Placing orders

​

The journey in plain terms

1. Browse — The customer picks a store, channel, and fulfillment id, then loads the composed menu for that combination.
2. Customize — Use @fire-spark/storefront createSession / toOrderLines to turn a customized product into priced OrderLine rows.
3. Open cart — Call Create order with scope (and usually empty lines). 201 is a new cart; 202 is the existing OPEN cart for that scope — use the returned id.
4. Sync cart — Debounce local line changes and Update order with lines + totals.
5. Validate — Before checkout, call Validate order (or order.validateOrder() in @fire-spark/storefront) so prices and availability are checked against a fresh menu.
6. Pay, then place — Save tenders with Save payment intent (order.setTenders) or pass a single method on place. Then call Place order (order.placeOrder()). Pass intent_id to lock that draft. Omit it to build one real tender from payment.type plus one REDEMPTION tender per redeem payment_id. There is no cash default: without intent_id or payment.type, place fails with PAYMENT_REQUIRED unless the redeems cover the total (then only REDEMPTION tenders). The cart becomes CLOSED and fulfillment starts.
7. Track — Subscribe with realtime.listenOrder({ orderId }) (see Issue realtime token) or poll Get order fulfillment for checkout_state, visited states, and current_node_ids. On history, use List order fulfillments instead of one GET per order. Get order still exposes fulfillment_status. How the overlay waits is configured on the fulfillment workflow.

​

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

​

Step 1 — Build priced lines from customization

import { createSession, indexMenu, toOrderLines } from "@fire-spark/storefront";

const lookup = indexMenu(menu);
const session = createSession(lookup, productId);
// ... customer selects modifiers via session ...
const lines = toOrderLines(session.root);

​

Step 2 — Choose ids before create

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

​

Step 3 — Create then update the order

curl -X POST "https://firespark.cloud/api/storefront/v1/orders" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "ord-48291",
    "store_id": "downtown",
    "channel_id": "app",
    "fulfillment_id": "delivery",
    "customer": {
      "customer_info": {
        "display_name": "Ada Lovelace",
        "first_name": "Ada",
        "last_name": "Lovelace",
        "email": "ada@example.com",
        "phone": "+15551234567"
      }
    },
    "lines": [],
    "totals": {
      "currency": "USD",
      "subtotal": 0,
      "discount_rate": 0,
      "discount_total": 0,
      "tax_rate": 0,
      "tax_total": 0,
      "total": 0
    }
  }'

​

Step 4 — Validate before checkout

curl -X POST "https://firespark.cloud/api/storefront/v1/orders/validate" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "store_id": "downtown",
    "channel_id": "app",
    "fulfillment_id": "delivery",
    "lines": [],
    "totals": {
      "currency": "USD",
      "subtotal": 0,
      "discount_rate": 0,
      "discount_total": 0,
      "tax_rate": 0,
      "tax_total": 0,
      "total": 0
    }
  }'

​

Step 5 — Place the order

await order.setTenders([
  {
    method: "CARD",
    provider: "kushki",
    collect_at: "DEVICE",
    allocation: null
  }
]);
await order.placeOrder();

​

Step 6 — Show status to the customer

​

Step 7 — Cancel or refund

​

Related endpoints