---
title: "Create a storefront order"
method: POST
path: "/api/v1/storefront/orders"
tags: ["storefront"]
---

# Create a storefront order

`POST /api/v1/storefront/orders`

## Request

- Base URL: `https://api.foundryims.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.foundryims.com/api/v1/storefront/orders`
- Auth: HTTP bearer

Finalize a storefront cart into a Foundry order. The storefront owns
payment processing — Foundry just records the order, server-recomputes
totals from current ChannelSku.price values, and reserves inventory.

Returns `{ orderId, orderNumber, status, lookupToken }`. The token
is the customer's escape-hatch reference: storefronts give it to
the customer (in the confirmation email, account page, wherever) so
they can fetch order status via Phase 3's
`GET /storefront/orders/:lookupToken` without a Foundry account.

Pass `Idempotency-Key` to make retries safe — replays with the same
key + body return the cached 2xx; same key + different body returns
409 to surface the misuse.

## Headers

- `idempotency-key` string, required
- `Idempotency-Key` string

## Request body

- CreateOrderDto
  - `customer` StorefrontCustomerDto, required
    - `email` string, required
    - `name` string, required
    - `phone` string
  - `shippingAddress` StorefrontAddressDto, required
    - `name` string, required
    - `line1` string, required
    - `line2` string
    - `city` string, required
    - `state` string, required
    - `postalCode` string, required
    - `country` string, required
    - `phone` string
  - `billingAddress` StorefrontAddressDto
    - `name` string, required
    - `line1` string, required
    - `line2` string
    - `city` string, required
    - `state` string, required
    - `postalCode` string, required
    - `country` string, required
    - `phone` string
  - `lineItems` StorefrontLineItemDto[], required
    - `variantId` string, required: Foundry variant UUID
    - `quantity` number, required
    - `unitPrice` number, required: Client-side per-unit price snapshot
  - `shipping` StorefrontShippingDto, required
    - `method` string, required
    - `cost` number, required
  - `tax` StorefrontTaxDto, required
    - `amount` number, required
  - `discount` StorefrontDiscountDto
    - `code` string
    - `amount` number, required
  - `payment` StorefrontPaymentDto, required
    - `provider` string, required
    - `chargeId` string, required: Provider-side charge / transaction id
    - `amount` number, required
  - `totals` StorefrontTotalsDto, required
    - `subtotal` number, required
    - `tax` number, required
    - `shipping` number, required
    - `discount` number
    - `total` number, required
  - `externalReference` string
  - `notes` string

## Response `201`

- CreateOrderResultDto
  - `orderId` string, required
  - `orderNumber` string, required
  - `status` string, required
  - `lookupToken` string, required: Customer-facing order-status token.

---

[API](https://skmtc.dev/foundryims/apis/foundry-storefront-api.md) · [All operations](https://skmtc.dev/foundryims/apis/foundry-storefront-api/llms.txt) · [OpenAPI document](https://skmtc.dev/foundryims/apis/foundry-storefront-api/revisions/c6b0410da596?raw)