Create Order

Create a new order with automatic inventory allocation and fulfillment workflow initiation

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

email · 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

id · 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

curl -X POST https://api.stateset.com/v1/orders \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "email": "[e-mail]",
      "first_name": "John",
      "last_name": "Doe",
      "phone": "[phone]"
    },
    "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"
    }
  }'

Success Response

{
  "id": "ord_1a2b3c4d5e6f",
  "object": "order",
  "order_number": "ORD-2024-001234",
  "status": "processing",
  "customer": {
    "id": "cus_9z8y7x6w5v4u",
    "email": "[e-mail]",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "[phone]"
  },
  "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"
}