Estimate

​

Using the Estimate API

If you are interested in using Shippo’s Estimate API, or have any questions about pricing, please contact an expert. One call to POST https://api.goshippo.com/v2/estimates returns predicted delivery dates across carriers and service levels, before a label is purchased. Predictions come back sorted fastest first. Authenticate with Authorization: ShippoToken <API_TOKEN>.

​

Required parameters

Every request needs all of the following fields. Leave one out and you get a 422 telling you which field is missing. Two things trip people up more than anything else:

• distance_unit and mass_unit are required, not inferred. Sending dimensions and weight without their units is the single most common 422.
• planned_ship_date must carry a timezone. Both 2026-08-27T17:00:00Z and 2026-08-27T13:00:00-04:00 work. A naive datetime like 2026-08-27T17:00:00 returns a 422, and so does a date on its own.

You also can’t ship in the past, though the rule is friendlier than it sounds. We compare the date, not the timestamp, and we do it in whatever timezone you sent. So at 11am you can still pass 9am today. You just can’t pass yesterday.

​

Optional parameters

Behavior worth knowing before you build against it:

• Unrecognized tokens in servicelevel_tokens are skipped, and each one comes back in the response’s messages array with the code servicelevel_unsupported. If every token you send is unrecognized, you get a 422 instead.
• If latest_delivery_date filters out everything, you get a 200 with an empty predictions array. That’s a success, not an error.
• We return every supported service level regardless of which carrier accounts you have connected. We don’t have your carrier account context in this call, so filtering to what you actually ship is your side of the job.

​

Picking parameters for your use case

We don’t model carrier cutoff times, so planned_ship_date is where you encode yours. Pass the moment the package realistically enters the carrier network. If an order lands after your daily handoff, bump the date to the next business day and call again. We don’t currently support Saturday-delivery upgrades for service levels that do support it.

​

Timezone of the estimates

We return estimated_delivery_date_utc in UTC. Always. Convert it before you show it to anyone. This matters more than it sounds. 2026-03-24T03:00:00Z is March 24 in UTC but March 23 in Los Angeles. If you slice the date off the UTC string and display it, you’ll be a day off for a meaningful share of your West Coast buyers. The same boundary applies to filtering. latest_delivery_date compares against the UTC date, so for example, an estimate of 2026-04-12T03:00:00Z has a UTC date of April 12th but is April 11th in America/Los_Angeles. The filter would exclude it if latest_delivery_date is 2026-04-11, even though the package arrives on April 11th locally. Timezone-aware filtering is on the roadmap. estimated_transit_days is the number of calendar days between your planned ship date and the predicted delivery date, returned as a whole number of days (e.g. 2.0). The dates are counted based on their local calendars to match what the sender and the recipient each see locally, which is why adding estimated_transit_days to your planned_ship_date will not always produce the date portion of estimated_delivery_date_utc. Use estimated_delivery_date_utc as the authoritative delivery date, with estimated_transit_days as a display-friendly duration.

​

Confidence levels

Pass confidence_level to control how conservative the estimate is. Omit it, and you get DEFAULT. The response echoes back whichever level was applied. Values are uppercase. Each call returns a single confidence level - the DEFAULT, or the one you selected. To receive more than one confidence level, you will need to make multiple calls (each of which is billed separately). None of these are guarantees. They’re predictions trained on real delivery outcomes, and carrier performance varies. Only certain services carry a carrier money-back guarantee, at the carrier’s discretion.

​

Service levels supported

We support 29 service levels at GA, covering roughly 92 percent of the volume shipped through Shippo. Refer to Supported service levels for valid servicelevel_tokens values for each support service level.

• USPS Ground Advantage, Priority Mail, Priority Mail Express, Media Mail
• UPS Ground, Ground Saver, 2nd Day Air®, 2nd Day Air A.M.®, 3 Day Select®, Next Day Air®, Next Day Air Saver®, Next Day Air® Early, SurePost, SurePost Lightweight
• FedEx Ground, Home Delivery, Ground Economy, Smartpost®, 2Day, 2Day A.M., Express Saver®, Standard Overnight®, Priority Overnight®, First Overnight®
• Regional carriers OnTrac Ground, LaserShip Ground, AxleHire Next Day, Veho Ground Plus, Veho Premium Economy

Estimates are for US domestic shipments only, and for single-piece shipments only.

​

Before going live

The Estimate API is built to sit on your critical path — gating a shipping choice, or checkout itself, on a returned delivery date is a supported way to use it. But like any network dependency, it will occasionally be slow or unavailable. A production integration is one where that moment degrades gracefully instead of stalling a purchase. That resilience comes down to five controls - all standard in HTTP and resilience libraries, so defaults are a fine starting point:

​

Two things that surprise people

• A 200 can be partial. Success doesn’t guarantee every service level you asked for is present; missing ones are explained in messages[] — prediction_unavailable (transient; that service level is temporarily unavailable) or servicelevel_unsupported (non-transient; that token isn’t supported). Apply your fallback per service level (full schema in the API reference).
• Successful calls are billable; failed ones aren’t. Retrying a genuine failure costs nothing. The one way a retry double-bills is if your client times out on a call that actually succeeded — which is why the read timeout should be generous enough not to cut off a normal response, and number of retries should be capped.

​

Pre-launch checklist

• Read timeout set; total wait bounded to your customer’s patience
• Circuit breaker and bulkhead configured for every use case
• Retry capped at one, and only where a fresh date beats the fallback
• A real fallback in place, served instantly
• Partial 200 / messages[] handled for the service levels you depend on
• Subscribed to the Shippo status page

​

What the API doesn’t do yet

No batch endpoint, no delivery date ranges, no carrier-level filtering, no multi-piece shipments, and no international lanes. The object_id in the response is a correlation ID for support, not something you can fetch later. Test tokens return placeholder predictions rather than real ones, and test calls aren’t billed.