---
title: 'Cancelación en loyalty'
description: 'Cómo el servicio de loyalty revierte el canje y la acumulación cuando se cancela un pedido o una reserva de canje.'
---

# Cancelación en loyalty

Una cancelación en el servicio de loyalty hace dos cosas en direcciones opuestas:

- El **canje** que se había debitado de un `rewardCard` se **acredita de vuelta** en el mismo card (el cliente recupera su cashback).
- La **acumulación** que se había acreditado en un `rewardCard` se **debita** de ese card (el cashback generado por la compra cancelada se remueve).

Cada movimiento queda registrado en `rewardCard_flow` con uno de los cuatro tipos — `reward`, `redemption`, `reward_cancel`, `redeem_cancel` — de modo que el historial siempre es auditable.

## Cuándo usar cada endpoint

| Endpoint | Cuándo usar |
|---|---|
| `POST /api/loyalty/transaction/cancel/{TID}` | Cancelar una transacción de loyalty, sin tocar el pedido. Revierte el canje y la acumulación. También es el camino para liberar una reserva de canje que nunca se convirtió en pedido (carrito abandonado, falla de pago): al no haber acumulación todavía, solo se devuelve la reserva. |
| `POST /api/loyalty/cancelOrderByTransaction/{TID}` | Toda la compra se está revirtiendo — la transacción de loyalty y el pedido se cancelan juntos. |
| `POST /api/loyalty/cancelPartial/{TID}` | Solo algunos ítems del pedido se están cancelando. El reembolso y la reversión de la acumulación se calculan proporcionalmente a los ítems cancelados. |
| `POST /api/loyalty/cards/{id}/cancel` | El objetivo es un **card**, no una compra: sale de circulación sin que nada se debite ni se devuelva. Vea la sección "Cancelar un card específico" más abajo. |

Las rutas de cancelación total (`transaction/cancel`, `cancelOrderByTransaction`) revierten **toda** la redención y acumulación de la transacción. `cancelPartial` opera por ítem — vea el endpoint de [Cancelación parcial](/docs/{lang}/api-reference/loyalty/checkout/partial-cancellation) para las reglas exactas de identificación de ítems.

## Cancelar un card específico

Los endpoints anteriores cancelan lo que generó una **transacción**. Cuando el objetivo es un card — un card de campaña otorgado por error, un card manual, un card que la operación necesita sacar de circulación —, la cancelación es por card:

- [`POST /api/loyalty/cards/{id}/cancel`](/docs/{lang}/api-reference/loyalty/card/cancel) — el card sale de toda consulta de saldo y se lee como `canceled`
- [`POST /api/loyalty/cards/{id}/reactivate`](/docs/{lang}/api-reference/loyalty/card/reactivate) — deshace la cancelación, sin tocar la vigencia

Para más de un card existe la versión en lote — hasta 100 por llamada, con `dryRun` y un desenlace por item: [cancelar en lote](/docs/{lang}/api-reference/loyalty/card/cancel-batch) y [reactivar en lote](/docs/{lang}/api-reference/loyalty/card/reactivate-batch). En un lote, un card ya cancelado, inexistente o con reserva abierta **no** tumba a los demás: cada id vuelve con su propio resultado.

La diferencia frente a los endpoints de transacción es la **naturaleza** de la operación:

- cancelar un card es un cambio de **estado**. El saldo no se debita ni se devuelve, el card completo sale de circulación con su `amount` intacto y **no entra ninguna línea en `rewardCard_flow`**. El card no tiene columna de estado: `canceled` se deriva de la fecha de cancelación.
- cancelar una transacción es un **movimiento**. La acumulación se debita, el canje se acredita de vuelta, y cada uno deja su línea en el ledger.

Consecuencia práctica en los reportes: el crédito original del card cancelado permanece en `rewardCard_flow`, así que una cifra sumada por el flow (crédito otorgado) sigue contando ese valor, mientras que el contador por card cuenta el card como `canceled`. Los dos no cuadran entre sí — es lo esperado, no un error.

Para sacar valor de un card que **sigue vivo**, use [Ajustar saldo del card](/docs/{lang}/api-reference/loyalty/card/adjust) con `manual_debit`, que pasa por el ledger.

Un card con **reserva de canje abierta** se rechaza con `409`: el valor reservado ya fue debitado y espera liquidación o devolución, así que cancelar el card lo dejaría atrapado. Resuelva la reserva primero.

## Cancelación automática por el flujo del pedido

No siempre hay que llamar a un endpoint de cancelación explícitamente. Cuando un pedido se cancela por el flujo del pedido (por ejemplo, la plataforma de origen cancela la compra), el lado de loyalty se revierte automáticamente, con la misma lógica de arriba:

- Una transacción aún retenida en `waitSettlement` (confirmada con `waitSettlement: true`, todavía no liquidada) tiene su **reserva liberada** — el canje reservado se acredita de vuelta. Aún no se acreditó ninguna acumulación, así que no hay nada que debitar.
- Una transacción que ya fue liquidada tiene su **acumulación revertida** y cualquier canje acreditado de vuelta, exactamente como lo haría `cancelOrderByTransaction`.

Esto corre en cuanto el pedido llega al estado `canceled`, de modo que una transacción retenida nunca deja el saldo del cliente bloqueado después de revertir la compra. Los movimientos quedan en `rewardCard_flow` con los mismos tipos `reward_cancel` / `redeem_cancel` y siguen la misma regla de idempotencia de abajo — sin reversión doble si la transacción ya estaba cancelada.

## Reembolso en card expirado

Cuando el canje se acredita de vuelta en un card que **ya está expirado** en el momento de la cancelación, el cliente recibiría un crédito que ya no podría usar. Para no atrapar el valor reembolsado, el loyalty extiende automáticamente el `expiresAt` del card para **mañana a las 23:59:59**.

La extensión se aplica **solo** cuando se cumplen las dos condiciones:

- El card está **activo** (`canceledAt IS NULL`).
- El card está **efectivamente expirado** (`expiresAt < NOW()`) al momento de la cancelación.

Los cards aún dentro de la vigencia mantienen su `expiresAt` original — la regla nunca acorta ni extiende un card no expirado. Los cards cancelados manualmente o inactivos por otro motivo no se reactivan.

La extensión es **por card y por cancelación**: cada card que recibe reembolso se evalúa de forma independiente. Una cancelación parcial que divide el reembolso entre varios cards puede extender algunos y dejar otros intactos.

## Idempotencia y estado

Una segunda llamada a cualquier endpoint de cancelación después de que la transacción ya está cancelada se rechaza con `409 Conflict` — la transacción lleva un `canceledAt` que se verifica primero. Ningún movimiento se duplica.

## Vea también

- [Cancelar una transacción](/docs/{lang}/api-reference/loyalty/transaction/cancel)
- [Cancelar transacción y pedido](/docs/{lang}/api-reference/loyalty/checkout/cancel-transaction-and-order)
- [Cancelación parcial](/docs/{lang}/api-reference/loyalty/checkout/partial-cancellation)
- [Cancelar card](/docs/{lang}/api-reference/loyalty/card/cancel)
- [Reactivar card](/docs/{lang}/api-reference/loyalty/card/reactivate)
