API Docs — Delivery Zone

Public Delivery Check API Contract

This API is used by external systems (custom backends, checkouts, or ERPs) to check if a postcode is deliverable based on your configured delivery zones and rules.

[!WARNING] Permitted use — real-time validation only. API responses must not be stored, cached, bulk-collected, exported, resold, or used to create, enrich, reconstruct, or replace any postcode, address, distance, delivery-zone, geographic, or similar dataset. Automated scraping, systematic enumeration, or bulk querying of the API is prohibited. Full restrictions: API Terms of Use and Acceptable Use Policy.

<strong>Note.</strong> The Finland postcode dataset is centrally managed by Gn-Projects / Delivery Zone. Customers do not upload, export, or download raw postcode data. The API returns delivery decisions based on this central dataset and your specific zone rules. Beta dataset note: During private beta, the active postcode dataset uses licensed third-party Finnish postcode reference data. Coordinates are estimated centroid values and are provided without accuracy warranty.

Endpoint

POST /api/v1/delivery/check

Headers

X-Api-Key: Your public API key.
Content-Type: application/json

Request Body

{
  "destinationPostcode": "00100",
  "basketValueCents": 4500
}

Success Responses (200 OK)

A 200 OK is returned for any valid check that completes, regardless of whether delivery is possible.

Deliverable

{
  "canDeliver": true,
  "matchedZoneName": "Helsinki Center",
  "priceCents": 590,
  "currency": "EUR",
  "estimatedDeliveryMinutes": 45,
  "reasonCode": "DELIVERABLE",
  "reasonMessage": "Delivery is available."
}

Not Deliverable

{
  "canDeliver": false,
  "reasonCode": "NOT_DELIVERABLE",
  "reasonMessage": "Delivery is not available for this postcode."
}

Not Deliverable — Minimum Order Not Met

{
  "canDeliver": false,
  "reasonCode": "BASKET_VALUE_TOO_LOW",
  "reasonMessage": "The location is covered, but the minimum order value was not met."
}

<strong>Note.</strong> All non-deliverable outcomes that relate to postcode coverage or zone configuration return the generic NOT_DELIVERABLE reason code. This is intentional. Internal zone identifiers, raw distances, and postcode dataset membership signals are never included in the public API response.

Error Responses

400 Bad Request

The request was malformed or the postcode format was fundamentally invalid.

{
  "canDeliver": false,
  "reasonCode": "INVALID_POSTCODE",
  "reasonMessage": "The provided postcode format is invalid."
}

401 Unauthorized

{
  "error": "Invalid API key"
}

402 Payment Required

Your organisation's monthly plan quota has been exhausted. Upgrade your plan or wait for your quota to reset at the start of the next billing period. Do not retry this request automatically — the result will not change until your quota resets or your plan is upgraded.

{
  "canDeliver": false,
  "reasonCode": "PLAN_LIMIT_EXCEEDED",
  "reasonMessage": "Your plan's API quota has been exhausted. Please upgrade your plan or wait for your quota to reset."
}

429 Too Many Requests

Your requests are arriving faster than your plan's per-minute rate limit allows. Back off and retry after a short delay. This is a temporary condition — no plan change is required.

{
  "canDeliver": false,
  "reasonCode": "RATE_LIMITED",
  "reasonMessage": "Too many requests. Please slow down and try again shortly."
}

503 Service Unavailable

The system is currently unable to process requests (e.g. no active central dataset).

{
  "canDeliver": false,
  "reasonCode": "NO_ACTIVE_DATASET",
  "reasonMessage": "Service temporarily unavailable."
}

Authentication

All requests require an X-Api-Key header. Get your key by creating a free account. Keys are scoped per environment and can be rotated from the dashboard.

Rate limits

Rate limits vary by plan. The Free plan allows 500 checks per month. Exhausting your monthly quota returns HTTP 402 Payment Required with PLAN_LIMIT_EXCEEDED — upgrade your plan or wait for the next billing period. Exceeding your per-minute request rate returns HTTP 429 Too Many Requests — back off and retry.

Delivery Zone API.