Filter by required delivery date

Filter carriers or service levels that miss a required delivery date

Some orders have hard delivery requirements: same-day gifts, event merchandise, subscription boxes with commit dates. Rather than presenting all available rates and hoping customers pick correctly, you can use estimated_delivery_date_utc to filter out any service levels that would miss the required date before displaying options or purchasing a label.

How it works

Pass latest_delivery_date in the request body. The API compares this date against the UTC date component of each prediction’s estimated_delivery_date_utc and silently omits any service level whose estimate falls after the specified date. Only service levels that can meet the deadline appear in predictions.

Timezone note: latest_delivery_date is compared against the UTC date component of each estimate — not the local delivery date. If your deadline is expressed in a non-UTC timezone, apply the filter client-side after converting estimated_delivery_date_utc to the destination timezone. See Filtering Results for full details.

Request — using `latest_delivery_date`

curl --request POST \
  --url https://api.goshippo.com/v2/estimates \
  --header 'Authorization: ShippoToken <API_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "origin": {
      "zip": "95122"
    },
    "destination": {
      "zip": "94103"
    },
    "parcel": {
      "length": 10,
      "width": 8,
      "height": 4,
      "distance_unit": "in",
      "weight": 2,
      "mass_unit": "lb"
    },
    "planned_ship_date": "2026-05-01T17:00:00Z",
    "latest_delivery_date": "2026-05-03"
  }'

Service levels that cannot deliver by May 3 (UTC) are omitted from the response. Only eligible service levels are returned in predictions.

Response

{
  "object_id": "7a1b2c3d-...",
  "planned_ship_date": "2026-05-01T17:00:00Z",
  "confidence_level": "DEFAULT",
  "latest_delivery_date": "2026-05-03",
  "predictions": [
    {
      "provider": "FedEx",
      "servicelevel": {
        "name": "Priority Overnight",
        "token": "fedex_priority_overnight"
      },
      "estimated_delivery_date_utc": "2026-05-02T20:00:00Z",
      "estimated_transit_days": 1
    },
    {
      "provider": "USPS",
      "servicelevel": {
        "name": "Priority Mail",
        "token": "usps_priority"
      },
      "estimated_delivery_date_utc": "2026-05-03T20:00:00Z",
      "estimated_transit_days": 2
    }
  ],
  "test": false
}

Service levels that would have arrived after May 3 — such as UPS Ground — are not present in the response.

If your deadline is expressed as a local date rather than UTC, filter the predictions array yourself after timezone conversion.

const REQUIRED_LOCAL_DATE = "2026-05-03";
const DESTINATION_TIMEZONE = "America/Los_Angeles";

const eligiblePredictions = estimatesResponse.predictions.filter(prediction => {
  const localDate = new Date(prediction.estimated_delivery_date_utc)
    .toLocaleDateString("en-CA", { timeZone: DESTINATION_TIMEZONE }); // "YYYY-MM-DD"
  return localDate <= REQUIRED_LOCAL_DATE;
});

if (eligiblePredictions.length === 0) {
  console.warn("No service levels can meet the required delivery date.");
}

Purchasing a label: The Estimate API returns no pricing. Once you have the eligible servicelevel.token values, pass them to POST /shipments (optionally with carrier_accounts) to retrieve rates, then purchase a label via POST /transactions.

Overview

Get started

AI & agents

Guides

Concepts

Filter by required delivery date

Filter carriers or service levels that miss a required delivery date

How it works

Request — using `latest_delivery_date`

Response