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

# Cancelar pedido

> Cancela un pedido del cliente antes de que se cumpla. Interrumpe un workflow de fulfillment en curso.

Cancela un pedido del cliente autenticado. Fire spark actualiza estados, detiene un workflow de fulfillment en curso si lo hay, y notifica a las integraciones para que el POS anule el ticket.

La fila del pedido permanece con `status: VOIDED` (nada cobrado) o `status: REVERSED` (hubo cobro, aunque un dispositivo ya lo haya devuelto). Sus tenders quedan `CANCELLED`. No se borra.

> [!NOTE]
>
> Requiere un access token de Storefront API de [Intercambio de
> token](https://firespark.cloud/docs/es/storefront-api/oauth/exchange/post.md).

En `@fire-spark/storefront`, llama `order.cancel()`. Lee el pedido, decide `VOID` o `REVERSE`, anula los cobros del dispositivo y llama una sola vez a este endpoint con los resultados. Un pedido entregado lanza error: usa `order.refund()`. `order.cancelOrder()` sigue llamando a este endpoint sin body.

> [!WARNING]
>
> La cancelación se rechaza si el pedido ya está fulfilled. Usa [Reembolsar
> pedido](https://firespark.cloud/docs/es/storefront-api/orders/\[id]/refund/post) dentro de las 24 horas
> posteriores al fulfillment.

## Parámetros de ruta

| Parámetro | Requerido | Descripción |
| - | - | - |
| `id` | Sí | Identificador externo del pedido |

## Body

Opcional. Sin body la llamada funciona como antes. Cada campo se valida solo si se envía.

| Campo | Descripción |
| - | - |
| `device` | `{ kind: "KIOSK" \| "POS", uid, secret }`. El dispositivo que cancela. `401` con secreto incorrecto o dispositivo no vinculado, `403` si es de otro workspace. Se guarda en `metadata.cancellation` |
| `type` | `VOID` (nada cobrado) o `REVERSE` (hubo cobro). Debe coincidir con el pedido; si no, `422` con `details.code` |
| `reason` | Texto libre, se guarda en `metadata.cancellation` |
| `idempotency_key` | Clave de la llamada |
| `tenders` | Lo que hizo el dispositivo con cada cobro: `{ tender_id, attempt_reference, result: "REVERSED" \| "NOT_REVERSED", provider_reference?, metadata? }`. `REVERSED` deja el tender `CANCELLED`; `NOT_REVERSED` lo deja `PAID` con `metadata.reversal_pending` |

Un pedido ya `VOIDED` o `REVERSED` responde `200` y solo toma los tenders informados; así un dispositivo que anula un cobro más tarde lo reporta con la misma llamada.

## Solicitud

```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": "Cliente desiste",
    "tenders": [
      { "tender_id": "tnd_1", "attempt_reference": "01M641K2", "result": "REVERSED" }
    ]
  }'
```

## Respuesta

Devuelve `200` con el pedido anulado o revertido.

> [!NOTE]
>
> Si el pedido ya se envió al POS por
> [`order.status.changed`](https://firespark.cloud/docs/es/integrations-api/orders/webhooks), tu integración
> también recibe `order.voided` u `order.reversed` para anular el ticket de cocina.

```json Success theme={null}
{
  "data": {
    "id": "ord-48291",
    "status": "REVERSED",
    "fulfillment_status": "REVERSED",
    "payment_status": "CANCELLED"
  }
}
```

## Errores

| Estado | Descripción |
| - | - |
| `400` | Body mal formado o `type` desconocido |
| `401` | Token ausente o inválido, o `device` con secreto incorrecto o no vinculado |
| `403` | `device` de otro workspace (`DEVICE_SCOPE_MISMATCH`) |
| `404` | Pedido no encontrado |
| `422` | Pedido ya fulfilled (`ORDER_FULFILLED`) o no cancelable; `type` no coincide (`ORDER_CAPTURED`, `ORDER_NOT_CAPTURED`, `TYPE_STATUS_MISMATCH`, `TYPE_ENDPOINT_MISMATCH`); tender informado desconocido (`TENDER_NOT_FOUND`, `TENDER_NOT_DEVICE`, `TENDER_ATTEMPT_MISMATCH`) |


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