Update order status

Sends the next fulfillment status for a placed order. Use the status labels configured for this merchant (for example PREPARING or DELIVERED). Fire spark does not accept a fixed kitchen enum.

Requires an access token with the orders:write scope. See Token to obtain a token.

How this fits the order flow

After checkout, Fire spark sends a webhook when the order reaches a status you subscribed to.
Your POS creates the ticket when order.status.changed arrives with data.status injecting (or whichever status you use for handoff).
Each later kitchen event should PATCH the next fulfillment status. Fire spark updates the order and may send another webhook.
The call is asynchronous. It claims the advance while the fulfillment is WAITING and returns without waiting for the next node, so you can call it from the webhook handler. The order in the response can still be the snapshot from before this advance. A 409 means the row was not WAITING.

When to call this endpoint

The labels below are examples. Use the fulfillment statuses configured for your merchant.

POS event	Example `fulfillment_status`
Ticket accepted in kitchen	`PREPARING`
Bagged / ready for pickup	`PREPARED`
Driver dispatched	`DELIVERING`
Handed to customer	`DELIVERED` (may also set `status: COMPLETED`)

An order can be in more than one fulfillment status at once (for example kitchen and delivery). Send the next status for the work you are advancing. Other in-progress statuses stay until you update them.

Path parameters

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

Request body

Field	Required	Type	Description
`fulfillment_status`	Yes	string	Next non-terminal fulfillment status
`status`	No	string	`COMPLETED`, `VOIDED`, `REVERSED`, or `REFUNDED` — applied when Fire spark auto-enters a matching terminal
`tenders`	No	object[]	Only with `fulfillment_status` `PAID`. Each item is `{ "id": string, "completed": boolean }`. See Mark the order paid

curl -X PATCH "https://firespark.cloud/api/integrations/v1/orders/ord-48291/status" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fulfillment_status": "PREPARING"
  }'

Mark the order paid

While the order is in PAYING, send fulfillment_status PAID when your POS collected the payment. Fire spark marks the tenders of that paying step as paid (one capture per tender, as if each one were marked collected). The order advances to PAID only once every tender of the step is settled. A reserved reward counts as settled; Fire spark confirms reward redemptions.

Without tenders: every tender the paying step is still waiting for is marked paid, and the order advances. This is the all-at-once path.
With tenders, and the step has one tender: that tender is marked paid when completed is true, and the order advances. Same behavior as before.
With tenders, and the step has more than one tender: only items with completed: true change. Tenders you leave out stay as they are. The order does not advance until every tender of the step is in PAID, counting the tenders in this call. Repeat the same call for each tender. The last one advances the order. Each earlier call returns 200, not an error.

Only IDLE or PENDING tenders that charge money can be marked. A tender that is already PAID is not captured again. An unknown id, or an id that is not on this order, returns 404 TENDER_NOT_FOUND. While tenders are still pending, the response includes the order in data plus:

{
  "message": "Tender updated. 2 tenders still pending to reach PAID.",
  "tenderUpdated": true,
  "pendingTenders": 2,
  "targetState": "PAID",
  "transitioned": false
}

pendingTenders is a count. One tender left uses “1 tender still pending”. When the call that finishes the set advances the order, the same fields come back with pendingTenders 0, transitioned true, and message Tender updated. Order transitioned to PAID. A tender-only update does not send an order webhook or a realtime order event. Those fire only after the order actually advances, once that step has finished its own work.

curl -X PATCH "https://firespark.cloud/api/integrations/v1/orders/ord-48291/status" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fulfillment_status": "PAID",
    "tenders": [{ "id": "tnd_cash01", "completed": true }]
  }'

Repeating the same request is safe: each tender attempt is captured once.

Response

Returns the current order in data. The advance is asynchronous, so this body can still be the snapshot from before the status you just sent.

{
  "data": {
    "id": "ord-48291",
    "status": "COMPLETED",
    "fulfillment_status": "FULFILLED",
    "payment_status": "PAID"
  }
}

Pair this endpoint with order webhooks: the webhook delivers the order when it reaches a subscribed status; this endpoint is how your POS reports the rest of the kitchen path. Do not send a terminal status (FULFILLED, VOIDED, REVERSED, REFUNDED) — those nodes are entered automatically. After the last kitchen or delivery status (for example DELIVERED), Fire spark auto-enters FULFILLED. If an awaited callback exhausts retries, it auto-enters VOIDED (unpaid) or REVERSED (paid). Cancel and refund from the dashboard still reach those terminals.

Error responses

Status	Description
`401`	Missing or invalid access token
`403`	Token does not include the `orders:write` scope
`404`	No order exists for this id, or `TENDER_NOT_FOUND` for an unknown id in `tenders`
`409`	The order is not waiting for the next status. With `PAID`: `PAYMENT_NOT_SETTLED` when `tenders` is omitted and a tender cannot be marked, or the order is not on `PAYING` and a tender is still unpaid. `TENDER_NOT_MARKABLE` when the tender is not `IDLE` / `PENDING`. Naming some tenders on a multi-tender step does not return this while others are still pending
`422`	`fulfillment_status` is a terminal status, or is not a valid next step

API Documentation

Endpoints

Guides

Resources

How this fits the order flow

When to call this endpoint

Path parameters

Request body

Mark the order paid

Response

Error responses

​How this fits the order flow

​When to call this endpoint

​Path parameters

​Request body

​Mark the order paid

​Response

​Error responses

How this fits the order flow

When to call this endpoint

Path parameters

Request body

Mark the order paid

Response

Error responses