This method can be used to redeem a reward in behalf of a customer.

curl --request POST \
  --url https://api.bonifiq.com.br/v1/pvt/POS/rewards/{id}/redeem \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "CustomerId": "<string>",
  "Value": 123,
  "Points": 123,
  "OriginalKey": "<string>",
  "Metadatas": [
    {
      "Name": "<string>",
      "Value": "<string>"
    }
  ],
  "Branch": {
    "OriginalId": "<string>",
    "Name": "<string>"
  },
  "SalesPerson": {
    "OriginalId": "<string>",
    "Name": "<string>"
  },
  "ForceGenerateCoupon": true
}
'

{
  "ErrorMessage": "<string>",
  "ErrorCode": 123,
  "Result": {
    "RewardId": 123,
    "Point": {
      "PointId": 123,
      "Quantity": 123,
      "Metadatas": [
        {
          "Name": "<string>",
          "Value": "<string>"
        }
      ]
    },
    "ExternalCode": "<string>",
    "OriginalKey": "<string>",
    "Coupon": {
      "CouponCode": "<string>",
      "CouponValue": 123,
      "ValidDateStart": "2023-11-07T05:31:56Z",
      "ValidDateEnd": "2023-11-07T05:31:56Z"
    }
  },
  "Code": "<string>",
  "CodeName": "<string>",
  "HasWarning": true,
  "HasError": true
}

POS

This method can be used to redeem a reward in behalf of a customer.

There are 2 types of rewards:

Discount Rewards: Percent (10%) or Value (R$10,00). This rewards are simples as they use pre-configured values
Cashback: As a value (R$5,00). The used value must be informed in the Value field of the request body

They both can be used with this method. Just be aware that:

The field Value must have the selected cashback value for the purchase. Use only if the reward is Cashback type
For other rewards this field can be null

The rewardId field can be obtained by calling the rewards/available endpoint

The customerId field in the body is the same used in the rewards/avaible endpoint.

The `OriginalKey` field

This field allows you to create idempotency: even if you make the exactly same request twice it will redeem only once. As distributed systems should be fault-tolerant it may result in requests being done more than one time. Not using the OriginalKey may duplicate a redeem request

How to use this field

Inform some string that is unique for this change.

For instance: if you are redeeming the reward Id=OPQ for customerID=ABC regarding the OrderId=123 with Value=10,our key could be OPQ-ABC-123-10

If you dont need this kind of verification you can just use some time-related string, such as 2023-01-01 23:59:00:000

Coupon Generation

It’s important to note that unlike the customers/{id}/redeem endpoint this call will not generate a coupon in BonifiQ. That is true even if the reward if configured so.

This is by design as in Point of Sale endpoints it is expected that the caller (PoS) will give the customer the necessary discounts.

The `ExternalCode` return

One of the most important fields returned by this method is the ExternalCode. This field represents an External identification for this redeem. This exact value must be passed on the Coupon field for the Order Add Method from this API. This will make a link between the redeem and the order.

Important: Remember to pass the ExternalCode value to the Coupon field when adding an order

POST

pvt

POS

rewards

{id}

redeem

This method can be used to redeem a reward in behalf of a customer.

curl --request POST \
  --url https://api.bonifiq.com.br/v1/pvt/POS/rewards/{id}/redeem \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "CustomerId": "<string>",
  "Value": 123,
  "Points": 123,
  "OriginalKey": "<string>",
  "Metadatas": [
    {
      "Name": "<string>",
      "Value": "<string>"
    }
  ],
  "Branch": {
    "OriginalId": "<string>",
    "Name": "<string>"
  },
  "SalesPerson": {
    "OriginalId": "<string>",
    "Name": "<string>"
  },
  "ForceGenerateCoupon": true
}
'

{
  "ErrorMessage": "<string>",
  "ErrorCode": 123,
  "Result": {
    "RewardId": 123,
    "Point": {
      "PointId": 123,
      "Quantity": 123,
      "Metadatas": [
        {
          "Name": "<string>",
          "Value": "<string>"
        }
      ]
    },
    "ExternalCode": "<string>",
    "OriginalKey": "<string>",
    "Coupon": {
      "CouponCode": "<string>",
      "CouponValue": 123,
      "ValidDateStart": "2023-11-07T05:31:56Z",
      "ValidDateEnd": "2023-11-07T05:31:56Z"
    }
  },
  "Code": "<string>",
  "CodeName": "<string>",
  "HasWarning": true,
  "HasError": true
}

Authorizations

Authorization

string

header

required

Use API Basic Auth Keys

Path Parameters

integer<int32>

required

Body

application/json

Parameters used in redeeming

CustomerId

string

The id of the customer. It can be email or document (CPF/CNPJ).

Value

number<decimal> | null

Used only for Cashback Rewards. It the Cashback value selected by the customer. You can use either Points or Value for representing the selected amount of cashback to use.

Points

integer<int32> | null

Used only for Cashback Rewards. It the Cashback represented by points selected by the customer. You can use either Points or Value for representing the selected amount of cashback to use.

OriginalKey

string

This field allows you to create idempotency: even if you make the exactly same request twice it will consume the redeem only once. As distributed systems should be fault-tolerant it may result in requests being done more than one time. Not using the OriginalKey may duplicate a redeem request Inform some string that is unique for this change. For instance: if you are redeeming the reward Id=OPQ for customerID=ABC regarding the OrderId=123 with Value=10,our key could be OPQ-ABC-123-10 If you dont need this kind of verification you can just use some time-related string, such as 2023-01-01 23:59:00:000

Metadatas

object[] | null

Use this field as a key-value store for fields unique to your Business Use Case

Show child attributes

RedeemOrigin

enum<integer>

Use this field to send redeem origin. Have 4 types: LandingPage, Widget, Copilot, Checkout, API, PDV.

Available options:

0,

1,

2,

3,

4,

5

Branch

object

A Branch is physical location or outlet of a store (loja, filial, etc). This is used to receive information of which store the purchase was made. It can be later used to create rules for points or filtering reports.

Show child attributes

SalesPerson

object

A sales person is the person responsible for the sale. It can be used for filtering reports.

Show child attributes

ForceGenerateCoupon

boolean | null

Normally this endpoint generates a redeem without a coupon. Setting this property to true forces to generate a coupon in the ecommerce plataform

Response

200 - application/json

Standard response envelope used by the External API.

ErrorMessage

string | null

Error message returned when the request fails validation or processing. For warnings and successful responses, consumers should usually inspect Result, Code and Severity first.

ErrorCode

integer<int32> | null

Legacy numeric error code derived from internal API errors when available. This field is relevant only for error flows that use ApiResponseErrorDescription.

Result

object

Business payload returned by the endpoint.

Show child attributes

Code

string | null

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.

CodeName

string | null

Symbolic enum name associated with Code, such as CheckoutNotFound.

Severity

enum<integer>

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.

Available options:

0,

1,

2

HasWarning

boolean

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.

HasError

boolean

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.

Returns a list of available rewards for a given customer and purchase.Cancel an existing reward using the OriginalKey