--- title: "Hold shipments" method: POST path: "/v2/shipments/hold" tags: ["shipments"] --- # Hold shipments `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` 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](#operation/hold_shipment). ## Request body - HoldShipmentsRequestBody: A request body for holding one or more shipments - `shipment_ids` SeId[], required: Array of shipment IDs to hold - `hold_until_date` string, 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. ## Response `200` The request was a success. - HoldShipmentsResponseBody: A response body for holding one or more shipments - `shipment_ids` SeId[]: Array of shipment IDs that were put on hold - `hold_until_date` string, date-time: The date the shipments are held until, returned at midnight. Absent when no shipment was held. - `errors` Error[]: The shipments that could not be held, with the reason for each. Empty when every shipment was processed. - `error_source` 'carrier' | 'order_source' | 'ShipStation' | 'shipengine', required: The source of the error, as indicated by the name this informs us if the API call failed because of the carrier, the order source, the ShipStation API itself, or the underlying ShipEngine platform. - `error_type` 'account_status' | 'business_rules' | 'validation' | 'security' | 'system' | 'integrations', required: The type of error - `error_code` 'auto_fund_not_supported' | 'batch_cannot_be_modified' | 'bring_your_own_label_not_supported' | 'carrier_conflict' | 'carrier_disconnected' | 'carrier_not_connected' | 'carrier_not_supported' | 'confirmation_not_supported' | 'default_warehouse_cannot_be_deleted' | 'field_conflict' | 'field_value_required' | 'forbidden' | 'identifier_conflict' | 'identifiers_must_match' | 'insufficient_funds' | 'invalid_address' | 'invalid_billing_plan' | 'invalid_field_value' | 'invalid_identifier' | 'invalid_status' | 'invalid_string_length' | 'label_images_not_supported' | 'meter_failure' | 'multiple_sales_orders' | 'order_source_not_active' | 'rate_limit_exceeded' | 'refresh_not_supported' | 'request_body_required' | 'return_label_not_supported' | 'sales_order_link_required' | 'settings_not_supported' | 'subscription_inactive' | 'terms_not_accepted' | 'tracking_not_supported' | 'trial_expired' | 'unauthorized' | 'unknown' | 'unspecified' | 'verification_failure' | 'warehouse_conflict' | 'webhook_event_type_conflict' | 'customs_items_required' | 'incompatible_paired_labels' | 'invalid_charge_event' | 'invalid_object' | 'no_rates_returned' | 'freight_connection_inactive' | 'freight_provider_id_required' | 'freight_shipment_not_found' | 'freight_tracking_not_available' | 'freight_tracking_not_found' | 'freight_shipment_not_batchable' | 'freight_provider_already_connected', required: The error code specified for the failed API Call - `message` string, required: An error message associated with the failed API call - `field_name` string: The name of the field that caused the error (only present for validation errors) - `field_value` string: The invalid value that was provided for the field (only present for validation errors) - `request_id` string, uuid: A UUID (a.k.a. GUID) that uniquely identifies a resource ## Other responses - `207`: The request was a partial success. Some shipments were not held; see `errors`. - `400`: The request contained errors. - `404`: The specified resource does not exist. - `500`: An error occurred on ShipStation API's side. ## Changes - **2026-10-22** `4e29670aa28d`: 12 warning - added the new `bring_your_own_label_not_supported` enum value to the `errors/items/error_code` response property for the response status `200` - added the new `bring_your_own_label_not_supported` enum value to the `errors/items/error_code` response property for the response status `207` - added the new `bring_your_own_label_not_supported` enum value to the `errors/items/error_code` response property for the response status `400` - added the new `bring_your_own_label_not_supported` enum value to the `errors/items/error_code` response property for the response status `404` - …8 more - **2026-10-09** `934f5935dbea`: 9 breaking, 2 warning, 32 info - the `shipment_ids/items/` request property's minLength was increased from `0` to `1` - added the pattern `^se(-[a-z0-9]+)+$` to the request property `shipment_ids/items/` - the `shipment_ids/items/` request property type changed from no type to `string` - the `errors/items/` response's property type changed from no type to `object` for status `200` - …39 more - **2026-10-02** `0cf052f808b4`: 1 info - endpoint added [Operation history](https://skmtc.dev/shipstation/apis/shipstation-api-v2/changes/v2/shipments/hold/post.md) --- [API](https://skmtc.dev/shipstation/apis/shipstation-api-v2.md) - [All operations](https://skmtc.dev/shipstation/apis/shipstation-api-v2/llms.txt) - [OpenAPI document](https://skmtc.dev/shipstation/apis/shipstation-api-v2/revisions/43d0f3c948ca?raw)