Estimated delivery dates

The estimated delivery dates API helps you provide customers with accurate delivery estimates before they place an order.

Where carriers often provide broad estimates using the quote API, the estimated delivery dates API calculates highly accurate delivery windows. The API uses AI models that are trained on millions of real deliveries, in conjunction with your individual shipping history and carrier mix, to provide highly accurate delivery estimates. The API is designed to be lightweight and fast, making it suitable for real-time integration into your product, checkout, and tracking pages. Accurate delivery estimates can help build loyalty with new and returning customers, while reducing cart abandonment.

Use the estimated delivery dates API when you need to:

• Provide delivery estimates for product pages or category listings
• Display delivery estimates during checkout without showing shipping costs

At minimum, you need provide an origin and destination postcode, using from_postcode and to_postcode.

To get more accurate estimates, you can provide additional parameters:

Parameter	Description
service_levels	Filter results to specific service levels
couriers	Limit estimates to specific courier services
preparation_time	Account for your internal processing time before pickup
pickup_days_per_courier	Specify pickup schedules for different couriers
store_operating_hours	Include your store’s operating hours in the calculation

The API returns an array of delivery estimates, with each estimate containing the service level and the estimated number of business days for delivery . Example payload:

[
  {
    "service_level": "standard",
    "estimated_delivery_days": 4
  },
  {
    "service_level": "express",
    "estimated_delivery_days": 3
  },
  {
    "service_level": "on_demand",
    "estimated_delivery_days": 1
  }
]

For more information, see the estimated delivery dates API reference.

Best practices

The estimated delivery API endpoint is designed to be lightweight, but if you need to improve performance further, there are a few places where you can implement caching:

• Cache estimates for popular postcode combinations
• Use a time to live (TTL) of 4-24 hours depending on your needs
• Cache at the service level to allow for flexible display options

Implementing robust error handling helps you to avoid network issues, and throwing errors if an invalid postcode is passed. For example:

try {
  const estimates = await fetchDeliveryEstimates(fromPostcode, toPostcode);
  return estimates;
} catch (error) {
  if (error.status === 400) {
    // Invalid postcode - show error message
    showError("Please enter a valid postcode");
  } else {
    // Network or server error - show fallback message
    showError("Unable to calculate delivery times. Please try again.");
  }
}