> ## Documentation Index
> Fetch the complete documentation index at: https://firespark.cloud/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create order

> Place a customer order from your owned channel into Fire spark.

Creates a new order for the authenticated customer. This is how owned channels (app, web, kiosk) submit checkout into Fire spark. After creation, Fire spark routes the order to the merchant's operational stack and notifies POS integrations via [`order.injected`](/docs/integrations-api/orders/webhooks).

<Note>
  Requires a Storefront API access token from [Token
  exchange](/docs/storefront-api/oauth/exchange/post).
</Note>

## What happens after you create an order

<Steps>
  <Step title="Your channel sends the checkout payload">
    Fire spark validates store, channel, fulfillment, and line items against
    the composed menu for that selling context.
  </Step>

  <Step title="Fire spark stores the order">
    The order receives payment and fulfillment statuses based on your checkout
    flow.
  </Step>

  <Step title="The POS receives the ticket">
    Fire spark notifies the merchant integration. When the
    [`order.injected`](/docs/integrations-api/orders/webhooks) webhook fires, the
    order is sent to the POS **in its current state** so the kitchen can start
    preparation.
  </Step>
</Steps>

## Path parameters

| Parameter | Required | Description                                                                       |
| --------- | -------- | --------------------------------------------------------------------------------- |
| `id`      | Yes      | Customer identifier. Alphanumeric characters, `_`, and `-` only. 1–64 characters. |

## Request body

| Field            | Required | Type    | Description                                                                                                                                                                                 |
| ---------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`             | Yes      | string  | External order id you assign. Must be unique per merchant. 1–64 characters.                                                                                                                 |
| `store_id`       | Yes      | string  | External store identifier where the order is prepared                                                                                                                                       |
| `channel_id`     | Yes      | string  | External channel identifier (for example `app`, `web`)                                                                                                                                      |
| `fulfillment_id` | Yes      | string  | External fulfillment option (for example `delivery`, `pickup`)                                                                                                                              |
| `brand_id`       | No       | string  | External brand identifier when ordering under a specific brand                                                                                                                              |
| `is_anonymous`   | No       | boolean | Set to `true` for guest checkout without a registered customer profile. Defaults to `false`. The `customer_id` path parameter is still required and identifies the session or guest record. |
| `items`          | No       | array   | Line items with product ids, quantities, and modifier selections                                                                                                                            |
| `metadata`       | No       | object  | Channel-specific metadata. Defaults to `{}`.                                                                                                                                                |

## Request

```bash theme={null}
curl -X POST "https://firespark.cloud/api/storefront/v1/customers/cust-001/orders" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "ord-48291",
    "brand_id": "0001",
    "store_id": "downtown",
    "channel_id": "app",
    "fulfillment_id": "delivery",
    "is_anonymous": false,
    "items": [
      {
        "id": "burger-classic",
        "quantity": 1,
        "modifiers": []
      }
    ],
    "metadata": {
      "cart_session_id": "sess_abc123"
    }
  }'
```

## Response

Returns `201` with the created order in `data`.

<ResponseExample>
  ```json Success theme={null}
  {
    "data": {
      "id": "ord-48291",
      "brand_id": "0001",
      "store_id": "downtown",
      "channel_id": "app",
      "customer_id": "cust-001",
      "is_anonymous": false,
      "fulfillment_id": "delivery",
      "status": "OPEN",
      "payment_status": "PENDING",
      "fulfillment_status": "IDLE",
      "totals": {
        "currency": "USD",
        "subtotal": 12.99,
        "discount_total": 0,
        "tax_total": 1.95,
        "total": 14.94
      }
    }
  }
  ```
</ResponseExample>

<Tip>
  Generate the external `id` on your server before calling POST so you can retry
  safely if the network fails. Use the same id on retry — Fire spark rejects
  duplicate ids for the same merchant.
</Tip>

## Error responses

| Status | Description                                        |
| ------ | -------------------------------------------------- |
| `401`  | Missing or invalid access token                    |
| `404`  | Customer not found                                 |
| `422`  | Invalid store, channel, fulfillment, or line items |


## OpenAPI

````yaml POST /customers/{id}/orders
openapi: 3.0.1
info:
  title: Fire spark Storefront API
  description: Customer-facing channel endpoints for Fire spark.
  version: 1.0.0
servers:
  - url: https://firespark.cloud/api/storefront/v1
security:
  - bearerAuth: []
paths:
  /customers/{id}/orders:
    post:
      summary: Create order
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 64
            pattern: ^[a-zA-Z0-9_-]+$
          description: Customer identifier.
      requestBody:
        required: true
        description: Order to create.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderInsert'
      responses:
        '201':
          description: Ok
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Order'
components:
  schemas:
    OrderInsert:
      type: object
      required:
        - id
        - fulfillment_id
        - store_id
        - channel_id
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 64
          pattern: ^[a-zA-Z0-9_-]+$
        fulfillment_id:
          type: string
          minLength: 1
          maxLength: 64
          pattern: ^[a-zA-Z0-9_-]+$
        store_id:
          type: string
          minLength: 1
          maxLength: 64
          pattern: ^[a-zA-Z0-9_-]+$
        channel_id:
          type: string
          minLength: 1
          maxLength: 64
          pattern: ^[a-zA-Z0-9_-]+$
        brand_id:
          type: string
          minLength: 1
          maxLength: 64
          pattern: ^[a-zA-Z0-9_-]+$
          nullable: true
        is_anonymous:
          type: boolean
          default: false
        items:
          type: array
          items:
            type: object
        metadata:
          type: object
          additionalProperties: true
    Order:
      type: object
      additionalProperties: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````