Create an order

Create an order

POST /api/v1/orders

cURL

curl --silent --show-error --fail-with-body --request POST \
  --url 'https://api.stateset.com/api/v1/orders' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header "Idempotency-Key: ${IDEMPOTENCY_KEY:?Set a unique key for this operation; preserve it on retries}" \
  --header 'Content-Type: application/json' \
  --data '{
  "billing_address": {
    "city": "San Francisco",
    "country": "US",
    "line1": "548 Market St",
    "line2": "Suite 400",
    "postal_code": "94107",
    "state": "CA"
  },
  "currency": "USD",
  "customer_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "discount_amount": "5.00",
  "items": [
    {
      "discount": "5.00",
      "name": "Two-Person Tent",
      "product_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "quantity": 2,
      "sku": "SKU-TENT-2P-GRN",
      "tax_amount": "4.12",
      "unit_price": "49.00",
      "variant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
  ],
  "notes": "Two-person tent, green — replacement for damaged pole set.",
  "payment_method": "card",
  "shipping_address": {
    "city": "San Francisco",
    "country": "US",
    "line1": "548 Market St",
    "line2": "Suite 400",
    "postal_code": "94107",
    "state": "CA"
  },
  "shipping_amount": "8.00",
  "shipping_method": "ground",
  "stock_policy": "allow_backorder",
  "tax_amount": "4.12"
}'

201

{
  "created_at": "2026-08-31T14:22:05Z",
  "currency": "USD",
  "customer_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "fulfillment_status": "string",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "items": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Two-Person Tent",
      "product_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "quantity": 2,
      "shipped_quantity": 1,
      "sku": "SKU-TENT-2P-GRN",
      "total": "102.12",
      "unit_price": "49.00"
    }
  ],
  "order_number": "ORD-10042",
  "payment_status": "string",
  "status": "pending",
  "total_amount": "102.12",
  "updated_at": "2026-08-31T14:22:05Z"
}

Confirm your deployment before running this request. This page describes an API contract; a published reference does not establish hosted availability. Check the dated host report and obtain your deployment URL and credentials. Replace the example host if your provisioned service uses a different URL.

Headers

Idempotency-Key · string,null

Optional client-generated key. Replaying the same key with an identical body returns the original response without creating a duplicate; reusing it with a different body returns 422. Scoped per tenant.

Request body

CreateOrderRequest

billing_address · AddressDto,null

Address DTO shared by orders and customers.

Show AddressDto

city · string · required

country · string · required

line1 · string · required

line2 · string,null

postal_code · string · required

state · string,null

currency · string,null

ISO currency code (default: USD).

customer_id · string (uuid) · required

The customer placing the order.

discount_amount · string,null

Order-level discount subtracted from the line amounts.

items · CreateOrderItemRequest[] · required

Line items for the order.

Show CreateOrderItemRequest

discount · string,null

name · string · required

product_id · string (uuid) · required

quantity · integer (int32) · required

sku · string · required

tax_amount · string,null

unit_price · string · required

variant_id · string,null (uuid)

notes · string,null

Optional notes.

payment_method · string,null

Payment method identifier.

shipping_address · AddressDto,null

Address DTO shared by orders and customers.

Show AddressDto

city · string · required

country · string · required

line1 · string · required

line2 · string,null

postal_code · string · required

state · string,null

shipping_amount · string,null

Order-level shipping charge added to the line amounts.

shipping_method · string,null

Shipping method identifier.

stock_policy · StockPolicyDto,null

Stock policy accepted by POST /api/v1/orders (stock_policy). Allowed values: 'allow_backorder', 'reject_if_insufficient'.

tax_amount · string,null

Order-level tax added to the line amounts. Omitted means zero.

Response

OrderResponse

created_at · string (date-time) · required

currency · string · required

customer_id · string (uuid) · required

fulfillment_status · string · required

id · string (uuid) · required

items · OrderItemResponse[] · required

Show OrderItemResponse

id · string (uuid) · required

name · string · required

product_id · string (uuid) · required

quantity · integer (int32) · required

shipped_quantity · integer (int32)

Units of this line that have shipped so far (<= quantity).

sku · string · required

total · string · required

unit_price · string · required

order_number · string · required

payment_status · string · required

status · string · required

total_amount · string · required

updated_at · string (date-time) · required

Status codes

Code	Meaning
201	Order created
400	Invalid request
422	Idempotency-Key reused with a different body
428	Idempotency-Key header required on this endpoint (configurable)

Using this contract

Read the source OpenAPI document for declared schemas and alternatives. This page also includes documented corrections from the spec overlays. Example IDs and values are illustrative; replace them with records from your workspace.

cURL

curl --silent --show-error --fail-with-body --request POST \
  --url 'https://api.stateset.com/api/v1/orders' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header "Idempotency-Key: ${IDEMPOTENCY_KEY:?Set a unique key for this operation; preserve it on retries}" \
  --header 'Content-Type: application/json' \
  --data '{
  "billing_address": {
    "city": "San Francisco",
    "country": "US",
    "line1": "548 Market St",
    "line2": "Suite 400",
    "postal_code": "94107",
    "state": "CA"
  },
  "currency": "USD",
  "customer_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "discount_amount": "5.00",
  "items": [
    {
      "discount": "5.00",
      "name": "Two-Person Tent",
      "product_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "quantity": 2,
      "sku": "SKU-TENT-2P-GRN",
      "tax_amount": "4.12",
      "unit_price": "49.00",
      "variant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
  ],
  "notes": "Two-person tent, green — replacement for damaged pole set.",
  "payment_method": "card",
  "shipping_address": {
    "city": "San Francisco",
    "country": "US",
    "line1": "548 Market St",
    "line2": "Suite 400",
    "postal_code": "94107",
    "state": "CA"
  },
  "shipping_amount": "8.00",
  "shipping_method": "ground",
  "stock_policy": "allow_backorder",
  "tax_amount": "4.12"
}'

201

{
  "created_at": "2026-08-31T14:22:05Z",
  "currency": "USD",
  "customer_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "fulfillment_status": "string",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "items": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Two-Person Tent",
      "product_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "quantity": 2,
      "shipped_quantity": 1,
      "sku": "SKU-TENT-2P-GRN",
      "total": "102.12",
      "unit_price": "49.00"
    }
  ],
  "order_number": "ORD-10042",
  "payment_status": "string",
  "status": "pending",
  "total_amount": "102.12",
  "updated_at": "2026-08-31T14:22:05Z"
}