shipments

Hold shipments

Changed on Oct 22, 2026

<aside class="access" aria-label="Endpoint access"> <table class="access__table"> <thead> <tr> <th class="access__table-header">Products</th> <th class="access__table-header">Plans</th> </tr> </thead> <tbody> <tr> <td class="access__table-cell access__product"> <img class="access__logo" src="/static/logos/shipstation-api-logo.svg" alt="ShipStation API Logo" loading="lazy" decoding="async"/> <div class="access__sub">Formerly ShipEngine</div> </td> <td class="access__table-cell access__plans"> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-api-free.md" class="access__plan">Free</a> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-api-advanced-enterprise.md" class="access__plan">Advanced</a> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-api-advanced-enterprise.md" class="access__plan">Enterprise</a> </td> </tr> <tr> <td class="access__table-cell"> <img class="access__logo" src="/static/logos/shipstation-logo.svg" alt="ShipStation Logo" loading="lazy" decoding="async"/> </td> <td class="access__table-cell access__plans"> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-free-starter.md" class="access__plan access__plan--off">Free</a> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-free-starter.md" class="access__plan access__plan--off">Starter</a> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-standard-premium.md" class="access__plan">Standard</a> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-standard-premium.md" class="access__plan">Premium</a> </td> </tr> </tbody> </table> <footer class="access__footer"> <a class="access__help" href="/apis/@shipstation-v2/docs/getting-started/products-and-plans.md"> Learn about products and plans <img src="/static/icons/external-link.svg" alt="External Link Icon" style="width: 16px;" loading="lazy" decoding="async"/> </a> </footer> </aside>

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/v2/shipments/hold

Request

Base URL
https://api.shipstation.com
URL
https://api.shipstation.com/v2/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": [
    {
      "message": "Body of request cannot be null.",
      "field_name": "inventory_warehouse_id",
      "field_value": "invalid-id"
    }
  ],
  "request_id": "aa3d8e8e-462b-4476-9618-72db7f7b7009"
}

Changes

Oct 22, 20264e29670aa28d Revision changes
- warning
  added the new bring_your_own_label_not_supported enum value to the // response property for the response status
- warning
  added the new bring_your_own_label_not_supported enum value to the // response property for the response status
- warning
  added the new bring_your_own_label_not_supported enum value to the // response property for the response status
- warning
  added the new bring_your_own_label_not_supported enum value to the // response property for the response status
- warning
  added the new multiple_sales_orders enum value to the // response property for the response status
- warning
  added the new multiple_sales_orders enum value to the // response property for the response status
- warning
  added the new multiple_sales_orders enum value to the // response property for the response status
- warning
  added the new multiple_sales_orders enum value to the // response property for the response status
- warning
  added the new sales_order_link_required enum value to the // response property for the response status
- warning
  added the new sales_order_link_required enum value to the // response property for the response status
- warning
  added the new sales_order_link_required enum value to the // response property for the response status
- warning
  added the new sales_order_link_required enum value to the // response property for the response status
Oct 9, 2026934f5935dbea Revision changes
- breaking
  the / request property's minLength was increased from 0 to 1
- breaking
  added the pattern ^se(-[a-z0-9]+)+$ to the request property /
- breaking
  the / request property type changed from no type to string
- breaking
  the / response's property type changed from no type to object for status
- breaking
  the / response's property type changed from no type to object for status
- breaking
  the / response's property type changed from no type to object for status
- breaking
  the / response's property type changed from no type to object for status
- breaking
  the / response's property type changed from no type to string for status
- breaking
  the / response's property type changed from no type to string for status
- warning
  removed from the / request property allOf list
- warning
  the / request property's maxLength was set to 25
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  removed from the / response property allOf list for the response status
- info
  removed from the / response property allOf list for the response status
- info
  removed from the / response property allOf list for the response status
- info
  removed from the / response property allOf list for the response status
- info
  removed from the / response property allOf list for the response status
- info
  removed from the / response property allOf list for the response status
- info
  the / response's property pattern ^se(-[a-z0-9]+)+$ was added for the status
- info
  the / response's property pattern ^se(-[a-z0-9]+)+$ was added for the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status

Operation history (3 revisions)