Integrate postcode validation into any custom checkout

When to call the API

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

Request example

// Server-side only — never expose your API key in browser code
const res = await fetch('https://api.deliveryzone.fi/v1/check', {
  method: 'POST',
  headers: {
    'X-Api-Key': process.env.DZ_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ destinationPostcode: postcode, basketValueCents: basket }),
});
const data = await res.json();
if (!data.canDeliver) {
  showError(data.reason); // e.g. "OUT_OF_ZONE"
} else {
  setShippingFee(data.priceCents);
}

Error handling

When canDeliver is false, the response includes a reason field. Display this to the customer:

• OUT_OF_ZONE — postcode is valid but outside all defined zones
• UNKNOWN_POSTCODE — postcode is not recognised
• MIN_BASKET — basket value is below the zone minimum

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

Production 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