Create Order

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

POST /api/v1/orders

cURL

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

mutation CreateOrder($input: OrderCreateInput!) {
  orderCreate(input: $input) {
    order {
      id
      orderNumber
      status
      customer {
        email
        firstName
        lastName
      }
      items {
        sku
        quantity
        price
        total
      }
      totals {
        subtotal
        tax
        shipping
        total
      }
      createdAt
    }
    userErrors {
      field
      message
    }
  }
}

const order = await stateset.orders.create({
  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)'
    }
  ],
  shipping_address: {
    line1: '123 Main Street',
    city: 'San Francisco',
    state: 'CA',
    postal_code: '94105',
    country: 'US'
  },
  payment: {
    method: 'card',
    payment_intent_id: 'pi_1234567890'
  }
});

order = stateset.orders.create(
    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)'
        }
    ],
    shipping_address={
        'line1': '123 Main Street',
        'city': 'San Francisco',
        'state': 'CA',
        'postal_code': '94105',
        'country': 'US'
    },
    payment={
        'method': 'card',
        'payment_intent_id': 'pi_1234567890'
    }
)

order = Stateset::Order.create({
  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)'
    }
  ],
  shipping_address: {
    line1: '123 Main Street',
    city: 'San Francisco',
    state: 'CA',
    postal_code: '94105',
    country: 'US'
  },
  payment: {
    method: 'card',
    payment_intent_id: 'pi_1234567890'
  }
})

order, err := stateset.Orders.Create(&stateset.OrderParams{
  Customer: &stateset.CustomerParams{
    Email:     "[e-mail]",
    FirstName: "John",
    LastName:  "Doe",
    Phone:     "[phone]",
  },
  Items: []*stateset.OrderItemParams{
    {
      SKU:      "TSHIRT-BLUE-L",
      Quantity: 2,
      Price:    1999,
      Name:     "Blue T-Shirt (Large)",
    },
  },
  ShippingAddress: &stateset.AddressParams{
    Line1:      "123 Main Street",
    City:       "San Francisco",
    State:      "CA",
    PostalCode: "94105",
    Country:    "US",
  },
  Payment: &stateset.PaymentParams{
    Method:          "card",
    PaymentIntentID: "pi_1234567890",
  },
})

Map<String, Object> params = new HashMap<>();
params.put("customer", Map.of(
    "email", "[e-mail]",
    "first_name", "John",
    "last_name", "Doe",
    "phone", "[phone]"
));
params.put("items", List.of(Map.of(
    "sku", "TSHIRT-BLUE-L",
    "quantity", 2,
    "price", 1999,
    "name", "Blue T-Shirt (Large)"
)));
params.put("shipping_address", Map.of(
    "line1", "123 Main Street",
    "city", "San Francisco",
    "state", "CA",
    "postal_code", "94105",
    "country", "US"
));
params.put("payment", Map.of(
    "method", "card",
    "payment_intent_id", "pi_1234567890"
));

Order order = stateset.orders().create(params);

$order = $stateset->orders->create([
  '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)',
    ],
  ],
  'shipping_address' => [
    'line1' => '123 Main Street',
    'city' => 'San Francisco',
    'state' => 'CA',
    'postal_code' => '94105',
    'country' => 'US',
  ],
  'payment' => [
    'method' => 'card',
    'payment_intent_id' => 'pi_1234567890',
  ],
]);

var order = await stateset.Orders.CreateAsync(new OrderCreateParams
{
    Customer = new CustomerParams
    {
        Email = "[e-mail]",
        FirstName = "John",
        LastName = "Doe",
        Phone = "[phone]"
    },
    Items = new List<OrderItemParams>
    {
        new OrderItemParams
        {
            Sku = "TSHIRT-BLUE-L",
            Quantity = 2,
            Price = 1999,
            Name = "Blue T-Shirt (Large)"
        }
    },
    ShippingAddress = new AddressParams
    {
        Line1 = "123 Main Street",
        City = "San Francisco",
        State = "CA",
        PostalCode = "94105",
        Country = "US"
    },
    Payment = new PaymentParams
    {
        Method = "card",
        PaymentIntentId = "pi_1234567890"
    }
});

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

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": {
      "items[0].quantity": "Quantity must be a positive integer",
      "customer.email": "Invalid email format"
    }
  }
}

{
  "success": false,
  "error": {
    "code": "INVENTORY_UNAVAILABLE",
    "message": "Insufficient inventory for requested items",
    "details": {
      "unavailable_items": [
        {
          "sku": "TSHIRT-BLUE-L",
          "requested": 2,
          "available": 1
        }
      ]
    }
  }
}

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/api/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"
    }
  }'

