Sign in
.md

Loyalty cancellation

A cancellation in the loyalty service does two things in opposite directions:

  • Redemption that was debited from a rewardCard is credited back to that same card (the customer gets their cashback back).
  • Reward that was credited to a rewardCard is debited from that card (the cashback earned for the cancelled purchase is removed).

Every movement is recorded in rewardCard_flow with one of four types — reward, redemption, reward_cancel, redeem_cancel — so the history is always auditable.

When to call which endpoint

Endpoint When
POST /api/loyalty/transaction/cancel/{TID} Cancel a loyalty transaction without touching the order. Reverses redemption and reward. This is also the path to release a redeem reservation that never became an order (cart abandoned, payment failed): with no reward credited yet, only the reservation is returned.
POST /api/loyalty/cancelOrderByTransaction/{TID} The whole purchase is being reverted — both the loyalty transaction and the order are cancelled together.
POST /api/loyalty/cancelPartial/{TID} Only some items of the order are being cancelled. The refund and the reward reversal are calculated proportionally to the cancelled items.
POST /api/loyalty/cards/{id}/cancel The target is a card, not a purchase: it leaves circulation with nothing debited or returned. See "Cancelling a single card" below.

The full cancel paths (transaction/cancel, cancelOrderByTransaction) reverse the entire redemption and reward of the transaction. cancelPartial operates per item — see the Partial cancellation endpoint for the exact item-matching rules.

Cancelling a single card

The endpoints above cancel what a transaction generated. When the target is a card — a campaign card granted by mistake, a manual card, a card the operation needs out of circulation — cancellation is per card:

For more than one card there is a batch version — up to 100 per call, with dryRun and one outcome per item: cancel in batch and reactivate in batch. In a batch, a card that is already canceled, missing or holding a reservation does not bring the others down: every id comes back with its own result.

The difference from the transaction endpoints is the nature of the operation:

  • cancelling a card is a change of state. The balance is neither debited nor returned, the whole card leaves circulation with its amount intact, and no line is written to rewardCard_flow. A card has no status column: canceled is derived from the cancellation timestamp.
  • cancelling a transaction is a movement. The reward is debited, the redemption is credited back, and each leaves its line in the ledger.

What that means for reporting: the cancelled card's original credit stays in rewardCard_flow, so a figure summed from the flow (credit granted) keeps counting that value, while the per-card counter counts the card as canceled. The two do not reconcile with each other — that is expected, not a bug.

To take value out of a card that stays alive, use Adjust Card Balance with manual_debit, which goes through the ledger.

A card holding an open redemption reservation is refused with 409: the reserved value was already debited and is waiting to be settled or returned, so cancelling the card would strand it. Resolve the reservation first.

Automatic cancellation via the order flow

You don't always have to call a cancel endpoint explicitly. When an order is cancelled through the order flow (for example, the source platform cancels the purchase), the loyalty side is reversed automatically, using the same logic as above:

  • A transaction still held in waitSettlement (confirmed with waitSettlement: true, not yet settled) has its reservation released — the reserved redemption is credited back. No reward was credited yet, so there is nothing to debit.
  • A transaction that was already settled has its reward rolled back and any redemption credited back, exactly as cancelOrderByTransaction would do.

This runs once the order reaches the canceled state, so a held transaction never leaves the customer's balance locked after the purchase is reverted. The movements land in rewardCard_flow with the same reward_cancel / redeem_cancel types and follow the same idempotency rule below — no double reversal if the transaction was already cancelled.

Refund of an expired card

When the redemption is refunded back to a card that has already expired at the moment of the cancellation, the customer would otherwise receive credit they can no longer use. To avoid trapping the refunded value, the loyalty service automatically extends the card's expiresAt to tomorrow at 23:59:59.

The extension is applied only when both conditions are true:

  • The card is active (canceledAt IS NULL).
  • The card is already expired (expiresAt < NOW()) at the time of the cancellation.

Cards that are still valid keep their original expiresAt — the rule never shortens or extends a non-expired card. Cards that were manually cancelled or otherwise inactive are not reactivated.

The extension is per card and per cancel: each card receiving a refund is evaluated independently. A partial cancel that splits the refund across several cards may extend some of them and leave others untouched.

Idempotency and status

A second call to any cancel endpoint after the transaction is already cancelled is rejected with 409 Conflict — the underlying transaction carries a canceledAt timestamp that is checked first. No movements are duplicated.

See also