Add postcode validation to WooCommerce

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.

Request example

// PHP — server-side, keep API key out of frontend
$r = wp_remote_post('https://api.deliveryzone.fi/v1/check', [
  'headers' => [
    'X-Api-Key'    => get_option('dz_api_key'),
    'Content-Type' => 'application/json',
  ],
  'body' => json_encode([
    'destinationPostcode' => $postcode,
    'basketValueCents'    => $basketCents,
  ]),
]);
$data = json_decode(wp_remote_retrieve_body($r), true);
if (!$data['canDeliver']) return [];
foreach ($rates as $rate) {
  $rate->cost = $data['priceCents'] / 100;
}

Error handling

When canDeliver is false, the response includes a reason field. Display this to the customer:

• OUT_OF_ZONE — postcode is valid but outside all defined zones
• UNKNOWN_POSTCODE — postcode is not recognised
• MIN_BASKET — basket value is below the zone minimum

Always handle HTTP errors (5xx, timeout) gracefully. If the API is unreachable, fail safe — either reject the order or allow manual review.

Production checklist

• Store API key in WordPress options, not in theme files
• Test with sandbox key 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