---
title: "Split a shipment"
method: POST
path: "/v1/shipments/{shipment_id}/split"
tags: ["shipments"]
---

# Split a shipment

`POST /v1/shipments/{shipment_id}/split`

## Request

- Base URL: `https://api.shipengine.com`
- URL: `https://api.shipengine.com/v1/shipments/{shipment_id}/split`
- Auth: API key in header `API-Key`

Move items from a shipment into one or more new shipments. Each entry in `shipments` creates one new
shipment holding the items and quantities listed for it. Items and quantities that you don't list
stay on the original shipment.

Each new shipment is based on the original shipment and stays linked to the same sales order, so
the order source keeps getting shipment notifications after the split.

To split a shipment:

- It must have a `shipment_status` of `pending`, `awaiting_payment`, or `on_hold`.
- It must be linked to a sales order. Check `sales_order_ids` on the shipment.
- It can't come from a marketplace that supplies its own shipping labels.
- All of the items you move must belong to the same sales order. To move items from more than one
  sales order, make one request for each sales order.
- At least one item must stay on the original shipment.

Get the `item_id` values from the `items` array of the shipment, using
[Get shipment by id](#operation/get_shipment_by_id).

## Request body

- SplitShipmentRequestBody: A request body for splitting a shipment into one or more new shipments
  - `shipments` object[], required: The new shipments to create. Each entry creates one new shipment that holds the listed items. Items and quantities that you don't list stay on the original shipment.
    - `items` object[], required: The items to move from the original shipment into this new shipment
      - `item_id` string, required: The `item_id` of an item on the original shipment, from the `items` array returned by [Get shipment by id](#operation/get_shipment_by_id). Each item can be listed only once in the same new shipment.
      - `quantity` integer, required: The number of units of the item to move into the new shipment. Across all new shipments, the total for an item can't be more than the quantity on the original shipment.

## Response `200`

The shipment was split.

- SplitShipmentResponseBody: A response body for splitting a shipment
  - `shipment_id` string: A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc.
  - `new_shipment_ids` SeId[]: The new shipments, in the same order as the `shipments` array in the request

## Other responses

- `400`: The request contained errors, or the shipment can't be split. The `error_code` identifies the reason: | `error_code` | Reason | |---|---| | `invalid_field_value` | A value in the request can't be used. For example, a quantity is larger than the quantity on the shipment, an item is listed twice in the same new shipment, or no items would stay on the original shipment. | | `invalid_identifier` | An `item_id` isn't on the shipment. | | `invalid_status` | The shipment has already shipped, has been cancelled, or is in another status that can't be split. | | `sales_order_link_required` | The shipment isn't linked to a sales order. | | `multiple_sales_orders` | The items you're moving belong to more than one sales order. | | `bring_your_own_label_not_supported` | The shipment comes from a marketplace that supplies its own shipping labels. | | `unspecified` | The split was rejected for another reason. The `message` explains why. |
- `404`: The `shipment_id` does not identify a shipment on this account.
- `500`: An error occurred on ShipStation API's side. > This error will automatically be reported to our engineers.

## Changes

- **2026-10-22** `e998dffc42be`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/shipstation/apis/shipengine-api/changes/v1/shipments/:shipment_id/split/post.md)

---

[API](https://skmtc.dev/shipstation/apis/shipengine-api.md) - [All operations](https://skmtc.dev/shipstation/apis/shipengine-api/llms.txt) - [OpenAPI document](https://skmtc.dev/shipstation/apis/shipengine-api/revisions/5d4d1c20776b?raw)