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

# Merge shipments

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

## Request

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

<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>

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 ShipStation 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.

## Changes

- **2026-10-22** `4e29670aa28d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/shipstation/apis/shipstation-api-v2/changes/v2/shipments/:shipment_id/merge/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/29d877316ed6?raw)