---
title: "Returns a list of available rewards for a given customer and purchase."
method: POST
path: "/v1/pvt/POS/rewards/available"
tags: ["POS"]
---

# Returns a list of available rewards for a given customer and purchase.

`POST /v1/pvt/POS/rewards/available`

This method returns a list of all rewards available even if they cannot be used by the given customer at the moment.        

This method returns two types of rewards: Discounts (Value Discounts and Percent Discounts) or Cashback. Although not common, it is possible to have all types of rewards active at the same time.

## Input parameters
- `CustomerId` The id of the customer. It can be email or document (CPF/CNPJ). If a document use numbers only.
- `PurchaseValue` Current value of the order. Should NOT contains discounts, return codes (vales) or other promotions.
- `DiscountValue` If there is another discount in the order (not from BonifiQ) it can be passed here. BonifiQ use this information to return only rewards that can be used with other discounts. If no discount is being used pass `null` or `0`

## Main return properties
- `HasRewards` if this property is `false` means there are no rewards available. The entire reward flow must be skipped.
- `ShouldValidateCustomer` if `true` the flow must follow the Customer Validation Flow where an PIN CODE will be asked from the customer. If `false` the validation flow must be skipped
- `AvailablePoints` Returns the amount of points the customer currently have. This is important is Discount Rewards as the customer needs to know how many points he needes to redeem a reward.
- `CashbackEnabled` If `true` means there is a Cashback reward in the list. The customer will be able to use it if he had enough cashback
- `AvailableCashback` The amount of Cashback the customer have. It is important to note that the customer may not be able to use it entirely as there are usage rules (such as minimum purchase value). 
- `MaxCashbackForCurrentPurchase` This is the maximum cashback the customer will be able to use in the current purchase. It maybe different from `AvailableCashback` as this property take into account usage rules.

## Discounts Rewards
A discount reward offers some discount in exchange of an amount of points. The discount can be a Value (R$10,00 discount in exchange of 100 points) or Percent (15% discount in exchange of 1000 points)-
            
