Add postcode validation to Shopify

When to call the API

Call the API from your custom app backend during checkout, or from a Shopify Functions delivery-customization function. Always server-side — never from a storefront theme file.

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

• Use a Shopify custom app or Shopify Functions — not theme files
• Store the API key in environment variables or Shopify app secrets
• Test with sandbox key in a development store before activating
• Handle API errors gracefully so checkout does not break on failures
• Confirm out-of-zone rejection behaviour before going live

Related