> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goshippo.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Shippo is a multi-carrier shipping API. For agent integrations that execute shipping operations (rates, labels, tracking, address validation, customs), connect the hosted Shippo MCP server at https://mcp.shippo.com (per-user OAuth; setup at /guides/mcp-server). To search and read this documentation from an agent, a docs search MCP is available at https://docs.goshippo.com/mcp. Shipping workflow knowledge (agent skills and a knowledge pack) is published at https://github.com/goshippo/ai. For REST integrations start at /guides/api-quickstart; test mode uses shippo_test_ API keys.

# 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`.

> [!NOTE]
>
> **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](https://docs.goshippo.com/docs/Estimate/Estimate.md#filtering-results) for full details.

### Request — using `latest_delivery_date`

```sh theme={null}
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

```json theme={null}
{
  "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.

### Filter by required delivery date

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

```js theme={null}
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.");
}
```

> [!NOTE]
>
> **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`.


## Related topics

- [Rate shop with delivery dates](https://docs.goshippo.com/estimate/rate-shop-with-delivery-dates.md)
- [Estimate](https://docs.goshippo.com/estimate/estimate.md)
- [Display a delivery date](https://docs.goshippo.com/estimate/display-a-delivery-date.md)