> ## Documentation Index > Fetch the complete documentation index at: https://developers.bonifiq.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Returns a list of available rewards for a given customer and purchase. > 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 ## OpenAPI ````yaml https://api.bonifiq.com.br/swagger/Private%20APIs/swagger.json post /v1/pvt/POS/rewards/available openapi: 3.0.0 info: title: BonifiQ Private APIs description: >- # Introduction This is the BonifiQ Private APIs documentation. With these endpoints you can interact with BonifiQ systems and enhance your program points. # Limitations These endpoints are intended to be used in backend communication so they are not CORS-compatible and cannot be used by in-browser frontend libraries (such as React, Angular, Vue, jQuery, etc) If are required to call BonifiQ API from a browser, please refer to our [Public APIs](https://api.bonifiq.com.br/apidocs/public) # Authentication These Private APis use the [Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) scheme. You need both an API Token (Username) and API Key (Password) to use with it You can generate this key pair in BonifiQ admin panel, at the "API Keys" menu. # How to use this page ## Making calls You can simulate, test and make calls to API from this Swagger page. To do that: - Click on the **Authorize** button - Inform the Username (API Token) and Passwoird (API Key) and click on **Authorize** - From the list bellow, choose an API call and click on **Try it out** - Inform the required parameters (if any) and click on **Execute** ## Verifying requests and responses bodies In every API Call there is an explanation of what each field means, theirs types and accepted values for all Requests and Responses. To view this information, just go to any API Call bellow and in the Responses section, click on the Schema. version: 1.0.0 servers: - url: https://api.bonifiq.com.br security: [] tags: - name: POS description: >- Flow methods to integrate BonifiQ with a POS system. Check the Flow Documentation link on the right externalDocs: description: Flow Documentation url: >- https://suporte.bonifiq.com.br/support/solutions/articles/159000319538-integrar-com-pdv - name: Checkout description: Operations related to checkout cashback redeem, refresh and removal - name: Customization description: Retrieve customizations for the loyalty program - name: Rewards description: Interact with rewards already redeemed paths: /v1/pvt/POS/rewards/available: post: tags: - POS summary: Returns a list of available rewards for a given customer and purchase. description: >- 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 operationId: POS_AvailableRewards requestBody: x-name: request content: application/json: schema: $ref: '#/components/schemas/RewardConfigSimulateRequest' required: true x-position: 1 responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/RewardConfigSimulateResponse' security: - Basic Authentication: [] components: schemas: RewardConfigSimulateRequest: type: object additionalProperties: false properties: CustomerId: type: string description: >- The id of the customer. It can be email or document (CPF/CNPJ). If a document use numbers only. PurchaseValue: type: number description: >- Current value of the order. Should not contains discounts or other promotions. format: decimal DiscountValue: type: number description: >- 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. format: decimal nullable: true Products: type: array description: >- 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). nullable: true xml: wrapped: true items: xml: name: RewardAvailableProductItem oneOf: - $ref: '#/components/schemas/RewardAvailableProductItem' RewardConfigSimulateResponse: type: object additionalProperties: false properties: Customer: description: >- Customer data resolved from the informed id. Can be null when the customer is not found. nullable: true oneOf: - $ref: '#/components/schemas/RewardConfigSimulateCustomerResponse' Rewards: type: array description: >- 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 xml: wrapped: true items: xml: name: RewardConfigSimulateResponseItem oneOf: - $ref: '#/components/schemas/RewardConfigSimulateResponseItem' HasRestrictedItems: type: boolean description: |- True if any items were restricted from cashback eligibility. Only populated when Items are provided in the request. RestrictedValue: type: number description: |- Total value of restricted items that cannot receive cashback. Only populated when Items are provided in the request. format: decimal EligibleValue: type: number description: >- Total value eligible for cashback (after filtering restricted items). Only populated when Items are provided in the request. format: decimal HasRewards: type: boolean description: >- False if there is no available rewards to redeem. In this case the flow should proceed without showing any information to the user ShouldValidateCustomer: type: boolean description: >- 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: type: boolean description: >- If true the caller must validate the customer signup before considering the customer enrolled. AvailablePoints: type: integer description: >- How many points the customer have. It is useful in scenarios without cashback where rewards are fully point-based. format: int32 CashbackEnabled: type: boolean description: >- Returns true if exists a cashback reward. In this case the user will need to be aware of how much Cashback is Available AvailableCashback: type: number description: >- Returns the total amount of cashback the user have. Will be 0 if CashbackEnable=false. format: decimal MaxCashbackForCurrentPurchase: type: number description: >- 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 format: decimal RewardAvailableProductItem: type: object description: >- Represents a product item for the rewards/available endpoint. This is a simplified model containing only the fields needed for cashback eligibility validation. additionalProperties: false properties: OriginalId: type: string description: >- External product identifier from the e-commerce platform (SKU, barcode, etc.) example: 530648963003 Title: type: string description: Product name/title example: CAMISA ML SLIM VICHY MELANGE 13 2601 001 - VERDE ESCURO - 3 IsActive: type: boolean description: Whether the product is active ProductPrice: type: number description: Product regular price format: decimal nullable: true example: 499.9 ProductDiscountPrice: type: number description: Product promotional/discount price format: decimal nullable: true example: 50.5 ProductBrand: description: Product brand information nullable: true oneOf: - $ref: '#/components/schemas/RewardAvailableProductBrand' ProductCategory: description: Product category information (supports hierarchical categories) nullable: true oneOf: - $ref: '#/components/schemas/RewardAvailableProductCategory' RewardConfigSimulateCustomerResponse: type: object additionalProperties: false properties: Id: type: integer format: int32 OriginalId: type: string Name: type: string Email: type: string Phone: type: string nullable: true Document: type: string nullable: true IsEnrolled: type: boolean CurrentTier: nullable: true oneOf: - $ref: '#/components/schemas/CustomerTierResponse' RewardConfigSimulateResponseItem: type: object additionalProperties: false properties: Id: type: integer description: Unique ID for this reward. Used afterwards for redeeming format: int32 Title: type: string description: Name of this reward. Can be shown to the user example: R$50,00 de desconto RewardType: description: |- Type of the reward 0 Percent Discount (eg: 15% off) 1 Value Discount (eg: R$10,00) 2 Not Used 3 Cashback (eg: R$10,00 on purchases of at least R$30,00) 4 Customized Reward (eg: Uma toalha de Brinde) oneOf: - $ref: '#/components/schemas/RewardType' Value: type: number description: >- 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 format: decimal CanSelectValue: type: boolean description: >- Returns true if the customer can select the amount of cashback he wants to use. Uses in cashback only. IsCashback: type: boolean description: >- 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: type: string description: >- 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 example: Válido para compras acima de R$50,00. AvailableCashback: type: number description: >- 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). format: decimal MaxCashbackForCurrentPurchase: type: number description: >- 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 format: decimal CanUse: type: boolean description: >- 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: type: integer description: >- 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. format: int32 RewardCanBeCumulative: type: boolean description: >- 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. RewardAvailableProductBrand: type: object description: Represents a product brand for the rewards/available endpoint additionalProperties: false properties: OriginalId: type: string description: External brand identifier nullable: true example: Vichy Name: type: string description: Brand name nullable: true example: VC0112 RewardAvailableProductCategory: type: object description: |- Represents a product category for the rewards/available endpoint. Supports hierarchical categories through ParentCategory. additionalProperties: false properties: OriginalId: type: string description: External category identifier nullable: true example: CA123 Name: type: string description: Category name nullable: true example: Camisas ParentCategory: description: Parent category (for hierarchical categories) nullable: true example: null oneOf: - $ref: '#/components/schemas/RewardAvailableProductCategory' CustomerTierResponse: type: object additionalProperties: false properties: Name: type: string Color: type: string IconUrl: type: string RewardType: type: integer description: |- 0 = PercentDiscountCoupon 1 = ValueDiscountCoupon 2 = FreightDiscountCoupon 3 = PointToCashback 4 = Customized x-enumNames: - PercentDiscountCoupon - ValueDiscountCoupon - FreightDiscountCoupon - PointToCashback - Customized enum: - 0 - 1 - 2 - 3 - 4 securitySchemes: Basic Authentication: type: http description: Use API Basic Auth Keys name: Basic Authentication in: header scheme: basic ````