---
title: "Merge shipments"
method: POST
path: "/v1/shipments/{shipment_id}/merge"
tags: ["shipments"]
---

# Merge shipments

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

## Request

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

Merge one or more shipments into the shipment in the URL. The items from each shipment in
`shipment_ids` move onto the shipment in the URL, and the shipments in `shipment_ids` are then
deleted.

The shipment in the URL stays linked to its own sales orders and becomes linked to the sales orders
of every shipment merged into it, so order sources keep getting shipment notifications. The merged
shipments can belong to different sales orders.

To merge shipments:

- Every shipment, including the one in the URL, must have a `shipment_status` of `pending`,
  `awaiting_payment`, or `on_hold`.
- Every shipment must be linked to a sales order. Check `sales_order_ids` on each shipment.
- None of the shipments can come from a marketplace that supplies its own shipping labels.

If `shipment_ids` includes the shipment in the URL or lists a shipment more than once, the extra
entries are ignored.

## Request body

- MergeShipmentsRequestBody: A request body for merging shipments into a shipment
  - `shipment_ids` SeId[], required: The shipments to merge into the shipment in the URL. At least one of them must be a shipment other than the one in the URL.

## Response `200`

The shipments were merged.

- MergeShipmentsResponseBody: A response body for merging shipments
  - `shipment_id` string: A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc.
  - `merged_shipment_ids` SeId[]: The shipments that were merged in. These shipments have been deleted.

## Other responses

- `400`: The request contained errors, or the shipments can't be merged. The `error_code` identifies the reason: | `error_code` | Reason | |---|---| | `invalid_field_value` | A value in the request can't be used. For example, `shipment_ids` contains only the shipment in the URL, or contains `null`. | | `invalid_status` | One of the shipments has already shipped, has been cancelled, or is in another status that can't be merged. | | `sales_order_link_required` | One of the shipments isn't linked to a sales order. | | `bring_your_own_label_not_supported` | One of the shipments comes from a marketplace that supplies its own shipping labels. | | `unspecified` | The merge was rejected for another reason. The `message` explains why. |
- `404`: The shipment in the URL, or one of the shipments in `shipment_ids`, 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/merge/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)