# Redemption lifecycle

A redemption starts when the customer views a wallet balance or applies points to a cart. It ends when the hold is confirmed by an order-placed event or reverted after the allowed window.

Redemption lifecycle from wallet lookup and cart hold to order confirmation or timeout reversion
center
em
Figure 1: Cart redemption hold, confirmation, and timeout reversion
## Request sequence

1. **Get the wallet balance:** The storefront or POS requests the wallet balance using the Engage user ID.
2. **Resolve the customer:** Engage calls the partner customer-search operation using the customer's mobile number.
3. **Return the available balance:** The partner returns the current available balance.
4. **Map the wallet:** Engage maps the provider response into the Engage wallet schema.
5. **Apply points:** The storefront or POS applies points using the cart ID.
6. **Create the hold:** Engage calls the provider redemption operation with `action:perform` and reference `<salesChannelId>:<cartId>`.
7. **Return the discount:** The provider returns the discount and hold transaction.
8. **Apply the discount:** Engage returns the mapped discount to the storefront or POS.


## Hold outcomes

Order placed
When Fynd Commerce emits the matching order-placed webhook within the allowed window, the partner confirms the hold using `order.cart_info.cart_object_id` to resolve the cart reference.

The order-placed event confirms the redemption. Earned points are credited later, after the applicable shipment reaches a terminal delivery status.

No order placed
If no order-placed event arrives within the agreed window, the partner automatically reverts the hold using the original reference ID.

The Engage native engine uses a 15-minute default. The timeout for a third-party integration is agreed with the partner and enforced by the partner system.

## Explicit cancellation

Engage exposes `POST /v2/order/transaction/cancel`, which maps to the partner `cancelOrder` adapter method. The provider reverts the hold with `action:revert` using the original redemption reference.

Credit compared with hold
The order-placed event confirms the points spent by the customer. Earned points are credited only when a shipment reaches `delivery_done` or `handed_over_to_customer`. When a shipment is cancelled or a refund is initiated, reverse points against that shipment's `loyalty_discount` value

## Idempotency requirements

- Treat `<salesChannelId>:<cartId>` as the unique redemption reference.
- Support perform, confirm, and revert operations against the same reference.
- Return a consistent result when an event or request is retried.
- Prevent a confirmed hold from being reverted by the timeout job.


Continue to [Webhooks](/engage/partner-integrations/webhooks) for event names, payload fields, and shipment status actions.