Call the Delivery Zone API from Node.js

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.

Get free API key API reference

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.

API key security: 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.

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 inside a server-side route, not a client component
Store the key in .env as DZ_KEY — never prefix it with NEXT_PUBLIC_
Handle fetch errors and non-200 responses
Validate postcode format before calling the API
Test with sandbox key before switching to live key

Ready to integrate?

Create a free account and get your sandbox API key in minutes.

Create free account Read API docs

Custom checkout guide Example: check postcode API reference