mutation CreateOrder($input: OrderCreateInput!) {
  orderCreate(input: $input) {
    order {
      id
      orderNumber
      status
      customer {
        email
        firstName
        lastName
      }
      items {
        sku
        quantity
        price
        total
      }
      totals {
        subtotal
        tax
        shipping
        total
      }
      createdAt
    }
    userErrors {
      field
      message
    }
  }
}

const order = await stateset.orders.create({
  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)'
    }
  ],
  shipping_address: {
    line1: '123 Main Street',
    city: 'San Francisco',
    state: 'CA',
    postal_code: '94105',
    country: 'US'
  },
  payment: {
    method: 'card',
    payment_intent_id: 'pi_1234567890'
  }
});

order = stateset.orders.create(
    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)'
        }
    ],
    shipping_address={
        'line1': '123 Main Street',
        'city': 'San Francisco',
        'state': 'CA',
        'postal_code': '94105',
        'country': 'US'
    },
    payment={
        'method': 'card',
        'payment_intent_id': 'pi_1234567890'
    }
)

order = Stateset::Order.create({
  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)'
    }
  ],
  shipping_address: {
    line1: '123 Main Street',
    city: 'San Francisco',
    state: 'CA',
    postal_code: '94105',
    country: 'US'
  },
  payment: {
    method: 'card',
    payment_intent_id: 'pi_1234567890'
  }
})

order, err := stateset.Orders.Create(&stateset.OrderParams{
  Customer: &stateset.CustomerParams{
    Email:     "[e-mail]",
    FirstName: "John",
    LastName:  "Doe",
    Phone:     "[phone]",
  },
  Items: []*stateset.OrderItemParams{
    {
      SKU:      "TSHIRT-BLUE-L",
      Quantity: 2,
      Price:    1999,
      Name:     "Blue T-Shirt (Large)",
    },
  },
  ShippingAddress: &stateset.AddressParams{
    Line1:      "123 Main Street",
    City:       "San Francisco",
    State:      "CA",
    PostalCode: "94105",
    Country:    "US",
  },
  Payment: &stateset.PaymentParams{
    Method:          "card",
    PaymentIntentID: "pi_1234567890",
  },
})

Map<String, Object> params = new HashMap<>();
params.put("customer", Map.of(
    "email", "[e-mail]",
    "first_name", "John",
    "last_name", "Doe",
    "phone", "[phone]"
));
params.put("items", List.of(Map.of(
    "sku", "TSHIRT-BLUE-L",
    "quantity", 2,
    "price", 1999,
    "name", "Blue T-Shirt (Large)"
)));
params.put("shipping_address", Map.of(
    "line1", "123 Main Street",
    "city", "San Francisco",
    "state", "CA",
    "postal_code", "94105",
    "country", "US"
));
params.put("payment", Map.of(
    "method", "card",
    "payment_intent_id", "pi_1234567890"
));

Order order = stateset.orders().create(params);

$order = $stateset->orders->create([
  '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)',
    ],
  ],
  'shipping_address' => [
    'line1' => '123 Main Street',
    'city' => 'San Francisco',
    'state' => 'CA',
    'postal_code' => '94105',
    'country' => 'US',
  ],
  'payment' => [
    'method' => 'card',
    'payment_intent_id' => 'pi_1234567890',
  ],
]);

var order = await stateset.Orders.CreateAsync(new OrderCreateParams
{
    Customer = new CustomerParams
    {
        Email = "[e-mail]",
        FirstName = "John",
        LastName = "Doe",
        Phone = "[phone]"
    },
    Items = new List<OrderItemParams>
    {
        new OrderItemParams
        {
            Sku = "TSHIRT-BLUE-L",
            Quantity = 2,
            Price = 1999,
            Name = "Blue T-Shirt (Large)"
        }
    },
    ShippingAddress = new AddressParams
    {
        Line1 = "123 Main Street",
        City = "San Francisco",
        State = "CA",
        PostalCode = "94105",
        Country = "US"
    },
    Payment = new PaymentParams
    {
        Method = "card",
        PaymentIntentId = "pi_1234567890"
    }
});

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

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": {
      "items[0].quantity": "Quantity must be a positive integer",
      "customer.email": "Invalid email format"
    }
  }
}

{
  "success": false,
  "error": {
    "code": "INVENTORY_UNAVAILABLE",
    "message": "Insufficient inventory for requested items",
    "details": {
      "unavailable_items": [
        {
          "sku": "TSHIRT-BLUE-L",
          "requested": 2,
          "available": 1
        }
      ]
    }
  }
}