Skip to content
Guides
/
/
Create Shipments
Last updated

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.

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:

PropertyTypeRequiredDescription
ship_toobjectRequiredRecipient shipping address
ship_fromobjectRequiredOrigin shipping address
packagesarrayRequiredPackage dimensions and weight (minimum 1 package)
external_shipment_idstringOptionalYour internal shipment identifier (max 50 characters)
carrier_idstringOptionalCarrier account to use for shipping
service_codestringOptionalSpecific carrier service (e.g., fedex_ground, usps_priority_mail)
itemsarrayOptionalShipment line items with product details
shipment_statusstringOptionalInitial status: pending, processing, label_purchased, cancelled
advanced_optionsobjectOptionalAdvanced shipping options (signature, Saturday delivery, etc.)
customsobjectOptionalInternational shipment customs information
insurance_providerstringOptionalInsurance provider: none, shipsurance, 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_for_gift": "I am a gift note",
        "is_gift": true,
        "zone": 0,
        "display_scheme": "paperless",
        "assigned_user": "a2df9fa5-b7ee-467f-be4e-9c660542c187",
        "shipment_status": "pending",
        "amount_paid": {
          "currency": "string",
          "amount": 12
        },
        "shipping_paid": {
          "currency": "string",
          "amount": 12
        },
        "tax_paid": {
          "currency": "string",
          "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"
        },
        "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
Previous page
Next page