shipments

Hold shipments

Changed on Oct 9, 2026

Holds one or more shipments until a given date. A shipment on hold has the on_hold status, and you can't purchase a label for it while it's on hold. On the hold_until_date, the shipment is released automatically and returns to the pending status. You can hold up to 500 shipments at once.

hold_until_date is a date-only value: any time component you send is ignored, and the date must be later than today.

Shipments that cannot be held — because they are not found, are cancelled, or have a purchased label — are reported in errors, and the remaining shipments are still held. If only some of the shipments were held, the response status is 207. If none of them could be held, the response status is 404 when at least one shipment was not found, or 400 otherwise, and shipment_ids is empty.

To hold a single shipment, use Hold a shipment.

post/v1/shipments/hold

Request

Base URL: https://api.shipengine.com
URL: https://api.shipengine.com/v1/shipments/hold
Auth: API key in header API-Key

Request body

shipment_idsSeId[] required

Array of shipment IDs to hold

hold_until_datestring date required

The date to hold the shipments until. This is a date-only value — you can send a plain YYYY-MM-DD date, and any time component is ignored. The date must be later than today.

Example request

{
  "shipment_ids": [
    "se-202902255",
    "se-202902256"
  ],
  "hold_until_date": "2026-10-15"
}

Response

The request was a success.

shipment_idsSeId[]

Array of shipment IDs that were put on hold

hold_until_datestring date-time

The date the shipments are held until, returned at midnight. Absent when no shipment was held.

request_idstring uuid

A UUID (a.k.a. GUID) that uniquely identifies a resource

Example response

{
  "shipment_ids": [
    "se-202902255",
    "se-202902256"
  ],
  "hold_until_date": "2026-10-15T00:00:00Z",
  "errors": [
    {
      "error_source": "shipengine",
      "error_type": "validation",
      "error_code": "invalid_field_value",
      "message": "Body of request cannot be null.",
      "carrier_id": "se-28529731",
      "carrier_code": "dhl_express",
      "field_name": "shipment.ship_to.phone_number"
    }
  ],
  "request_id": "aa3d8e8e-462b-4476-9618-72db7f7b7009"
}

Changes

Oct 9, 2026020f57d6f5b8 Revision changes
- ▲
  the / request property's minLength was increased from 0 to 1
- ▲
  added the pattern ^se(-[a-z0-9]+)+$ to the request property /
- ▲
  the / request property type changed from no type to string
- ▲
  the / response's property type changed from no type to object for status
- ▲
  the / response's property type changed from no type to object for status
- ▲
  the / response's property type changed from no type to object for status
- ▲
  the / response's property type changed from no type to object for status
- ▲
  the / response's property type changed from no type to object for status
- ▲
  the / response's property type changed from no type to string for status
- ▲
  the / response's property type changed from no type to string for status
- ●
  removed from the / request property allOf list
- ●
  the / request property's maxLength was set to 25
- ○
  added the optional property // to the response with the status
- ○
  added the optional property // to the response with the status
- ○
  added the optional property // to the response with the status
- ○
  added the optional property // to the response with the status
- ○
  added the optional property // to the response with the status
- ○
  added the optional property // to the response with the status
- ○
  added the optional property // to the response with the status
- ○
  added the optional property // to the response with the status
- ○
  added the optional property // to the response with the status
- ○
  added the optional property // to the response with the status
- ○
  added the optional property // to the response with the status
- ○
  added the optional property // to the response with the status
- ○
  added the optional property // to the response with the status
- ○
  added the optional property // to the response with the status
- ○
  added the optional property // to the response with the status
- ○
  removed from the / response property allOf list for the response status
- ○
  removed from the / response property allOf list for the response status
- ○
  removed from the / response property allOf list for the response status
- ○
  removed from the / response property allOf list for the response status
- ○
  removed from the / response property allOf list for the response status
- ○
  removed from the / response property allOf list for the response status
- ○
  removed from the / response property allOf list for the response status
- ○
  the / response's property pattern ^se(-[a-z0-9]+)+$ was added for the status
- ○
  the / response's property pattern ^se(-[a-z0-9]+)+$ was added for the status
- ○
  added the required property // to the response with the status
- ○
  added the required property // to the response with the status
- ○
  added the required property // to the response with the status
- ○
  added the required property // to the response with the status
- ○
  added the required property // to the response with the status
- ○
  added the required property // to the response with the status
- ○
  added the required property // to the response with the status
- ○
  added the required property // to the response with the status
- ○
  added the required property // to the response with the status
- ○
  added the required property // to the response with the status
- ○
  added the required property // to the response with the status
- ○
  added the required property // to the response with the status
- ○
  added the required property // to the response with the status
- ○
  added the required property // to the response with the status
- ○
  added the required property // to the response with the status
- ○
  added the required property // to the response with the status
- ○
  added the required property // to the response with the status
- ○
  added the required property // to the response with the status
- ○
  added the required property // to the response with the status
- ○
  added the required property // to the response with the status
Oct 2, 202687db9f1b6ab1 Revision changes
- ○
  endpoint added

Operation history