A discount reward cannot be used partially. Customer must either use all the value or don`t use at all.

It is possible (and rather common) to have multiple Discount Rewards active at same time (for instance: R$10,00 for 10 points, R$30,00 for 25 points, 10% for 15 points, etc)

### Important properties
`Title` 
Represents brief user-friendly description of the reward (such as "R$50,00 de desconto", "10% de desconto", "R$50,00 em cashback")

 `CanUse`
Despite the fact the API returns all available rewards you have to check the `CanUse` property to allow the customer to use this reward. The `CanUse` property will be `true` when the customer have enought points and the purchase value is within the configured minimum amount.
            
If the `CanUse` property is `false` you can still show the reward to the customer (in a disabled state). This is useful for him to known which rewards he can redeem in the future.
            
 `Requirements` 
This is an optional string detailing restrictions regarding the Reward such as: Minimum amount of purchase, percent relative to the purchase, etc. It is a user-friendly string so you can show it to the user alongside the reward name and points.

 `Points` This is the cost in points of this reward. It is useful to the customer to know how many points will be deduct from him when this reward is redeemed.

 `Value` For Value Discount this represents the value in cash (eg: 10.00 for a R$10,00 reward). For Percent Discount this is the percent value (eg: 10.00 for a 10% discount). 
 This property is useful for you to apply the discount in the customer purchase on behalf of BonifiQ.   
 
 `RewardCanBeCumulative` If `true` the customer can use this reward in conjunction with other discounts. If `false` the customer can only use this reward if there is no other discount in the order.

## Cashback Reward
A Cashback reward also offers an value discount in exchange of points but the amount can be selected by the customer. For instance: the customer can have R$10,00 of cashback balance but decide to use just R$5,00.

As the value can be selected, it is necessary to ask de customer for the value he wants to use and use it in redeem

A Cashback maybe not present in the reward list as it could be disabled. 

### Important properties

Some properties are the same of Discounts Rewards (see above). A few other are exclusive for Cashback
- `CashbackEnabled` if `true` the cashback exist and is active. However the user could not be able to use it as he may not have enough balance.
- `AvailableCashback` Total amount of cashback the use have.
- `MaxCashbackForCurrentPurchase` This is the maximum amount of cashback that can be used in the current purchase. The value may differ from `AvailableCashback` due to purchase rules such as minimum value.
- `IsCashback` Returns `true` if this is a cashback reward. If so, we need to ask the customer for the amount he wants to use upon redeeming

## Request body

- RewardConfigSimulateRequest
  - `CustomerId` string — The id of the customer. It can be email or document (CPF/CNPJ). If a document use numbers only.
  - `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`.
  - `PurchaseValue` number — Current value of the order. Should not contains discounts or other promotions.
  - `DiscountValue` number, nullable — If there is another discount in the order (not from BonifiQ) it can be passed here. BonifiQ use this information to return only rewards that can be used with other discounts.
  - `Products` object[], nullable — Optional: List of products for cashback eligibility validation. If provided, restricted products will be filtered and the cashback will be calculated based only on eligible items. If not provided, the full PurchaseValue will be used (backward compatible behavior).
    - `OriginalId` string — External product identifier from the e-commerce platform (SKU, barcode, etc.)
    - `Title` string — Product name/title
    - `IsActive` boolean — Whether the product is active
    - `ProductPrice` number, nullable — Product regular price
    - `ProductDiscountPrice` number, nullable — Product promotional/discount price
    - `ProductBrand` RewardAvailableProductBrand — Represents a product brand for the rewards/available endpoint
      - `OriginalId` string, nullable — External brand identifier
      - `Name` string, nullable — Brand name
    - `ProductCategory` RewardAvailableProductCategory — Represents a product category for the rewards/available endpoint. Supports hierarchical categories through ParentCategory.
      - `OriginalId` string, nullable — External category identifier
      - `Name` string, nullable — Category name
      - `ParentCategory` RewardAvailableProductCategory — recursive

## Response `200`

- RewardConfigSimulateResponse
  - `Customer` RewardConfigSimulateCustomerResponse
    - `Id` integer
    - `OriginalId` string
    - `Name` string
    - `Email` string
    - `Phone` string, nullable
    - `Document` string, nullable
    - `IsEnrolled` boolean
    - `CurrentTier` CustomerTierResponse
      - `Name` string
      - `Color` string
      - `IconUrl` string
  - `Rewards` object[] — A list of all available rewards regardless if the user can redeem it or not. Even if the user doest not have enought points to redeem a reward it is still usefull for him
    - `Id` integer — Unique ID for this reward. Used afterwards for redeeming
    - `Title` string — Name of this reward. Can be shown to the user
    - `RewardType` 0 | 1 | 2 | 3 | 4 — 0 = PercentDiscountCoupon 1 = ValueDiscountCoupon 2 = FreightDiscountCoupon 3 = PointToCashback 4 = Customized
    - `Value` number — Value of the reward, if applicable. Eg: For Percent Discount Returns the discount percent value: 10.00 for 10% discount For Value Discount Returns the discount amount in R$: 10.00 for R$10,00 discount For Cashback Returns how much a single point is worth. This is not much of useful for returning to the user so using the **AvailableCashback** field for this scenário should be preferred For Customized Always returns zero
    - `CanSelectValue` boolean — Returns true if the customer can select the amount of cashback he wants to use. Uses in cashback only.
    - `IsCashback` boolean — Returns true if this is a Cashback reward. A Cashback reward is special in a sense that its amount can be selected by the customer.
    - `Requirements` string — All the requirements to use this reward in a user-friendly text. Can be shown to the user. The possible Requirements are: - Minimum Purchase Value - Maximum Cashback that can be used in this purchase
    - `AvailableCashback` number — This is the total Cashback the customer currently have. Its not necessarily the amount the user can use as there as some usage rules (see the MaxCashbackForCurrentPurchase field).
    - `MaxCashbackForCurrentPurchase` number — The maximum amount that can be used for the current purchase order value Cashback have some rules to use such as: in order to spend R$10,00 in cashback the total order value must be of at least R$50,00. In this scenario, the user could have a total amount of available cashback (AvailableCashback) of R$20,00 but as the rule requires at least R$50,00 of purchase he can only use R$10,00. That way even if the customer have a certain amount of Cashback BonifiQ caps this value to the maxium amount he can use for the current purchase, according to rules
    - `CanUse` boolean — If true the customer can use this reward. It can be useful to shown to customers what are the rewards he can use in the future by gaining more points.
    - `Points` integer — How many points will be spent in this reward. This is useful for Percent and Value Discounts so the user will be aware of how many points he is using. It`s also useful to shown users which rewards he will have acces in the future with more points. For cashback it represents the MaxCashbackForCurrentPurchase value.
    - `RewardCanBeCumulative` boolean — If true the user can use this reward in conjunction with other discounts. If false the user can only use this reward if there is no other discount in the order.
  - `HasRestrictedItems` boolean — True if any items were restricted from cashback eligibility. Only populated when Items are provided in the request.
  - `RestrictedValue` number — Total value of restricted items that cannot receive cashback. Only populated when Items are provided in the request.
  - `EligibleValue` number — Total value eligible for cashback (after filtering restricted items). Only populated when Items are provided in the request.
  - `HasRewards` boolean — False if there is no available rewards to redeem. In this case the flow should proceed without showing any information to the user
  - `ShouldValidateCustomer` boolean — If true the caller must follow the Validation flow, calling the BonifiQ API to request a token-code from customer. If false the flow can be directed to conclusion
  - `ShouldValidateCustomerSignup` boolean — If true the caller must validate the customer signup before considering the customer enrolled.
  - `AvailablePoints` integer — How many points the customer have. It is useful in scenarios without cashback where rewards are fully point-based.
  - `CashbackEnabled` boolean — Returns true if exists a cashback reward. In this case the user will need to be aware of how much Cashback is Available
  - `AvailableCashback` number — Returns the total amount of cashback the user have. Will be 0 if CashbackEnable=false.
  - `MaxCashbackForCurrentPurchase` number — The maximum amount that can be used for the current purchase order value Cashback have some rules to use such as: in order to spend R$10,00 in cashback the total order value must be of at least R$50,00. In this scenario, the user could have a total amount of available cashback (AvailableCashback) of R$20,00 but as the rule requires at least R$50,00 of purchase he can only use R$10,00. That way even if the customer have a certain amount of Cashback BonifiQ caps this value to the maxium amount he can use for the current purchase, according to rules

---

[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/070a57eeffdc/schema)