ShippitDeveloper Centre

Estimated delivery dates API

The estimated delivery dates API returns estimated delivery times for different service levels based on origin and destination postcodes.

Endpoints

The estimate object

The response is an array of estimated delivery dates grouped by service level.

service_levelstringRequired
The service level for this estimate. Valid values are standard or express
estimated_deliveryobjectRequired
Estimated delivery window for this service level
Show child attributesHide child attributes
earlieststring (ISO 8601 date)Optional
The earliest estimated delivery date. null when confidence is none.
lateststring (ISO 8601 date)Optional
The latest estimated delivery date. null when confidence is none.
confidenceenumRequired
Confidence level for the estimate. See the confidence values table.
displaystringRequired
Pre-formatted delivery message ready to show customers. Render this directly—no client-side date logic required.

Confidence values

The confidence field indicates the reliability of the delivery window and controls how display reads.

ValueMeaningExample display
highearliest and latest are the same date. High accuracy estimate."Arrives Tue, Apr 20"
mediumearliest and latest differ by a moderate spread."Arrives Tue, Apr 20 - Wed, Apr 21"
lowWide spread between earliest and latest."Arrives by Mon, Apr 27"
noneNo data available for this route or service level. earliest and latest are null."3 to 5 business days"

Use the display string as-is for all confidence levels. It's pre-formatted server-side and requires no additional date logic.

Sample responseJSON
[
  {
    "service_level": "standard",
    "estimated_delivery": {
      "earliest": "2026-04-20",
      "latest": "2026-04-22",
      "confidence": "medium",
      "display": "Arrives Tue, Apr 20 - Thu, Apr 22"
    }
  },
  {
    "service_level": "express",
    "estimated_delivery": {
      "earliest": "2026-04-18",
      "latest": "2026-04-18",
      "confidence": "high",
      "display": "Arrives Sat, Apr 18"
    }
  }
]

Retrieve estimated delivery dates

POST/api/v3/estimated_delivery_dates

Submits a request to get estimated delivery dates for different service levels between specified postcodes.

At minimum, a request requires origin and destination postcodes. However, you can optionally filter by specific couriers, service levels, or provide additional context like fulfilment time or pickup schedules to get more accurate estimates. To estimate delivery for an order that already exists, rather than one placed now, send its order_date.

The API returns a delivery window for each available service level, including the earliest and latest estimated delivery dates, a confidence level, and a pre-formatted display string ready to show customers.

To perform this operation, you must be authenticated with an authentication token.

Parameters

from_postcodestringRequired
Origin postcode for the delivery estimate
to_postcodestringRequired
Destination postcode for the delivery estimate
couriersarray of stringsOptional
List of carrier strings to provide estimates for. If not provided, all available carriers are considered.
service_levelsarray of stringsOptional
An array of service levels to return estimates for. Valid values are standard or express.
preparation_timestringOptional
Lead time required for order fulfilment before pickup in format DD:HH:MM. For example, 01:05:30 is 1 day, 5 hours, and 30 minutes. Counts only while the store is open. See store_operating_hours.
order_datestring (ISO 8601 date-time)Optional
The date and time of the order, including a UTC offset or Z. For example, 2026-11-12T10:15:00+11:00. Defaults to the current time. See order date.
pickup_days_per_courierArray,see tableOptional
Pickup schedule for each carrier
store_operating_hoursarray of objectsOptional
Array of store operating hours

When you send store_operating_hours, include each day of the week exactly once. Set end_of_workday later than beginning_of_workday on the same day, because hours that run past midnight aren't supported.

preparation_time only counts during these hours. For example, a 24-hour preparation_time for a store open 9:00 AM to 5:00 PM takes three working days.

Show child attributesHide child attributes
dayenumRequired
The day of the week in lowercase. Possible values are monday, tuesday, wednesday, thursday, friday, saturday, sunday.
beginning_of_workdaystringRequired
The start time of the workday in HH:MM format
end_of_workdaystringRequired
The end time of the workday in HH:MM format
is_openbooleanRequired
Whether the store is open on the given day. Use true for open, false for closed.

Order date

Use order_date to calculate the estimate from the time of the order, instead of the time of the request.

The value must be an ISO 8601 date-time with a UTC offset, such as 2026-11-12T10:15:00+11:00 or 2026-11-11T23:15:00Z. A value without an offset, or a date without a time, returns a 422.

Send the offset that applied on that date. Sydney and Melbourne are +11:00 during daylight saving and +10:00 outside it. A hard-coded offset can shift the order by an hour, which is enough to miss a pickup and push the estimate out by a day. Sending UTC (Z) avoids the problem.

