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

curl --request POST \
  --url https://api.bonifiq.com.br/v1/pub/Product/points \
  --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/points"

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/points', 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/points",
  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/points"

	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/points")
  .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/points")

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

{
  "HasError": true,
  "ErrorMessages": [
    "<string>"
  ],
  "ErrorMessage": "<string>",
  "ErrorDescriptions": [
    {
      "Description": 0,
      "Field": "<string>",
      "FieldText": "<string>"
    }
  ],
  "Result": [
    {
      "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

points

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

curl --request POST \
  --url https://api.bonifiq.com.br/v1/pub/Product/points \
  --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/points"

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/points', 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/points",
  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/points"

	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/points")
  .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/points")

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

{
  "HasError": true,
  "ErrorMessages": [
    "<string>"
  ],
  "ErrorMessage": "<string>",
  "ErrorDescriptions": [
    {
      "Description": 0,
      "Field": "<string>",
      "FieldText": "<string>"
    }
  ],
  "Result": [
    {
      "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.

HasError

boolean

ErrorMessages

string[]

ErrorMessage

string

ErrorDescriptions

object[]

Show child attributes

Result

object[] | null

Show child attributes