Skip to main content
POST
/
v1
/
shipments
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": "+1-555-123-4567",
        "email": "john.doe@example.com"
    },
    "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
}'

{
  "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"
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.stateset.com/llms.txt

Use this file to discover all available pages before exploring further.

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
​
packages
array
required
Array of packages in the shipment
​
insurance
object
Insurance options
​
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
​
reference_numbers
object
Reference numbers for tracking
​
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 --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": "+1-555-123-4567",
        "email": "john.doe@example.com"
    },
    "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
}'

{
  "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"
  }
}