JavaScript / Node.js integration

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.

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 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 against a non-production delivery zone before going live

Related