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

curl --request POST \
  --url https://api.bonifiq.com.br/v1/pub/Product/pointslist \
  --header 'Content-Type: application/json' \
  --header 'X-BQ-ApiToken: <api-key>' \
  --data '
[
  {
    "Id": "SKU-001",
    "Price": 499.99,
    "PriceCurrency": "BRL",
    "Name": "Running shoes"
  }
]
'

import requests

url = "https://api.bonifiq.com.br/v1/pub/Product/pointslist"

payload = [
    {
        "Id": "SKU-001",
        "Price": 499.99,
        "PriceCurrency": "BRL",
        "Name": "Running shoes"
    }
]
headers = {
    "X-BQ-ApiToken": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-BQ-ApiToken': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify([{Id: 'SKU-001', Price: 499.99, PriceCurrency: 'BRL', Name: 'Running shoes'}])
};

fetch('https://api.bonifiq.com.br/v1/pub/Product/pointslist', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.bonifiq.com.br/v1/pub/Product/pointslist",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    [
        'Id' => 'SKU-001',
        'Price' => 499.99,
        'PriceCurrency' => 'BRL',
        'Name' => 'Running shoes'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-BQ-ApiToken: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.bonifiq.com.br/v1/pub/Product/pointslist"

	payload := strings.NewReader("[\n  {\n    \"Id\": \"SKU-001\",\n    \"Price\": 499.99,\n    \"PriceCurrency\": \"BRL\",\n    \"Name\": \"Running shoes\"\n  }\n]")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-BQ-ApiToken", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.bonifiq.com.br/v1/pub/Product/pointslist")
  .header("X-BQ-ApiToken", "<api-key>")
  .header("Content-Type", "application/json")
  .body("[\n  {\n    \"Id\": \"SKU-001\",\n    \"Price\": 499.99,\n    \"PriceCurrency\": \"BRL\",\n    \"Name\": \"Running shoes\"\n  }\n]")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.bonifiq.com.br/v1/pub/Product/pointslist")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-BQ-ApiToken"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "[\n  {\n    \"Id\": \"SKU-001\",\n    \"Price\": 499.99,\n    \"PriceCurrency\": \"BRL\",\n    \"Name\": \"Running shoes\"\n  }\n]"

response = http.request(request)
puts response.read_body

[
  {
    "Id": "SKU-001",
    "Points": 499,
    "Cashback": 4,
    "CashbackPercent": 1,
    "CanUseCashback": true,
    "CanUseCashbackPercent": 20
  }
]

Product

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

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

[{"Id":"4571633770876","Price":2999.99}]

Product estimate

{
  "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.

POST

pub

Product

pointslist

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

curl --request POST \
  --url https://api.bonifiq.com.br/v1/pub/Product/pointslist \
  --header 'Content-Type: application/json' \
  --header 'X-BQ-ApiToken: <api-key>' \
  --data '
[
  {
    "Id": "SKU-001",
    "Price": 499.99,
    "PriceCurrency": "BRL",
    "Name": "Running shoes"
  }
]
'

import requests

url = "https://api.bonifiq.com.br/v1/pub/Product/pointslist"

payload = [
    {
        "Id": "SKU-001",
        "Price": 499.99,
        "PriceCurrency": "BRL",
        "Name": "Running shoes"
    }
]
headers = {
    "X-BQ-ApiToken": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-BQ-ApiToken': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify([{Id: 'SKU-001', Price: 499.99, PriceCurrency: 'BRL', Name: 'Running shoes'}])
};

fetch('https://api.bonifiq.com.br/v1/pub/Product/pointslist', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.bonifiq.com.br/v1/pub/Product/pointslist",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    [
        'Id' => 'SKU-001',
        'Price' => 499.99,
        'PriceCurrency' => 'BRL',
        'Name' => 'Running shoes'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-BQ-ApiToken: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.bonifiq.com.br/v1/pub/Product/pointslist"

	payload := strings.NewReader("[\n  {\n    \"Id\": \"SKU-001\",\n    \"Price\": 499.99,\n    \"PriceCurrency\": \"BRL\",\n    \"Name\": \"Running shoes\"\n  }\n]")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-BQ-ApiToken", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.bonifiq.com.br/v1/pub/Product/pointslist")
  .header("X-BQ-ApiToken", "<api-key>")
  .header("Content-Type", "application/json")
  .body("[\n  {\n    \"Id\": \"SKU-001\",\n    \"Price\": 499.99,\n    \"PriceCurrency\": \"BRL\",\n    \"Name\": \"Running shoes\"\n  }\n]")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.bonifiq.com.br/v1/pub/Product/pointslist")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-BQ-ApiToken"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "[\n  {\n    \"Id\": \"SKU-001\",\n    \"Price\": 499.99,\n    \"PriceCurrency\": \"BRL\",\n    \"Name\": \"Running shoes\"\n  }\n]"

response = http.request(request)
puts response.read_body

[
  {
    "Id": "SKU-001",
    "Points": 499,
    "Cashback": 4,
    "CashbackPercent": 1,
    "CanUseCashback": true,
    "CanUseCashbackPercent": 20
  }
]

Authorizations

X-BQ-ApiToken

string

header

required

API Tokeen

Body

application/json

Array of products with external Id and Price; Name and PriceCurrency are optional.

string

required

Product Id on the ecommerce platform

Minimum string length: 1

Example:

"SKU-001"

Price

number<decimal>

required

Current product selling price

Example:

499.99

PriceCurrency

string | null

Optional currency label (for example, BRL). It does not select a currency or perform conversion; the calculation uses Price as supplied.

Example:

"BRL"

Name

string | null

Optional product name. It does not affect product lookup, earning rules or cashback restrictions.

Example:

"Running shoes"

Response

200 - application/json

Product estimates in the same order as the request.

string

External product identifier, returned exactly as supplied in the request.

Example:

"SKU-001"

Points

integer<int32>

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.

Example:

499

Cashback

number<decimal> | null

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.

Example:

4

CashbackPercent

number<decimal> | null

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.

Example:

1

CanUseCashback

boolean | null

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.

Example:

true

CanUseCashbackPercent

number<decimal> | null

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.

Example:

20