For the complete documentation index, see llms.txt. This page is also available as Markdown.

Examples

Copy-paste requests for a first quote.

Get a quote

This example quotes two items at 50.00 GBP and 1 kg each.

curl -sS -X POST 'https://deliveryratesbyzipcode.com/api/v1/rates' \
  -H 'Authorization: Bearer dbz_your_key_here' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "destination": {
      "address1": "5 Fanthorpe Lane",
      "city": "Louth",
      "province": "Lincolnshire",
      "postal_code": "LN11 0EB",
      "country": "GB"
    },
    "items": [
      { "quantity": 2, "grams": 1000, "price": 5000 }
    ]
  }'
async function getRates(destination, items) {
  const response = await fetch("https://deliveryratesbyzipcode.com/api/v1/rates", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.ZAPIET_RATES_API_KEY}`,
      "Content-Type": "application/json",
      Accept: "application/json",
    },
    body: JSON.stringify({ destination, items }),
  });

  if (response.status === 429) {
    const waitSeconds = Number(response.headers.get("Retry-After"));
    // Wait waitSeconds, then retry
    return null;
  }

  if (!response.ok) {
    throw new Error(`Rates request failed: ${response.status}`);
  }

  const { rates } = await response.json();
  return rates;
}

const rates = await getRates(
  { postal_code: "LN11 0EB", city: "Louth", country: "GB" },
  [{ quantity: 2, grams: 1000, price: 5000 }],
);

if (rates === null) {
  // Rate limited, try again later
} else if (rates.length === 0) {
  // No shipping available for this postal code and cart
} else {
  const rate = rates[0];
  // Dividing by 100 assumes a currency with 2 decimal places (GBP, USD, EUR).
  // Currencies such as JPY have none, so use total_price as it is.
  const amount = Number(rate.total_price) / 100; // e.g. 4.95
  const isFallback = rate.zone_name === "";
  const description = rate.description ?? "";
}

Example responses

A quote does not match checkout

Check that you sent the same postal code, item weights, prices and quantities that checkout would see. If they match and the price is still different, message us through the chat on zapiet.com with the request body and the time you sent it.