This endpoint allows you to apply cashback discount to a checkout/cart.

Input Parameters

• CustomerId (required): The customer identifier (email or document/CPF)
• CheckoutId (required): The checkout/cart ID from the e-commerce platform
• CashbackValue (optional): The specific amount of cashback to apply. If not provided, the maximum available cashback will be used.
• Total (optional): The checkout total value. Used for validation.
• OriginalKey (optional): A unique key to identify this redemption (for idempotency). For VTEX, omit it (recommended) or use exactly checkout-{CheckoutId} with the actual cart ID; do not use an unrelated partner reference.

Response

On success, returns the reward information including:

• RewardId: The unique ID for this reward
• ExternalCode: Code to be used when sending orders to BonifiQ
• OriginalKey: The key identifying this redemption
• Point: Information about the points used
• Coupon: The coupon information (if generated)

Important Notes

• VTEX automatic checkout discovery and cleanup depend on the cart identity in ExternalCode. An unrelated OriginalKey, even one starting with checkout-, is unsupported for these flows: redemption currently accepts it without format validation, but automatic refund may preserve the debit because the cart cannot be identified and its cleanup cannot be confirmed. The caller is responsible for the compatible key; this restriction does not add automatic repair for existing redemptions.
• If the customer already has cashback applied in another checkout (without an order), it will be automatically refunded.
• The cashback value cannot exceed the checkout total or the customer's available cashback balance.
• VTEX orphaned reward markers or unidentified manual discounts block application with HTTP 400, existing code 09 / CashbackRedeemFailed, an explanatory message and no reward in Result (instead of a technical error). A known existing reward keeps 10 / CashbackAlreadyApplied. No marker or manual price is automatically removed.
• 22 / CashbackApplicationUncertain returns HTTP 400, HasError = true and Severity = Error: the reward/debit was persisted but remote application or rollback could not be confirmed. Result identifies that reward (RewardId, OriginalKey, Point) for reconciliation; it is NOT proof of applied cashback. Do not create another redeem with a new key or refund blindly. Verify checkout/order state using these identifiers. The existing checkout recovery is registered; absent identity or residual discount can still require manual analysis.