curl --request POST \
--url https://api.bonifiq.com.br/v1/pvt/Checkout/redeem \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '
{
"CustomerId": "<string>",
"Customer": {
"Document": "<string>",
"Email": "<string>"
},
"CheckoutId": "<string>",
"CashbackValue": 123,
"Total": 123,
"Token": "<string>",
"OriginalKey": "<string>",
"Items": [
{
"ExternalProductId": "<string>",
"Value": 123,
"Quantity": 123
}
]
}
'import requests
url = "https://api.bonifiq.com.br/v1/pvt/Checkout/redeem"
payload = {
"CustomerId": "<string>",
"Customer": {
"Document": "<string>",
"Email": "<string>"
},
"CheckoutId": "<string>",
"CashbackValue": 123,
"Total": 123,
"Token": "<string>",
"OriginalKey": "<string>",
"Items": [
{
"ExternalProductId": "<string>",
"Value": 123,
"Quantity": 123
}
]
}
headers = {
"Authorization": "Basic <encoded-value>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
body: JSON.stringify({
CustomerId: '<string>',
Customer: {Document: '<string>', Email: '<string>'},
CheckoutId: '<string>',
CashbackValue: 123,
Total: 123,
Token: '<string>',
OriginalKey: '<string>',
Items: [{ExternalProductId: '<string>', Value: 123, Quantity: 123}]
})
};
fetch('https://api.bonifiq.com.br/v1/pvt/Checkout/redeem', 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/pvt/Checkout/redeem",
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([
'CustomerId' => '<string>',
'Customer' => [
'Document' => '<string>',
'Email' => '<string>'
],
'CheckoutId' => '<string>',
'CashbackValue' => 123,
'Total' => 123,
'Token' => '<string>',
'OriginalKey' => '<string>',
'Items' => [
[
'ExternalProductId' => '<string>',
'Value' => 123,
'Quantity' => 123
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Basic <encoded-value>",
"Content-Type: application/json"
],
]);
$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/pvt/Checkout/redeem"
payload := strings.NewReader("{\n \"CustomerId\": \"<string>\",\n \"Customer\": {\n \"Document\": \"<string>\",\n \"Email\": \"<string>\"\n },\n \"CheckoutId\": \"<string>\",\n \"CashbackValue\": 123,\n \"Total\": 123,\n \"Token\": \"<string>\",\n \"OriginalKey\": \"<string>\",\n \"Items\": [\n {\n \"ExternalProductId\": \"<string>\",\n \"Value\": 123,\n \"Quantity\": 123\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Basic <encoded-value>")
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/pvt/Checkout/redeem")
.header("Authorization", "Basic <encoded-value>")
.header("Content-Type", "application/json")
.body("{\n \"CustomerId\": \"<string>\",\n \"Customer\": {\n \"Document\": \"<string>\",\n \"Email\": \"<string>\"\n },\n \"CheckoutId\": \"<string>\",\n \"CashbackValue\": 123,\n \"Total\": 123,\n \"Token\": \"<string>\",\n \"OriginalKey\": \"<string>\",\n \"Items\": [\n {\n \"ExternalProductId\": \"<string>\",\n \"Value\": 123,\n \"Quantity\": 123\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.bonifiq.com.br/v1/pvt/Checkout/redeem")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"CustomerId\": \"<string>\",\n \"Customer\": {\n \"Document\": \"<string>\",\n \"Email\": \"<string>\"\n },\n \"CheckoutId\": \"<string>\",\n \"CashbackValue\": 123,\n \"Total\": 123,\n \"Token\": \"<string>\",\n \"OriginalKey\": \"<string>\",\n \"Items\": [\n {\n \"ExternalProductId\": \"<string>\",\n \"Value\": 123,\n \"Quantity\": 123\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"ErrorMessage": "<string>",
"ErrorCode": 123,
"Result": {
"RewardId": 123,
"Point": {
"PointId": 123,
"Quantity": 123,
"Metadatas": [
{
"Name": "<string>",
"Value": "<string>"
}
]
},
"ExternalCode": "<string>",
"OriginalKey": "<string>",
"Coupon": {
"CouponCode": "<string>",
"CouponType": 0,
"CouponValue": 123,
"ValidDateStart": "2023-11-07T05:31:56Z",
"ValidDateEnd": "2023-11-07T05:31:56Z"
}
},
"Code": "<string>",
"CodeName": "<string>",
"Severity": 0,
"HasWarning": true,
"HasError": true
}Redeems cashback for a checkout
This endpoint allows you to apply cashback discount to a checkout/cart.
Input Parameters
CustomerId(required): The customer identifier (email or document/CPF)CheckoutId(required): The checkout/cart ID from the e-commerce platformCashbackValue(optional): The specific amount of cashback to apply. If not provided, the maximum available cashback will be used.Total(optional): The checkout total value. Used for validation.OriginalKey(optional): A unique key to identify this redemption (for idempotency). For VTEX, omit it (recommended) or use exactlycheckout-{CheckoutId}with the actual cart ID; do not use an unrelated partner reference.
Response
On success, returns the reward information including:
RewardId: The unique ID for this rewardExternalCode: Code to be used when sending orders to BonifiQOriginalKey: The key identifying this redemptionPoint: Information about the points usedCoupon: The coupon information (if generated)
Important Notes
- VTEX automatic checkout discovery and cleanup depend on the cart identity in ExternalCode.
An unrelated OriginalKey, even one starting with
checkout-, is unsupported for these flows: redemption currently accepts it without format validation, but automatic refund may preserve the debit because the cart cannot be identified and its cleanup cannot be confirmed. The caller is responsible for the compatible key; this restriction does not add automatic repair for existing redemptions. - If the customer already has cashback applied in another checkout (without an order), it will be automatically refunded.
- The cashback value cannot exceed the checkout total or the customer’s available cashback balance.
- VTEX orphaned reward markers or unidentified manual discounts block application with HTTP 400,
existing code
09 / CashbackRedeemFailed, an explanatory message and no reward in Result (instead of a technical error). A known existing reward keeps10 / CashbackAlreadyApplied. No marker or manual price is automatically removed. 22 / CashbackApplicationUncertainreturns HTTP 400,HasError = trueandSeverity = Error: the reward/debit was persisted but remote application or rollback could not be confirmed.Resultidentifies that reward (RewardId,OriginalKey,Point) for reconciliation; it is NOT proof of applied cashback. Do not create another redeem with a new key or refund blindly. Verify checkout/order state using these identifiers. The existing checkout recovery is registered; absent identity or residual discount can still require manual analysis.
curl --request POST \
--url https://api.bonifiq.com.br/v1/pvt/Checkout/redeem \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '
{
"CustomerId": "<string>",
"Customer": {
"Document": "<string>",
"Email": "<string>"
},
"CheckoutId": "<string>",
"CashbackValue": 123,
"Total": 123,
"Token": "<string>",
"OriginalKey": "<string>",
"Items": [
{
"ExternalProductId": "<string>",
"Value": 123,
"Quantity": 123
}
]
}
'import requests
url = "https://api.bonifiq.com.br/v1/pvt/Checkout/redeem"
payload = {
"CustomerId": "<string>",
"Customer": {
"Document": "<string>",
"Email": "<string>"
},
"CheckoutId": "<string>",
"CashbackValue": 123,
"Total": 123,
"Token": "<string>",
"OriginalKey": "<string>",
"Items": [
{
"ExternalProductId": "<string>",
"Value": 123,
"Quantity": 123
}
]
}
headers = {
"Authorization": "Basic <encoded-value>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
body: JSON.stringify({
CustomerId: '<string>',
Customer: {Document: '<string>', Email: '<string>'},
CheckoutId: '<string>',
CashbackValue: 123,
Total: 123,
Token: '<string>',
OriginalKey: '<string>',
Items: [{ExternalProductId: '<string>', Value: 123, Quantity: 123}]
})
};
fetch('https://api.bonifiq.com.br/v1/pvt/Checkout/redeem', 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/pvt/Checkout/redeem",
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([
'CustomerId' => '<string>',
'Customer' => [
'Document' => '<string>',
'Email' => '<string>'
],
'CheckoutId' => '<string>',
'CashbackValue' => 123,
'Total' => 123,
'Token' => '<string>',
'OriginalKey' => '<string>',
'Items' => [
[
'ExternalProductId' => '<string>',
'Value' => 123,
'Quantity' => 123
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Basic <encoded-value>",
"Content-Type: application/json"
],
]);
$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/pvt/Checkout/redeem"
payload := strings.NewReader("{\n \"CustomerId\": \"<string>\",\n \"Customer\": {\n \"Document\": \"<string>\",\n \"Email\": \"<string>\"\n },\n \"CheckoutId\": \"<string>\",\n \"CashbackValue\": 123,\n \"Total\": 123,\n \"Token\": \"<string>\",\n \"OriginalKey\": \"<string>\",\n \"Items\": [\n {\n \"ExternalProductId\": \"<string>\",\n \"Value\": 123,\n \"Quantity\": 123\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Basic <encoded-value>")
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/pvt/Checkout/redeem")
.header("Authorization", "Basic <encoded-value>")
.header("Content-Type", "application/json")
.body("{\n \"CustomerId\": \"<string>\",\n \"Customer\": {\n \"Document\": \"<string>\",\n \"Email\": \"<string>\"\n },\n \"CheckoutId\": \"<string>\",\n \"CashbackValue\": 123,\n \"Total\": 123,\n \"Token\": \"<string>\",\n \"OriginalKey\": \"<string>\",\n \"Items\": [\n {\n \"ExternalProductId\": \"<string>\",\n \"Value\": 123,\n \"Quantity\": 123\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.bonifiq.com.br/v1/pvt/Checkout/redeem")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"CustomerId\": \"<string>\",\n \"Customer\": {\n \"Document\": \"<string>\",\n \"Email\": \"<string>\"\n },\n \"CheckoutId\": \"<string>\",\n \"CashbackValue\": 123,\n \"Total\": 123,\n \"Token\": \"<string>\",\n \"OriginalKey\": \"<string>\",\n \"Items\": [\n {\n \"ExternalProductId\": \"<string>\",\n \"Value\": 123,\n \"Quantity\": 123\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"ErrorMessage": "<string>",
"ErrorCode": 123,
"Result": {
"RewardId": 123,
"Point": {
"PointId": 123,
"Quantity": 123,
"Metadatas": [
{
"Name": "<string>",
"Value": "<string>"
}
]
},
"ExternalCode": "<string>",
"OriginalKey": "<string>",
"Coupon": {
"CouponCode": "<string>",
"CouponType": 0,
"CouponValue": 123,
"ValidDateStart": "2023-11-07T05:31:56Z",
"ValidDateEnd": "2023-11-07T05:31:56Z"
}
},
"Code": "<string>",
"CodeName": "<string>",
"Severity": 0,
"HasWarning": true,
"HasError": true
}Authorizations
Use API Basic Auth Keys
Body
The redeem request
Request to redeem cashback in a checkout
Customer identifier (email or document/CPF)
Optional customer identifiers. Customer.Document is required and used for lookup
when Checkout.CustomerOriginalIdSource is document; Customer.Email is required
and used for lookup when the setting is email.
Show child attributes
Show child attributes
The checkout/cart ID from the e-commerce platform
Optional: The specific amount of cashback to apply. If not provided, the maximum available cashback will be used.
Optional: The checkout total value. Used for validation.
Optional: Platform-specific token for the checkout
Optional: A unique key to identify this redemption (for idempotency). For VTEX, omit it (recommended) or use exactly checkout-{CheckoutId} with the actual cart ID. Unrelated partner references are unsupported for automatic checkout cleanup/refund, even if prefixed with checkout-. Currently accepted without format validation; an unresolvable cart can leave the redemption debit preserved.
Optional: List of order items for cashback eligibility validation. If provided, only eligible items will be considered for cashback calculation. If not provided, the full order total will be used (backward compatible behavior).
Show child attributes
Show child attributes
Response
The reward information
Standard response envelope used by the External API.
Error message returned when the request fails validation or processing.
For warnings and successful responses, consumers should usually inspect Result, Code and Severity first.
Legacy numeric error code derived from internal API errors when available.
This field is relevant only for error flows that use ApiResponseErrorDescription.
Business payload returned by the endpoint.
Show child attributes
Show child attributes
Endpoint-specific business code formatted as a two-digit string, such as 03 or 07.
This field is available for success, warning and error outcomes.
Symbolic enum name associated with Code, such as CheckoutNotFound.
Final severity of the response.
Success means the action completed as expected, Warning means the request was valid but the business outcome is informational or non-ideal, and Error means the request should be treated as a failure.
0, 1, 2 Convenience flag that is true when Severity is Warning.
Warnings are valid 200 OK business outcomes and should not be handled as transport or validation errors.
Indicates whether the request failed and should be handled as an error response.
This flag is reserved for real API errors; warnings must keep this property as false.
Was this page helpful?