Custom checkout integration

When to call the API

Call the API server-side during checkout validation — before presenting payment options and before any charge is attempted.

Code example

// Server-side only — never expose your API key in browser code
async function checkDelivery(postcode, basketValueCents) {
  const res = await fetch("https://api.deliveryzone.fi/api/v1/delivery/check", {
    method: "POST",
    headers: {
      "X-Api-Key": process.env.DZ_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ destinationPostcode: postcode, basketValueCents }),
  });
  return res.json();
}

Error handling

When canDeliver is false (or null), the response includes a reasonCode field. Display this to the customer:

• NOT_DELIVERABLE — postcode is outside your delivery zones, or not recognised (the API intentionally uses one generic code for both, to protect zone boundaries)
• MINIMUM_ORDER_NOT_MET — basket value is below the zone's minimum order
• BASKET_VALUE_REQUIRED — a basket value is needed to evaluate this destination's minimum-order or free-delivery rule

Always handle HTTP errors (5xx, timeout) gracefully. If the API is unreachable, fail safe — either reject the order or allow manual review.

Implementation checklist

• Call the API from your server, not the browser
• Store the API key as an environment variable
• Validate the postcode format (5 digits) before calling the API
• Handle API errors gracefully — do not let a timeout block checkout
• Test both in-zone and out-of-zone postcodes before launch

Related