# Merge shipments

Products
            Plans
          
        
        
          
            
              
              Formerly ShipEngine
            
            
              Free
              Advanced
              Enterprise
            
          
          
            
              
            
            
              Free
              Starter
              Standard
              Premium
            
          
        
      
      
        
          Learn about products and plans
          
        
      
    

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.

Endpoint: POST /v2/shipments/{shipment_id}/merge
Version: 2.0.0
Security: api_keys

## Path parameters:

  - `shipment_id` (string, required)
    Shipment ID
    Example: "se-28529731"

## Request fields (application/json):

  - `shipment_ids` (array, 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.
    Example: ["se-202902301","se-202902302"]

## Response 200 fields (application/json):

  - `shipment_id` (string)
    The shipment that now holds all of the items
    Example: "se-28529731"

  - `merged_shipment_ids` (array)
    The shipments that were merged in. These shipments have been deleted.
    Example: ["se-202902301","se-202902302"]

## Response 400 fields (application/json):

  - `request_id` (string, required)
    A UUID that uniquely identifies the request id.
This can be given to the support team to help debug non-trivial issues that may occur
    Example: "aa3d8e8e-462b-4476-9618-72db7f7b7009"

  - `errors` (array, required)
    The errors associated with the failed API call

  - `errors.error_source` (string, 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.
    Enum: "carrier", "order_source", "ShipStation", "shipengine"

  - `errors.error_type` (string, required)
    The type of error
    Enum: "account_status", "business_rules", "validation", "security", "system", "integrations", "funding_sources"

  - `errors.error_code` (string, required)
    The error code specified for the failed API Call
    Enum: "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", "funding_source_missing_configuration"

  - `errors.message` (string, required)
    An error message associated with the failed API call
    Example: "Body of request cannot be null."

  - `errors.field_name` (string)
    The name of the field that caused the error (only present for validation errors)
    Example: "inventory_warehouse_id"

  - `errors.field_value` (string)
    The invalid value that was provided for the field (only present for validation errors)
    Example: "invalid-id"