Create Order - StateSet API Docs

curl -X POST https://api.stateset.com/v1/orders \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "email": "john.doe@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "phone": "+1234567890"
    },
    "items": [
      {
        "sku": "TSHIRT-BLUE-L",
        "quantity": 2,
        "price": 1999,
        "name": "Blue T-Shirt (Large)"
      },
      {
        "sku": "HAT-RED",
        "quantity": 1,
        "price": 1499,
        "name": "Red Baseball Cap"
      }
    ],
    "shipping_address": {
      "line1": "123 Main Street",
      "line2": "Apt 4B",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94105",
      "country": "US"
    },
    "payment": {
      "method": "card",
      "payment_intent_id": "pi_1234567890"
    },
    "shipping": {
      "method": "standard",
      "carrier": "ups"
    },
    "metadata": {
      "source": "web",
      "campaign": "summer-sale"
    }
  }'

{
  "id": "ord_1a2b3c4d5e6f",
  "object": "order",
  "order_number": "ORD-2024-001234",
  "status": "processing",
  "customer": {
    "id": "cus_9z8y7x6w5v4u",
    "email": "john.doe@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+1234567890"
  },
  "items": [
    {
      "id": "item_abc123",
      "sku": "TSHIRT-BLUE-L",
      "quantity": 2,
      "price": 1999,
      "name": "Blue T-Shirt (Large)",
      "total": 3998
    },
    {
      "id": "item_def456",
      "sku": "HAT-RED",
      "quantity": 1,
      "price": 1499,
      "name": "Red Baseball Cap",
      "total": 1499
    }
  ],
  "shipping_address": {
    "line1": "123 Main Street",
    "line2": "Apt 4B",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94105",
    "country": "US"
  },
  "billing_address": {
    "line1": "123 Main Street",
    "line2": "Apt 4B",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94105",
    "country": "US"
  },
  "payment": {
    "method": "card",
    "payment_intent_id": "pi_1234567890",
    "status": "paid"
  },
  "shipping": {
    "method": "standard",
    "carrier": "ups",
    "tracking_number": null,
    "estimated_delivery": "2024-01-22T00:00:00Z"
  },
  "totals": {
    "subtotal": 5497,
    "tax": 482,
    "shipping": 799,
    "discount": 0,
    "total": 6778
  },
  "metadata": {
    "source": "web",
    "campaign": "summer-sale"
  },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

POST

orders

curl -X POST https://api.stateset.com/v1/orders \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "email": "john.doe@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "phone": "+1234567890"
    },
    "items": [
      {
        "sku": "TSHIRT-BLUE-L",
        "quantity": 2,
        "price": 1999,
        "name": "Blue T-Shirt (Large)"
      },
      {
        "sku": "HAT-RED",
        "quantity": 1,
        "price": 1499,
        "name": "Red Baseball Cap"
      }
    ],
    "shipping_address": {
      "line1": "123 Main Street",
      "line2": "Apt 4B",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94105",
      "country": "US"
    },
    "payment": {
      "method": "card",
      "payment_intent_id": "pi_1234567890"
    },
    "shipping": {
      "method": "standard",
      "carrier": "ups"
    },
    "metadata": {
      "source": "web",
      "campaign": "summer-sale"
    }
  }'

