Create Shipment

Create a shipment for outbound orders

This endpoint creates a new shipment for one or more orders. It handles carrier integration, label generation, and tracking initialization.

Authentication

This endpoint requires a valid API key with shipments:write permissions.

Authorization: Bearer YOUR_API_KEY

Request Body

order_ids · array · required

Array of order IDs to include in this shipment

warehouse_id · string · required

Origin warehouse ID

carrier · string · required

Carrier for shipment (e.g., “ups”, “fedex”, “usps”, “dhl”)

service_type · string · required

Service level (e.g., “ground”, “express”, “overnight”, “2day”)

ship_date · string · required

Scheduled ship date (ISO 8601)

shipping_address · object · required

Destination address

Show Address properties

name · string · required

Recipient name

company · string

Company name

line1 · string · required

Street address line 1

line2 · string

Street address line 2

city · string · required

City

state · string · required

State/Province code

postal_code · string · required

Postal/ZIP code

country · string · required

ISO 3166-1 alpha-2 country code

phone · string

Contact phone number

email · string

Contact email for delivery notifications

packages · array · required

Array of packages in the shipment

Show Package properties

weight · object · required

Package weight

Show Weight properties

value · number · required

Weight value

unit · string · required

Weight unit (“lb” or “kg”)

dimensions · object · required

Package dimensions

Show Dimension properties

length · number · required

Length

width · number · required

Width

height · number · required

Height

unit · string · required

Dimension unit (“in” or “cm”)

items · array

Items in this package

package_type · string

Package type (e.g., “box”, “envelope”, “tube”)

insurance · object

Insurance options

Show Insurance properties

enabled · boolean

Whether to insure the shipment

amount · integer

Insurance value in cents

currency · string

ISO 4217 currency code

signature_required · boolean

Whether signature is required on delivery

saturday_delivery · boolean

Whether to enable Saturday delivery

customs_info · object

Customs information for international shipments

Show Customs properties

contents_type · string

Type of contents (e.g., “merchandise”, “gift”, “sample”)

customs_items · array

Array of customs line items

eel_pfc · string

Electronic Export Information or Proof of Filing Citation

reference_numbers · object

Reference numbers for tracking

Show Reference properties

po_number · string

Purchase order number

invoice_number · string

Invoice number

reference_1 · string

Custom reference 1

reference_2 · string

Custom reference 2

label_format · string

Label format preference (“pdf”, “zpl”, “png”)

metadata · object

Additional custom fields

Response

Returns the created shipment with tracking information and label URLs.

cURL

curl --location --request POST 'https://api.stateset.com/v1/shipments' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data-raw '{
    "order_ids": ["order_123456", "order_123457"],
    "warehouse_id": "wh_001",
    "carrier": "ups",
    "service_type": "ground",
    "ship_date": "2024-01-20T08:00:00Z",
    "shipping_address": {
        "name": "John Doe",
        "company": "Acme Corp",
        "line1": "123 Main St",
        "city": "Los Angeles",
        "state": "CA",
        "postal_code": "90001",
        "country": "US",
        "phone": "[phone]",
        "email": "[e-mail]"
    },
    "packages": [
        {
            "weight": {
                "value": 5.5,
                "unit": "lb"
            },
            "dimensions": {
                "length": 12,
                "width": 10,
                "height": 8,
                "unit": "in"
            },
            "package_type": "box"
        }
    ],
    "insurance": {
        "enabled": true,
        "amount": 15000,
        "currency": "USD"
    },
    "signature_required": true
}'

Response

{
  "id": "ship_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
  "object": "shipment",
  "status": "label_created",
  "created_at": "2024-01-19T14:30:00Z",
  "ship_date": "2024-01-20T08:00:00Z",
  "carrier": "ups",
  "service_type": "ground",
  "tracking_number": "1Z999AA10123456784",
  "tracking_url": "https://www.ups.com/track?tracknum=1Z999AA10123456784",
  "label_url": "https://labels.stateset.com/ship_0901f083-aa1c-43c5-af5c-0a9d2fc64e30.pdf",
  "rate": {
    "amount": 1250,
    "currency": "USD",
    "estimated_delivery_date": "2024-01-23T18:00:00Z"
  },
  "packages": [
    {
      "tracking_number": "1Z999AA10123456784",
      "label_url": "https://labels.stateset.com/ship_0901f083-aa1c-43c5-af5c-0a9d2fc64e30.pdf",
      "weight": {
        "value": 5.5,
        "unit": "lb"
      },
      "dimensions": {
        "length": 12,
        "width": 10,
        "height": 8,
        "unit": "in"
      }
    }
  ],
  "from_address": {
    "name": "Main Distribution Center",
    "line1": "456 Warehouse Blvd",
    "city": "Los Angeles",
    "state": "CA",
    "postal_code": "90001",
    "country": "US"
  },
  "to_address": {
    "name": "John Doe",
    "company": "Acme Corp",
    "line1": "123 Main St",
    "city": "Los Angeles",
    "state": "CA",
    "postal_code": "90001",
    "country": "US"
  },
  "order_ids": ["order_123456", "order_123457"],
  "insurance": {
    "enabled": true,
    "amount": 15000,
    "currency": "USD",
    "provider": "ups"
  }
}