WooCommerce integration guide

When to call the API

Call the API inside the woocommerce_package_rates or woocommerce_cart_shipping_packages filter — before shipping rates are returned to the customer.

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

• Store API key in WordPress options, not in theme files
• Test against a non-production delivery zone before going live
• Handle wp_remote_post errors and timeouts gracefully
• Log unexpected responses for debugging
• Confirm behaviour with out-of-zone postcodes before launch

Related