{
  "id": "ord_1a2b3c4d5e6f",
  "object": "order",
  "order_number": "ORD-2024-001234",
  "status": "processing",
  "customer": {
    "id": "cus_9z8y7x6w5v4u",
    "email": "john.doe@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+1234567890"
  },
  "items": [
    {
      "id": "item_abc123",
      "sku": "TSHIRT-BLUE-L",
      "quantity": 2,
      "price": 1999,
      "name": "Blue T-Shirt (Large)",
      "total": 3998
    },
    {
      "id": "item_def456",
      "sku": "HAT-RED",
      "quantity": 1,
      "price": 1499,
      "name": "Red Baseball Cap",
      "total": 1499
    }
  ],
  "shipping_address": {
    "line1": "123 Main Street",
    "line2": "Apt 4B",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94105",
    "country": "US"
  },
  "billing_address": {
    "line1": "123 Main Street",
    "line2": "Apt 4B",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94105",
    "country": "US"
  },
  "payment": {
    "method": "card",
    "payment_intent_id": "pi_1234567890",
    "status": "paid"
  },
  "shipping": {
    "method": "standard",
    "carrier": "ups",
    "tracking_number": null,
    "estimated_delivery": "2024-01-22T00:00:00Z"
  },
  "totals": {
    "subtotal": 5497,
    "tax": 482,
    "shipping": 799,
    "discount": 0,
    "total": 6778
  },
  "metadata": {
    "source": "web",
    "campaign": "summer-sale"
  },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

This endpoint creates a new order and automatically triggers order processing workflows, including inventory allocation, payment processing, and fulfillment initiation.

Authentication

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

Authorization: Bearer YOUR_API_KEY

Request Body

customer

object

required

Customer information for the order

Show Customer object properties

string

required

Customer’s email address

first_name

string

required

Customer’s first name

last_name

string

required

Customer’s last name

phone

string

Customer’s phone number (E.164 format recommended)

customer_id

string

Existing customer ID if available

items

array

required

Array of items in the order

Show Item object properties

sku

string

required

Product SKU

quantity

integer

required

Quantity ordered (must be positive)

price

number

required

Unit price in cents (e.g., 1999 for $19.99)

name

string

required

Product name for display

variant_id

string

Product variant ID if applicable

metadata

object

Additional item-specific metadata

shipping_address

object

required

Shipping address for the order

Show Address properties

line1

string

required

Street address line 1

line2

string

Street address line 2

city

string

required

City name

state

string

required

State/Province code (e.g., “CA”, “NY”)

postal_code

string

required

Postal/ZIP code

country

string

required

ISO 3166-1 alpha-2 country code (e.g., “US”, “CA”)

billing_address

object

Billing address if different from shipping. If not provided, shipping address will be used.

Show Address properties

Same structure as shipping_address

payment

object

required

Payment information

Show Payment properties

method

string

required

Payment method: card, paypal, apple_pay, google_pay, bank_transfer

payment_intent_id

string

Stripe PaymentIntent ID if using Stripe

transaction_id

string

External payment transaction ID

shipping

object

Shipping preferences

Show Shipping properties

method

string

Shipping method: standard, express, overnight, economy

carrier

string

Preferred carrier: ups, fedex, usps, dhl

service_level

string

Specific service level code

metadata

object

Additional custom metadata to store with the order

idempotency_key

string

Unique key to ensure idempotent order creation

Response

string

Unique identifier for the created order

object

string

Always “order” for this object type

order_number

string

Human-readable order number (e.g., “ORD-2024-001234”)

status

string

Order status: pending, processing, shipped, delivered, cancelled

customer

object

Customer information associated with the order

items

array

Array of order items with calculated totals

totals

object

Order totals breakdown

Show Totals properties

subtotal

number

Subtotal before tax and shipping (in cents)

tax

number

Total tax amount (in cents)

shipping

number

Shipping cost (in cents)

discount

number

Total discount amount (in cents)

total

number

Grand total (in cents)

created_at

string

ISO 8601 timestamp of order creation

updated_at

string

ISO 8601 timestamp of last update

curl -X POST https://api.stateset.com/v1/orders \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "email": "john.doe@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "phone": "+1234567890"
    },
    "items": [
      {
        "sku": "TSHIRT-BLUE-L",
        "quantity": 2,
        "price": 1999,
        "name": "Blue T-Shirt (Large)"
      },
      {
        "sku": "HAT-RED",
        "quantity": 1,
        "price": 1499,
        "name": "Red Baseball Cap"
      }
    ],
    "shipping_address": {
      "line1": "123 Main Street",
      "line2": "Apt 4B",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94105",
      "country": "US"
    },
    "payment": {
      "method": "card",
      "payment_intent_id": "pi_1234567890"
    },
    "shipping": {
      "method": "standard",
      "carrier": "ups"
    },
    "metadata": {
      "source": "web",
      "campaign": "summer-sale"
    }
  }'

{
  "id": "ord_1a2b3c4d5e6f",
  "object": "order",
  "order_number": "ORD-2024-001234",
  "status": "processing",
  "customer": {
    "id": "cus_9z8y7x6w5v4u",
    "email": "john.doe@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+1234567890"
  },
  "items": [
    {
      "id": "item_abc123",
      "sku": "TSHIRT-BLUE-L",
      "quantity": 2,
      "price": 1999,
      "name": "Blue T-Shirt (Large)",
      "total": 3998
    },
    {
      "id": "item_def456",
      "sku": "HAT-RED",
      "quantity": 1,
      "price": 1499,
      "name": "Red Baseball Cap",
      "total": 1499
    }
  ],
  "shipping_address": {
    "line1": "123 Main Street",
    "line2": "Apt 4B",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94105",
    "country": "US"
  },
  "billing_address": {
    "line1": "123 Main Street",
    "line2": "Apt 4B",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94105",
    "country": "US"
  },
  "payment": {
    "method": "card",
    "payment_intent_id": "pi_1234567890",
    "status": "paid"
  },
  "shipping": {
    "method": "standard",
    "carrier": "ups",
    "tracking_number": null,
    "estimated_delivery": "2024-01-22T00:00:00Z"
  },
  "totals": {
    "subtotal": 5497,
    "tax": 482,
    "shipping": 799,
    "discount": 0,
    "total": 6778
  },
  "metadata": {
    "source": "web",
    "campaign": "summer-sale"
  },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Retrieve Order

Update Order

StateSet One

​Authentication

​Request Body

​Response

Authentication

Request Body

Response