> ## 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.

# Cancel order

> Cancel a customer order before it is fulfilled. Interrupts a running fulfillment workflow.

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.

> [!NOTE]
>
> Requires a Storefront API access token from [Token
> exchange](https://firespark.cloud/docs/storefront-api/oauth/exchange/post.md).

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.

> [!WARNING]
>
> Cancel is rejected once the order is fulfilled. Use [Refund
> order](https://firespark.cloud/docs/storefront-api/orders/\[id]/refund/post) 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

```bash theme={null}
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.

> [!NOTE]
>
> If the order was already sent to the POS via
> [`order.status.changed`](https://firespark.cloud/docs/integrations-api/orders/webhooks), your integration
> should also receive an `order.voided` or `order.reversed` webhook so the
> kitchen ticket can be voided.

```json Success theme={null}
{
  "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`) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.