Cancel order

Cancels an order for the authenticated customer. Fire spark updates order and fulfillment statuses, stops a running fulfillment workflow if one is in progress, and notifies connected integrations so the POS can void the ticket. The order row stays in place with status: VOIDED (nothing charged) or status: REVERSED (something was charged, even if a device already gave it back). Its tenders end CANCELLED. It is not deleted.

Requires a Storefront API access token from Token exchange.

In @fire-spark/storefront, call order.cancel(). It reads the order, decides VOID or REVERSE, voids the device charges and calls this endpoint once with the results. A delivered order throws: use order.refund(). order.cancelOrder() still calls this endpoint without a body.

Cancel is rejected once the order is fulfilled. Use Refund order within 24 hours of fulfillment instead.

Path parameters

Parameter	Required	Description
`id`	Yes	External order identifier

Request body

Optional. Without a body the call works as before. Each field is checked only when sent.

Field	Description
`device`	`{ kind: "KIOSK" \| "POS", uid, secret }`. The device that cancels. `401` with a bad secret or a device not linked, `403` for another workspace. Stored in `metadata.cancellation`
`type`	`VOID` (nothing charged) or `REVERSE` (charged). Must match the order, else `422` with `details.code`
`reason`	Free text, stored in `metadata.cancellation`
`idempotency_key`	Key of the call
`tenders`	What the device did with each charge: `{ tender_id, attempt_reference, result: "REVERSED" \| "NOT_REVERSED", provider_reference?, metadata? }`. `REVERSED` ends the tender `CANCELLED`; `NOT_REVERSED` keeps it `PAID` with `metadata.reversal_pending`

An order already VOIDED or REVERSED answers 200 and only takes the reported tenders, so a device that voids a charge later can report it with the same call.

Request

curl -X POST "https://firespark.cloud/api/storefront/v1/orders/ord-48291/cancel" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "device": { "kind": "KIOSK", "uid": "DEVICE_UID", "secret": "DEVICE_SECRET" },
    "type": "REVERSE",
    "reason": "Customer changed their mind",
    "tenders": [
      { "tender_id": "tnd_1", "attempt_reference": "01M641K2", "result": "REVERSED" }
    ]
  }'

Response

Returns 200 with the voided or reversed order.

If the order was already sent to the POS via order.status.changed, your integration should also receive an order.voided or order.reversed webhook so the kitchen ticket can be voided.

{
  "data": {
    "id": "ord-48291",
    "status": "REVERSED",
    "fulfillment_status": "REVERSED",
    "payment_status": "CANCELLED"
  }
}

Error responses

Status	Description
`400`	Malformed body or unknown `type`
`401`	Missing or invalid access token, or `device` with a bad secret or not linked
`403`	`device` of another workspace (`DEVICE_SCOPE_MISMATCH`)
`404`	Order not found
`422`	Order is already fulfilled (`ORDER_FULFILLED`) or cannot be cancelled; `type` does not match (`ORDER_CAPTURED`, `ORDER_NOT_CAPTURED`, `TYPE_STATUS_MISMATCH`, `TYPE_ENDPOINT_MISMATCH`); a reported tender is unknown (`TENDER_NOT_FOUND`, `TENDER_NOT_DEVICE`, `TENDER_ATTEMPT_MISMATCH`)

API Documentation

Endpoints

Guides

Resources

Path parameters

Request body

Request

Response

Error responses

​Path parameters

​Request body

​Request

​Response

​Error responses

Path parameters

Request body

Request

Response

Error responses