StateSet API Docs

curl --location --request POST 'https://api.stateset.com/api/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
}'

const shipment = await stateset.shipments.create({
  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"
    }
  ],
  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"
  }
}

POST

api

shipments

curl --location --request POST 'https://api.stateset.com/api/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
}'

const shipment = await stateset.shipments.create({
  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"
    }
  ],
  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"
  }
}

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

array

required

Array of order IDs to include in this shipment

string

required

Origin warehouse ID

string

required

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

string

required

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

string

required

Scheduled ship date (ISO 8601)

object

required

Destination address

Show Address properties

string

required

Recipient name

string

Company name

string

required

Street address line 1

string

Street address line 2

string

required

City

string

required

State/Province code

string

required

Postal/ZIP code

string

required

ISO 3166-1 alpha-2 country code

string

Contact phone number

string

Contact email for delivery notifications

array

required

Array of packages in the shipment

Show Package properties

object

required

Package weight

Show Weight properties

number

required

Weight value

string

required

Weight unit (“lb” or “kg”)

object

required

Package dimensions

Show Dimension properties

number

required

Length

number

required

Width

number

required

Height

string

required

Dimension unit (“in” or “cm”)

array

Items in this package

string

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

object

Insurance options

Show Insurance properties

boolean

Whether to insure the shipment

integer

Insurance value in cents

string

ISO 4217 currency code

boolean

Whether signature is required on delivery

boolean

Whether to enable Saturday delivery

object

Customs information for international shipments

Show Customs properties

string

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

array

Array of customs line items

string

Electronic Export Information or Proof of Filing Citation

object

Reference numbers for tracking

Show Reference properties

string

Purchase order number

string

Invoice number

string

Custom reference 1

string

Custom reference 2

string

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

object

Additional custom fields

Response

Returns the created shipment with tracking information and label URLs.

curl --location --request POST 'https://api.stateset.com/api/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
}'

const shipment = await stateset.shipments.create({
  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"
    }
  ],
  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"
  }
}

Get Shipment Update Shipment

StateSet One API

StateSet API v1

Customer Management

Order Management

Checkouts

Returns Management

Warranty Management

Wholesale Management

Inventory Management

ASN Management

Purchase Orders

Manufacturing

Warehouse Operations

CRM

Suppliers

E-commerce

Financial

Fulfillment

Communication

System

StateSet Response API

StateSet Cloud API

StateSet Commerce API

Create Shipment

Authentication

Request Body

Response

​Authentication

​Request Body

​Response

Authentication

Request Body

Response