---
title: "Estimates points, cashback earned and cashback usage limits per product."
method: POST
path: "/v1/pub/Product/pointslist"
tags: ["Product"]
---

# Estimates points, cashback earned and cashback usage limits per product.

`POST /v1/pub/Product/pointslist`

## Request

- Base URL: `https://api.bonifiq.com.br`
- URL: `https://api.bonifiq.com.br/v1/pub/Product/pointslist`
- Auth: API key in header `X-BQ-ApiToken`

Send an array of products with the store's external `Id` and current `Price`.
Each item is estimated independently. Response order and repeated IDs are preserved.
`Name` and `PriceCurrency` are optional; no currency conversion is performed.
            
### Cashback earned
            
- `Points`: estimated points after bonuses, limits and zero-point rules.
- `Cashback`: cashback earned from those points, truncated to whole currency units.
- `CashbackPercent`: earned percentage before monetary truncation, rounded upward to a whole percentage. Do not calculate it from `Cashback / Price`.
            
### Cashback you can use
            
- `CanUseCashback`: `false` for a restricted product; `true` for a permitted or unknown product, including when restrictions are disabled or empty.
- `CanUseCashbackPercent`: maximum percentage of the price payable with cashback, assuming sufficient balance. Preserves the configured percentage and fractions, reduced by the monetary cap when applicable. Redemption rounding is not applied here.
            
A restricted product can still earn cashback. For a positive price, its `CanUseCashbackPercent` is `0`.
Without active cashback, all four cashback fields are `null`. For a nonpositive price, both percentage fields are `null`.
Percentages use percentage units: `20` means **20%**.
            
### Example
            
With no bonuses, one point per currency unit, cashback worth 0.01 per point, a 20% usage limit and no monetary cap:
            
**Request**
            
```json
[{"Id":"4571633770876","Price":2999.99}]
```
            
**Product estimate**
            
```json
{
  "Id": "4571633770876",
  "Points": 2999,
  "Cashback": 29,
  "CashbackPercent": 1,
  "CanUseCashback": true,
  "CanUseCashbackPercent": 20
}
```
            
For a price of 200, a 30% usage limit and a monetary cap of 40, `CanUseCashbackPercent` is **20%**.
            
### Cart restrictions
            
Minimum purchase requirements are ignored here and checked on the cart.
The monetary cap applies to the **whole order**: do not sum product estimates to authorize redemption.
Actual use also depends on the customer's balance and monetary rounding at redemption.

## Request body

- ProductPointRequest[]
  - `Id` string, required: Product Id on the ecommerce platform
  - `Price` number, required: Current product selling price
  - `PriceCurrency` string, nullable: Optional currency label (for example, BRL). It does not select a currency or perform conversion; the calculation uses Price as supplied.
  - `Name` string, nullable: Optional product name. It does not affect product lookup, earning rules or cashback restrictions.
  - `TradePolicyId` string, nullable: Optional trade policy (sales channel) identifier from the ecommerce platform, such as the VTEX `sc`. Earning rules restricted to this trade policy are included in the estimate. An unknown or empty value is ignored, so the estimate is the same as when the field is omitted.

## Response `200`

Product estimates in the same order as the request.

- ProductPointResponse[]
  - `Id` string: External product identifier, returned exactly as supplied in the request.
  - `Points` integer: Estimated earned points after applicable bonuses, limits and zero-point rules. This is a product estimate, not a guarantee of points granted for a completed order.
  - `Cashback` number, nullable: Estimated cashback earned from the simulated points, truncated to whole currency units. Null when cashback is unavailable; zero is a valid estimate and differs from null.
  - `CashbackPercent` number, nullable: The cashback percentage calculated from the final simulated points and product price, including bonuses and limits, rounded up to a whole percentage before monetary truncation. It will be null if cashback is unavailable or the product price is not positive.
  - `CanUseCashback` boolean, nullable: Whether cashback can be used on this product, considering product restrictions only, not the customer's balance. False for restricted products, true for eligible products (including unknown products or disabled restrictions), and null when cashback is inactive.
  - `CanUseCashbackPercent` number, nullable: Maximum percentage of this product's price payable with cashback, assuming sufficient balance. Includes product restrictions, the configured percentage limit and monetary cap, before redemption rounding. Null without active cashback or for a nonpositive price; zero for a restricted product.

## Changes

- **2026-10-28** `44ce3e962248`: 1 info
  - added the new optional request property `items/TradePolicyId`
- **2026-09-11** `ac8fd5749f8c`: 3 info
  - added the optional property `items/CanUseCashback` to the response with the `200` status
  - added the optional property `items/CanUseCashbackPercent` to the response with the `200` status
  - added the optional property `items/CashbackPercent` to the response with the `200` status

[Operation history](https://skmtc.dev/bonifiq/apis/bonifiq-public-apis/changes/v1/pub/Product/pointslist/post.md)

---

[API](https://skmtc.dev/bonifiq/apis/bonifiq-public-apis.md) - [All operations](https://skmtc.dev/bonifiq/apis/bonifiq-public-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/bonifiq/apis/bonifiq-public-apis/revisions/9de22a81f454?raw)