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

# Schedule warehouse ship-out dates

## Inform warehouse systems of the ideal ship-out date

Use `planned_ship_date` and `estimated_transit_days` together to schedule warehouse tasks and enforce fulfillment cutoffs.

Knowing a predicted delivery date is only useful if your warehouse knows the latest date an order can be picked, packed, and handed to the carrier to achieve it. The Estimate API's `planned_ship_date` is the ship-out date you are committing to, and `estimated_transit_days` tells you the transit window from that date. Together they enable automated warehouse task creation, pick queue prioritization, and same-day cutoff enforcement.

### How it works

When you call `POST /v2/estimates`, pass the `planned_ship_date` that reflects your intended handoff to the carrier — typically today's date at the warehouse's daily carrier pickup or drop-off cutoff time. The response echoes `planned_ship_date` back in UTC and returns `estimated_transit_days` on each prediction, so you can calculate and display the full fulfillment timeline.

For warehouse scheduling, `planned_ship_date` is the ship-by target. Your system must create and complete the pick/pack task before that datetime.

### Request

Pass the warehouse cutoff time as the `planned_ship_date`. In this example, the warehouse closes carrier handoffs at 3:00 PM PDT (22:00 UTC).

```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-01T22:00:00Z"
  }'
```

### Response

```json theme={null}
{
  "object_id": "2b3c4d5e-...",
  "planned_ship_date": "2026-05-01T22:00:00Z",
  "confidence_level": "DEFAULT",
  "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
    },
    {
      "provider": "UPS",
      "servicelevel": {
        "name": "Ground",
        "token": "ups_ground"
      },
      "estimated_delivery_date_utc": "2026-05-05T20:00:00Z",
      "estimated_transit_days": 4
    }
  ],
  "test": false
}
```

### Push tasks to your warehouse system

Once the customer selects a service level at checkout, extract `planned_ship_date` and `estimated_transit_days` from the matching prediction and send them downstream to your warehouse management system (WMS) or fulfillment queue.

```js theme={null}
const CUSTOMER_SELECTED_TOKEN = "usps_priority";
const WAREHOUSE_TIMEZONE = "America/Los_Angeles";

// Find the prediction matching what the customer chose
const selectedPrediction = estimatesResponse.predictions.find(
  p => p.servicelevel.token === CUSTOMER_SELECTED_TOKEN
);

// A partial response can omit a service level. Check messages[] for the reason.
if (!selectedPrediction) {
  throw new Error(`No prediction for ${CUSTOMER_SELECTED_TOKEN}`);
}

// planned_ship_date is the cutoff the warehouse must meet
const shipByLocal = new Date(estimatesResponse.planned_ship_date)
  .toLocaleString("en-US", {
    timeZone: WAREHOUSE_TIMEZONE,
    dateStyle: "short",
    timeStyle: "short"
  });

const warehouseTask = {
  orderId: order.id,
  carrier: selectedPrediction.provider,
  service: selectedPrediction.servicelevel.name,
  servicelevelToken: selectedPrediction.servicelevel.token,
  shipBy: estimatesResponse.planned_ship_date,     // "2026-05-01T22:00:00Z" — UTC for storage
  shipByLocal: shipByLocal,                        // "5/1/26, 3:00 PM" — local time for display
  estimatedDeliveryUtc: selectedPrediction.estimated_delivery_date_utc,
  transitDays: selectedPrediction.estimated_transit_days,
  priority: isCutoffApproaching(estimatesResponse.planned_ship_date) ? "URGENT" : "STANDARD",
};

// Send to your WMS or fulfillment queue
await warehouseQueue.enqueue(warehouseTask);
```

### Enforce carrier cutoff times

The `planned_ship_date` you pass into the request defines the cutoff. If an order is placed after your warehouse's daily carrier handoff time, bump `planned_ship_date` to the next day's cutoff (skip days your warehouse is closed) and re-call the endpoint — the delivery date predictions will update accordingly.

```js theme={null}
function getNextShipDate(cutoffHourUTC = 22) {
  const now = new Date();
  const cutoff = new Date(now);
  cutoff.setUTCHours(cutoffHourUTC, 0, 0, 0);

  // If we've passed today's cutoff, ship tomorrow
  if (now >= cutoff) {
    cutoff.setUTCDate(cutoff.getUTCDate() + 1);
  }
  return cutoff.toISOString();
}

function isCutoffApproaching(plannedShipDateUtc, warningWindowMinutes = 60) {
  const cutoff = new Date(plannedShipDateUtc);
  const now = new Date();
  const msUntilCutoff = cutoff - now;
  return msUntilCutoff > 0 && msUntilCutoff <= warningWindowMinutes * 60 * 1000;
}

// Use the result as planned_ship_date in your estimates request
const plannedShipDate = getNextShipDate(22); // 22:00 UTC = 3 PM PDT (2 PM PST)
```

> [!TIP]
>
> For orders with tight fulfillment windows, consider calling the Estimate API with `confidence_level: "HIGH"`(see [Provide conservative commit dates](https://docs.goshippo.com/estimate/use-high-confidence-estimates.md)) so the predicted delivery date accounts for real-world variability before you commit it to the customer.


## Related topics

- [Date intervals](https://docs.goshippo.com/reporting-api/intervals.md)
- [Estimate](https://docs.goshippo.com/estimate/estimate.md)
- [Filter by required delivery date](https://docs.goshippo.com/estimate/filter-by-delivery-date.md)