---
title: "This method can be used to redeem a reward in behalf of a customer."
method: POST
path: "/v1/pvt/POS/rewards/{id}/redeem"
tags: ["POS"]
---

# This method can be used to redeem a reward in behalf of a customer.

`POST /v1/pvt/POS/rewards/{id}/redeem`

There are 2 types of rewards:
- Discount Rewards: Percent (10%) or Value (R$10,00). This rewards are simples as they use pre-configured values
- Cashback: As a value (R$5,00). The used value must be informed in the `Value` field of the request body
        
They both can be used with this method. Just be aware that:
- The field `Value` must have the selected cashback value for the purchase. Use only if the reward is **Cashback** type
- For other rewards this field can be null

The `rewardId` field can be obtained by calling the `rewards/available` endpoint

The `customerId` field in the body is the same used in the `rewards/avaible` endpoint. 

## The `OriginalKey` field
This field allows you to create idempotency: even if you make the exactly same request twice it will redeem only once.
As distributed systems should be fault-tolerant it may result in requests being done more than one time. Not using the `OriginalKey` may duplicate a redeem request 

### How to use this field
Inform some string that is unique for this change. 

For instance: if you are redeeming the reward Id=OPQ for customerID=ABC regarding the OrderId=123 with Value=10,our key could be `OPQ-ABC-123-10`

If you dont need this kind of verification you can just use some time-related string, such as `2023-01-01 23:59:00:000`

## Coupon Generation
It's important to note that unlike the `customers/{id}/redeem` endpoint this call **will not** generate a coupon in BonifiQ. That is true even if the reward if configured so.

This is by design as in Point of Sale endpoints it is expected that the caller (PoS) will give the customer the necessary discounts.

## The `ExternalCode` return
One of the most important fields returned by this method is the `ExternalCode`. This field represents an External identification for this redeem. This exact value must be passed on the `Coupon` field for the Order Add Method from this API. This will make a link between the redeem and the order.


**Important**: Remember to pass the `ExternalCode` value to the `Coupon` field when adding an order

## Path parameters

- `id` integer, required

## Request body

- CouponlessRewardGenerateRequest
  - `CustomerId` string — The id of the customer. It can be email or document (CPF/CNPJ).
  - `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`.
  - `Value` number, nullable — Used only for Cashback Rewards. It the Cashback value selected by the customer. You can use either Points or Value for representing the selected amount of cashback to use.
  - `Points` integer, nullable — Used only for Cashback Rewards. It the Cashback represented by points selected by the customer. You can use either Points or Value for representing the selected amount of cashback to use.
  - `OriginalKey` string — This field allows you to create idempotency: even if you make the exactly same request twice it will consume the redeem only once. As distributed systems should be fault-tolerant it may result in requests being done more than one time. Not using the `OriginalKey` may duplicate a redeem request Inform some string that is unique for this change. For instance: if you are redeeming the reward Id=OPQ for customerID=ABC regarding the OrderId=123 with Value=10,our key could be `OPQ-ABC-123-10` If you dont need this kind of verification you can just use some time-related string, such as `2023-01-01 23:59:00:000`
  - `Metadatas` object[], nullable — Use this field as a key-value store for fields unique to your Business Use Case
    - `Name` string
    - `Value` string
  - `RedeemOrigin` 0 | 1 | 2 | 3 | 4 | 5 — 0 = LandingPage 1 = Widget 2 = Copilot 3 = Checkout 4 = API 5 = PDV
  - `Branch` CreateOrderBranch
    - `OriginalId` string — This is the Id of the branch (filial, loja, etc) in the client store. Can be any string.
    - `Name` string — This is the name of the branch. Can be any string possible
  - `SalesPerson` CreateOrderSalesPerson
    - `OriginalId` string — This is the Id of the Sales Person. Can be any string or number.
    - `Name` string — This is the name of the sales person. Can be any string.
  - `ForceGenerateCoupon` boolean, nullable — Normally this endpoint generates a redeem without a coupon. Setting this property to true forces to generate a coupon in the ecommerce plataform

## Response `200`

- 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)