---
title: "Redeems cashback for a checkout"
method: POST
path: "/v1/pvt/Checkout/redeem"
tags: ["Checkout"]
---

# Redeems cashback for a checkout

`POST /v1/pvt/Checkout/redeem`

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)

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

## Request body

- ExternalApiCheckoutRedeemRequest — Request to redeem cashback in a checkout
  - `CustomerId` string — Customer identifier (email or document/CPF)
  - `Customer` ExternalApiCustomerIdentifierRequest — Optional customer identifiers used when the tenant configuration changes which value is used as the customer's OriginalId.
    - `Document` string, nullable — Customer document. Required when `Checkout.CustomerOriginalIdSource` is set to `document`. The value is normalized to digits only before the customer lookup.
    - `Email` string, nullable — Customer e-mail. Required when `Checkout.CustomerOriginalIdSource` is set to `email`.
  - `CheckoutId` string — The checkout/cart ID from the e-commerce platform
  - `CashbackValue` number, nullable — Optional: The specific amount of cashback to apply. If not provided, the maximum available cashback will be used.
  - `Total` number, nullable — Optional: The checkout total value. Used for validation.
  - `Token` string, nullable — Optional: Platform-specific token for the checkout
  - `OriginalKey` string, nullable — Optional: A unique key to identify this redemption (for idempotency)
  - `Items` object[], nullable — Optional: List of order items for cashback eligibility validation. If provided, only eligible items will be considered for cashback calculation. If not provided, the full order total will be used (backward compatible behavior).
    - `ExternalProductId` string, nullable — External product identifier from the e-commerce platform
    - `Value` number — Item value (price * quantity)
    - `Quantity` integer — Quantity of the item

## Response `200`

The reward information

- BaseExternalApiResponseOfCouponlessRewardRedeemResponse — Standard response envelope used by the External API.
  - `ErrorMessage` string, nullable — Error message returned when the request fails validation or processing. For warnings and successful responses, consumers should usually inspect `Result`, `Code` and `Severity` first.
  - `ErrorCode` integer, nullable — Legacy numeric error code derived from internal API errors when available. This field is relevant only for error flows that use `ApiResponseErrorDescription`.
  - `Result` CouponlessRewardRedeemResponse
    - `RewardId` integer — This is the unique-id for this reward
    - `Point` CouponlessRewardRedeemPointResponse
      - `PointId` integer
      - `Quantity` integer
      - `Metadatas` object[], nullable
        - `Name` string
        - `Value` string
    - `ExternalCode` string — When sending orders to BonifiQ use this field value in the `Coupon` field for the Order This is necessary so we know that this order used this reward
    - `OriginalKey` string — This is the key that was send in the redeem request
    - `Coupon` RewardRedeemCoupon
      - `CouponCode` string
      - `CouponType` 0 | 1 | 2 | 3 | 4 — 0 = FixedValue 1 = Percent 2 = FreeShipping 3 = DiscountShipping 4 = Others
      - `CouponValue` number
      - `ValidDateStart` string, date-time, nullable
      - `ValidDateEnd` string, date-time, nullable
  - `Code` string, nullable — Endpoint-specific business code formatted as a two-digit string, such as `03` or `07`. This field is available for success, warning and error outcomes.
  - `CodeName` string, nullable — Symbolic enum name associated with `Code`, such as `CheckoutNotFound`.
  - `Severity` 0 | 1 | 2 — 0 = Success 1 = Warning 2 = Error
  - `HasWarning` boolean — Convenience flag that is `true` when `Severity` is `Warning`. Warnings are valid `200 OK` business outcomes and should not be handled as transport or validation errors.
  - `HasError` boolean — Indicates whether the request failed and should be handled as an error response. This flag is reserved for real API errors; warnings must keep this property as `false`.

---

[API](https://skmtc.net/bonifiq/apis/bonifiq-private-apis.md) · [All operations](https://skmtc.net/bonifiq/apis/bonifiq-private-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/bonifiq/bonifiq-private-apis/revisions/fafbe5673edc/schema)