> ## 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.

# Create Order

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

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

## Authentication

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

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Request Body

<ParamField body="customer" type="object" required>
  Customer information for the order

  <Expandable title="Customer object properties">
    <ParamField body="email" type="string" required>
      Customer's email address
    </ParamField>

    <ParamField body="first_name" type="string" required>
      Customer's first name
    </ParamField>

    <ParamField body="last_name" type="string" required>
      Customer's last name
    </ParamField>

    <ParamField body="phone" type="string">
      Customer's phone number (E.164 format recommended)
    </ParamField>

    <ParamField body="customer_id" type="string">
      Existing customer ID if available
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="items" type="array" required>
  Array of items in the order

  <Expandable title="Item object properties">
    <ParamField body="sku" type="string" required>
      Product SKU
    </ParamField>

    <ParamField body="quantity" type="integer" required>
      Quantity ordered (must be positive)
    </ParamField>

    <ParamField body="price" type="number" required>
      Unit price in cents (e.g., 1999 for \$19.99)
    </ParamField>

    <ParamField body="name" type="string" required>
      Product name for display
    </ParamField>

    <ParamField body="variant_id" type="string">
      Product variant ID if applicable
    </ParamField>

    <ParamField body="metadata" type="object">
      Additional item-specific metadata
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="shipping_address" type="object" required>
  Shipping address for the order

  <Expandable title="Address properties">
    <ParamField body="line1" type="string" required>
      Street address line 1
    </ParamField>

    <ParamField body="line2" type="string">
      Street address line 2
    </ParamField>

    <ParamField body="city" type="string" required>
      City name
    </ParamField>

    <ParamField body="state" type="string" required>
      State/Province code (e.g., "CA", "NY")
    </ParamField>

    <ParamField body="postal_code" type="string" required>
      Postal/ZIP code
    </ParamField>

    <ParamField body="country" type="string" required>
      ISO 3166-1 alpha-2 country code (e.g., "US", "CA")
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="billing_address" type="object">
  Billing address if different from shipping. If not provided, shipping address will be used.

  <Expandable title="Address properties">
    Same structure as shipping\_address
  </Expandable>
</ParamField>

<ParamField body="payment" type="object" required>
  Payment information

  <Expandable title="Payment properties">
    <ParamField body="method" type="string" required>
      Payment method: `card`, `paypal`, `apple_pay`, `google_pay`, `bank_transfer`
    </ParamField>

    <ParamField body="payment_intent_id" type="string">
      Stripe PaymentIntent ID if using Stripe
    </ParamField>

    <ParamField body="transaction_id" type="string">
      External payment transaction ID
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="shipping" type="object">
  Shipping preferences

  <Expandable title="Shipping properties">
    <ParamField body="method" type="string">
      Shipping method: `standard`, `express`, `overnight`, `economy`
    </ParamField>

    <ParamField body="carrier" type="string">
      Preferred carrier: `ups`, `fedex`, `usps`, `dhl`
    </ParamField>

    <ParamField body="service_level" type="string">
      Specific service level code
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="metadata" type="object">
  Additional custom metadata to store with the order
</ParamField>

<ParamField body="idempotency_key" type="string">
  Unique key to ensure idempotent order creation
</ParamField>

### Response

<ResponseField name="id" type="string">
  Unique identifier for the created order
</ResponseField>

<ResponseField name="object" type="string">
  Always "order" for this object type
</ResponseField>

<ResponseField name="order_number" type="string">
  Human-readable order number (e.g., "ORD-2024-001234")
</ResponseField>

<ResponseField name="status" type="string">
  Order status: `pending`, `processing`, `shipped`, `delivered`, `cancelled`
</ResponseField>

<ResponseField name="customer" type="object">
  Customer information associated with the order
</ResponseField>

<ResponseField name="items" type="array">
  Array of order items with calculated totals
</ResponseField>

<ResponseField name="totals" type="object">
  Order totals breakdown

  <Expandable title="Totals properties">
    <ResponseField name="subtotal" type="number">
      Subtotal before tax and shipping (in cents)
    </ResponseField>

    <ResponseField name="tax" type="number">
      Total tax amount (in cents)
    </ResponseField>

    <ResponseField name="shipping" type="number">
      Shipping cost (in cents)
    </ResponseField>

    <ResponseField name="discount" type="number">
      Total discount amount (in cents)
    </ResponseField>

    <ResponseField name="total" type="number">
      Grand total (in cents)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of order creation
</ResponseField>

<ResponseField name="updated_at" type="string">
  ISO 8601 timestamp of last update
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  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"
      }
    }'
  ```

  ```graphQL GraphQL theme={null}
  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
      }
    }
  }
  ```

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

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

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

  ```go Go theme={null}
  order, err := stateset.Orders.Create(&stateset.OrderParams{
    Customer: &stateset.CustomerParams{
      Email:     "john.doe@example.com",
      FirstName: "John",
      LastName:  "Doe",
      Phone:     "+1234567890",
    },
    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",
    },
  })
  ```

  ```java Java theme={null}
  Map<String, Object> params = new HashMap<>();
  params.put("customer", Map.of(
      "email", "john.doe@example.com",
      "first_name", "John",
      "last_name", "Doe",
      "phone", "+1234567890"
  ));
  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);
  ```

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

  ```csharp C# theme={null}
  var order = await stateset.Orders.CreateAsync(new OrderCreateParams
  {
      Customer = new CustomerParams
      {
          Email = "john.doe@example.com",
          FirstName = "John",
          LastName = "Doe",
          Phone = "+1234567890"
      },
      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"
      }
  });
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={null}
  {
    "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"
  }
  ```

  ```json Error Response - Validation Error theme={null}
  {
    "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"
      }
    }
  }
  ```

  ```json Error Response - Inventory Unavailable theme={null}
  {
    "success": false,
    "error": {
      "code": "INVENTORY_UNAVAILABLE",
      "message": "Insufficient inventory for requested items",
      "details": {
        "unavailable_items": [
          {
            "sku": "TSHIRT-BLUE-L",
            "requested": 2,
            "available": 1
          }
        ]
      }
    }
  }
  ```
</ResponseExample>