The pickup_days_per_courier array

Send one entry for each carrier, and describe its pickups in one of two ways:

  • The same pickup time every pickup day: send pickup_days and pickup_time
  • Different pickup times by day, or several pickups a day: send pickup_schedule

An entry can't use both. An entry with pickup_schedule and either pickup_days or pickup_time returns a 422.

courierstringRequired
Name of the carrier
pickup_daysarray of stringsOptional
Days when pickup is available, in lowercase. Required unless you send pickup_schedule.
pickup_timestringOptional
Time when pickup occurs, in format HH:MM. Required unless you send pickup_schedule.
pickup_scheduleobjectOptional
Pickup times for each day. Each key is a day of the week in lowercase, and each value is an array of one or more times in HH:MM format. Leave out days with no pickup.

Example pickup_schedule for a carrier that collects twice a day, with an earlier last pickup on Friday:

Pickup times are in the store's local time, based on from_postcode. The estimate uses the first pickup after the order is ready:

  • An order ready before a pickup time on a pickup day goes out that day. An order ready at exactly the pickup time catches the next one.
  • On a day with several pickup times, the estimate uses the earliest time after the order is ready. The order of the times in the array doesn't matter.
  • A carrier without an entry uses a default schedule of 9:00 AM, Monday to Friday, starting the day after the order is ready.
  • The estimate treats saturday and sunday pickups like any other day, but the estimated delivery date is always a business day.

An order is ready once preparation_time has passed during the store's opening hours. Preparation pauses while the store is closed, and an order placed before opening or after closing starts preparation at the next opening. For example, with a 9:00 AM opening and a 30-minute preparation_time, an order placed at 7:00 AM is ready at 9:30 AM, so it misses a 9:00 AM pickup that day.

If you leave out preparation_time and Shippit has fulfilment history for your account, the estimate uses your observed time from order to pickup instead and ignores pickup schedules.

Response codes

StatusMeaningDescription
200OKSuccessful delivery estimate response. Returns an empty array if no carrier is enabled for the merchant.
400Bad RequestThe request body isn't valid JSON
401UnauthorizedThe Authorization header is missing, or the API key doesn't match a valid merchant account. The response has no body.
422Unprocessable EntityA required parameter is missing, or a parameter is the wrong type. details names each field that failed.
429Too Many RequestsMore than 1000 requests in a minute for the same API key. The RateLimit-* response headers carry your remaining quota.
500Internal Server ErrorAn unknown error occurred
RequestJSON
{
  "from_postcode": "2000",
  "to_postcode": "3000",
  "couriers": ["CouriersPlease", "eParcelExpress"],
  "service_levels": ["standard", "express"],
  "preparation_time": "00:01:05",
  "order_date": "2026-11-12T10:15:00+11:00",
  "pickup_days_per_courier": [
    {
      "courier": "eParcelExpress",
      "pickup_schedule": {
        "monday": ["12:30", "18:30"],
        "tuesday": ["12:30", "18:30"],
        "wednesday": ["12:30", "18:30"],
        "thursday": ["12:30", "18:30"],
        "friday": ["12:30", "16:30"]
      }
    },
    {
      "courier": "CouriersPlease",
      "pickup_days": ["monday", "friday"],
      "pickup_time": "09:00"
    }
  ],
  "store_operating_hours": [
    { "day": "monday", "beginning_of_workday": "09:00", "end_of_workday": "17:00", "is_open": true },
    { "day": "tuesday", "beginning_of_workday": "09:00", "end_of_workday": "17:00", "is_open": true },
    { "day": "wednesday", "beginning_of_workday": "09:00", "end_of_workday": "17:00", "is_open": true },
    { "day": "thursday", "beginning_of_workday": "09:00", "end_of_workday": "17:00", "is_open": true },
    { "day": "friday", "beginning_of_workday": "09:00", "end_of_workday": "17:00", "is_open": true },
    { "day": "saturday", "beginning_of_workday": "10:00", "end_of_workday": "14:00", "is_open": true },
    { "day": "sunday", "beginning_of_workday": "10:00", "end_of_workday": "14:00", "is_open": false }
  ]
}
JSON
[
  {
    "service_level": "standard",
    "estimated_delivery": {
      "earliest": "2026-04-20",
      "latest": "2026-04-22",
      "confidence": "medium",
      "display": "Arrives Tue, Apr 20 - Thu, Apr 22"
    }
  },
  {
    "service_level": "express",
    "estimated_delivery": {
      "earliest": "2026-04-18",
      "latest": "2026-04-18",
      "confidence": "high",
      "display": "Arrives Sat, Apr 18"
    }
  }
]