Shopify integration guide

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.

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

• Use a Shopify custom app or Shopify Functions — not theme files
• Store the API key in environment variables or Shopify app secrets
• Test against a non-production delivery zone 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