Integration guide
PHP integration
The Delivery Zone API accepts a JSON POST and returns a JSON response. Call it using file_get_contents with a stream context, cURL, or wp_remote_post in WordPress.
When to call the API
Call the API inside your PHP request handling code — in a controller, a WordPress filter, or an API endpoint. Always server-side.
Important: keep API keys server-side: Never expose the API key in JavaScript output, HTML source, or any client-visible file. Store it in a config file outside the web root, an environment variable, or WordPress options.
Code example
// PHP — server-side, keep API key out of frontend
$response = wp_remote_post('https://api.deliveryzone.fi/api/v1/delivery/check', [
'headers' => [
'X-Api-Key' => get_option('dz_api_key'),
'Content-Type' => 'application/json',
],
'body' => wp_json_encode([
'destinationPostcode' => $postcode,
'basketValueCents' => $basket_cents,
]),
]);
$data = json_decode(wp_remote_retrieve_body($response), true);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 orderBASKET_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
- Store API key in an environment variable or WordPress option
- Validate postcode is 5 digits before calling the API
- Handle cURL/wp_remote_post errors and non-200 responses
- Test against a non-production delivery zone first
- Confirm WooCommerce rejection behaviour if using WooCommerce
Ready to add postcode validation?
Free plan. No credit card. Real setup help.