Integration guide
JavaScript / Node.js integration
The Delivery Zone API is a JSON endpoint. Call it from fetch or axios in Node.js — in an Express route, a Next.js API route, a Netlify function, or any server-side JavaScript runtime.
When to call the API
Call the API inside your server-side route handler — not in React/Vue components or client-side scripts. The API key must stay on the server.
Important: keep API keys server-side: Never call the API from browser-side JavaScript. Your API key must live in a server environment variable. A
NEXT_PUBLIC_ prefix, for example, would expose it — do not do that.
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 orderBASKET_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 inside a server-side route, not a client component
- Store the key in
.envasDZ_KEY— never prefix it with NEXT_PUBLIC_ - Handle fetch errors and non-200 responses
- Validate postcode format before calling the API
- Test against a non-production delivery zone before going live
Ready to add postcode validation?
Free plan. No credit card. Real setup help.