Create Shipments

Create one or more shipments to prepare packages for label generation and tracking. Shipments contain all the information needed to ship packages including origin, destination, carrier preferences, and package details.

Coming from v1 or the ShipStation UI?

In v2, what you might know as "orders" are called "shipments". This guide shows you how to create shipments (orders) using the v2 API.

Key identifiers to understand:

external_shipment_id - Your system's unique identifier (maps to v1 orderKey)
shipment_number - User-friendly display number (maps to v1 orderNumber)
external_order_id - ShipStation UI order ID (optional, now settable)

Important behaviors:

If you don't provide external_shipment_id, it will be auto-generated as se-{shipment_id}
If you provide external_shipment_id but not shipment_number, the shipment_number will duplicate the external_shipment_id value
Both external_shipment_id and shipment_number must be unique per account

For complete details, see:

Create Shipments

Use the POST method with /v2/shipments to create one or more shipments. This endpoint accepts an array of shipments, allowing you to create multiple shipments in a single request.

Request Body Properties

The request body contains a shipments array. Each shipment object supports the following properties:

Property	Type	Required	Description
`ship_to`	object	Required	Recipient shipping address
`ship_from`	object	Required	Origin shipping address
`packages`	array	Required	Package dimensions and weight (minimum 1 package)
`external_shipment_id`	string	Optional	Your internal shipment identifier (max 50 characters)
`carrier_id`	string	Optional	Carrier account to use for shipping
`service_code`	string	Optional	Specific carrier service (e.g., `fedex_ground`, `usps_priority_mail`)
`items`	array	Optional	Shipment line items with product details
`shipment_status`	string	Optional	Initial status: `pending`, `processing`, `label_purchased`, `cancelled`
`advanced_options`	object	Optional	Advanced shipping options (signature, Saturday delivery, etc.)
`customs`	object	Optional	International shipment customs information. Many countries have specific requirements for customs descriptions, tax IDs, and documentation. See Country-Specific Shipping Requirements for details.
`insurance_provider`	string	Optional	Insurance provider: `none`, `shipsurance`, `parcelguard`, `xcover`, `carrier`

Example Request & Response

POST /v2/shipments

curl -i -X POST \
  https://api.shipstation.com/v2/shipments \
  -H 'Content-Type: application/json' \
  -H 'api-key: YOUR_API_KEY_HERE' \
  -d '{
    "shipments": [
      {
        "validate_address": "no_validation",
        "external_shipment_id": "1751939189",
        "carrier_id": "se-2774150",
        "create_sales_order": true,
        "store_id": "1582173",
        "notes_from_buyer": "I am a note from the buyer",
        "notes_to_buyer": "Thank you for your order!",
        "notes_for_gift": "I am a gift note",
        "internal_notes": "Check packaging before shipping",
        "is_gift": true,
        "zone": 0,
        "display_scheme": "paperless",
        "requested_shipment_service": "usps_priority_mail",
        "deliver_by_date": "2025-01-20T00:00:00.000Z",
        "assigned_user": "a2df9fa5-b7ee-467f-be4e-9c660542c187",
        "shipment_status": "pending",
        "amount_paid": {
          "currency": "usd",
          "amount": 12
        },
        "shipping_paid": {
          "currency": "usd",
          "amount": 12
        },
        "tax_paid": {
          "currency": "usd",
          "amount": 12
        },
        "ship_to": {
          "name": "John Doe",
          "phone": "+1 204-253-9411 ext. 123",
          "email": "example@example.com",
          "company_name": "The Home Depot",
          "address_line1": "1999 Bishop Grandin Blvd.",
          "address_line2": "Unit 408",
          "address_line3": "Building #7",
          "city_locality": "Winnipeg",
          "state_province": "Manitoba",
          "postal_code": "78756-3717",
          "country_code": "CA",
          "address_residential_indicator": "yes",
          "instructions": "any instruction",
          "geolocation": [
            {
              "type": "what3words",
              "value": "cats.with.thumbs"
            }
          ]
        },
        "ship_from": {
          "name": "John Doe",
          "phone": "+1 204-253-9411 ext. 123",
          "email": "example@example.com",
          "company_name": "The Home Depot",
          "address_line1": "1999 Bishop Grandin Blvd.",
          "address_line2": "Unit 408",
          "address_line3": "Building #7",
          "city_locality": "Winnipeg",
          "state_province": "Manitoba",
          "postal_code": "78756-3717",
          "country_code": "CA",
          "address_residential_indicator": "yes",
          "instructions": "any instructions",
          "geolocation": [
            {
              "type": "what3words",
              "value": "cats.with.thumbs"
            }
          ]
        },
        "items": [],
        "packages": [
          {
            "package_id": "se-123456",
            "package_code": "thick_envelope",
            "package_name": "Flat Rate Envelope",
            "weight": {
              "value": 23,
              "unit": "pound"
            },
            "dimensions": {
              "unit": "inch",
              "length": 2,
              "width": 2,
              "height": 1
            },
            "insured_value": [
              {
                "currency": "usd",
                "amount": 0
              }
            ],
            "label_messages": {
              "reference1": "Reference",
              "reference2": "Reference 2",
              "reference3": "Reference 3"
            },
            "external_package_id": "se-1234545",
            "content_description": "Hand knitted wool socks",
            "products": []
          }
        ]
      }
    ]
  }'

Use Cases

Bulk Import from Order System Import multiple orders from your e-commerce platform or order management system as shipments ready for rate shopping and label creation.

Pre-Create for Rate Shopping Create shipments before purchasing labels to compare carrier rates and delivery times across multiple services.

Batch Processing Workflows Prepare shipments in advance and process them in scheduled batches for efficient warehouse operations.

Validation Rules

Required Fields

ship_to address (recipient)
ship_from address (origin)
packages array with at least one package

Address Format

Addresses must include:

address_line_1
city_locality
postal_code
country_code (ISO 3166-1 alpha-2)

Package Requirements

Each package requires:

weight with value and unit
Dimensions are optional but recommended for accurate rates

Common Scenarios

Create with specific carrier:

{
  "shipments": [{
    "carrier_id": "se-123456",
    "service_code": "usps_priority_mail",
    "ship_to": { ... },
    "ship_from": { ... },
    "packages": [{ ... }]
  }]
}

Create without carrier (for rate shopping):

{
  "shipments": [{
    "ship_to": { ... },
    "ship_from": { ... },
    "packages": [{ ... }]
  }]
}

Error Handling

Common errors when creating shipments:

400 Bad Request

Missing required fields (ship_to, ship_from, packages)
Invalid address format
Invalid package weight or dimensions
Invalid carrier_id or service_code

500 Server Error

Temporary service issue - retry the request

Update Shipments - Modify shipment details
List Shipments - Retrieve shipments
Create Labels - Purchase labels for shipments

Create Shipments

Create Shipments

Request Body Properties

Example Request & Response

Use Cases

Validation Rules

Required Fields

Address Format

Package Requirements

Common Scenarios

Error Handling

Related Resources

Was this helpful?