Placing orders

This guide walks through how a customer order moves from your app or web channel into Fire spark and then into the merchant kitchen — in language that works for developers and for teams explaining the process to stakeholders.

The journey in plain terms

Browse — The customer picks a store, channel context, and fulfillment type, then loads the composed menu for that combination.
Checkout — Your channel collects items, payment, and delivery details.
Submit — Your server calls Create order with an external order id you control.
Route — Fire spark validates the order, records payment and fulfillment state, and notifies the merchant’s POS integration.
Kitchen — When the integration receives order.injected, it creates the ticket in the POS with the order exactly as Fire spark stored it at that moment.
Track — Poll or subscribe to status via Get order while the customer waits for updates from your UI.

Prerequisites

Customer registered and authenticated via Token exchange
Store, channel, and fulfillment ids from List stores and List fulfillment
Menu loaded for the same store, channel, and fulfillment triple

Use product and modifier ids from the composed menu response. Those same external ids appear on order line items and on POS tickets after injection.

Example cart item

{
  "id": "burger-classic",
  "quantity": 1,
  "modifiers": [
    { "id": "cola", "quantity": 1 }
  ]
}

Step 2 — Choose ids before checkout

Assign the order id on your server before calling POST. This makes retries safe if the client loses connectivity.

const orderId = `ord-${crypto.randomUUID().slice(0, 8)}`;

Step 3 — Create the order

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",
    "store_id": "downtown",
    "channel_id": "app",
    "fulfillment_id": "delivery",
    "items": [
      { "id": "burger-classic", "quantity": 1, "modifiers": [] }
    ]
  }'

Fire spark responds with the order object including payment_status, fulfillment_status, and status.

Step 4 — What happens in the back office

You do not call the Integrations API from the storefront. After creation:

Stage	What Fire spark does
Validation	Confirms items exist on the menu for that store, channel, and fulfillment
Storage	Persists lines, totals, customer, and payment intents
Notification	Sends webhooks to the merchant POS integration
Injection	On `order.injected`, delivers the full order payload so the POS creates the kitchen ticket

For marketing and ops: The customer sees confirmation as soon as your channel receives 201 from Create order. The kitchen sees the ticket when the POS integration handles order.injected — usually seconds later, depending on merchant configuration.

Step 5 — Show status to the customer

Poll Get order or refresh from your own realtime layer as fulfillment_status moves from IDLE → PREPARING → PREPARED → DELIVERED.

Status field	Customer-facing copy (examples)
`payment_status: PENDING`	Confirming payment…
`payment_status: PAID` + `fulfillment_status: PREPARING`	Your order is being prepared
`fulfillment_status: PREPARED`	Ready for pickup / On the way
`status: COMPLETED`	Delivered — thanks!

Step 6 — Cancel if needed

If the customer cancels before the order is fulfilled, call Cancel order. Fire spark propagates cancellation to the POS integration.

Create order

Submit checkout

List orders

Order history

Order webhooks

How orders reach the POS

Orders concept

Commercial overview

API Documentation

Endpoints

Guides

Resources

The journey in plain terms

Prerequisites

Step 1 — Build the cart from the menu

Step 2 — Choose ids before checkout

Step 3 — Create the order

Step 4 — What happens in the back office

Step 5 — Show status to the customer

Step 6 — Cancel if needed

Create order

List orders

Order webhooks

Orders concept

​The journey in plain terms

​Prerequisites

​Step 1 — Build the cart from the menu

​Step 2 — Choose ids before checkout

​Step 3 — Create the order

​Step 4 — What happens in the back office

​Step 5 — Show status to the customer

​Step 6 — Cancel if needed

​Related endpoints

Create order

List orders

Order webhooks

Orders concept

The journey in plain terms

Prerequisites

Step 1 — Build the cart from the menu

Step 2 — Choose ids before checkout

Step 3 — Create the order

Step 4 — What happens in the back office

Step 5 — Show status to the customer

Step 6 — Cancel if needed

Related endpoints