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"
}

429 Too Many Requests

Returned if you exceed your monthly plan limit or hit the rate limit.

{
  "canDeliver": false,
  "reasonCode": "PLAN_LIMIT_EXCEEDED",
  "reasonMessage": "Monthly API limit exceeded"
}

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 with a burst of 10 req/s. Exceeding the monthly quota returns HTTP 429 with QUOTA_EXCEEDED in the response body.

Delivery Zone API.