Sign in

v4

OpenAPI 3.0.02026-07-31811,0021.1 MB
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/v1/pvt/POS/rewards/{id}/redeem

Path parameters

idinteger required

Request body

CustomerIdstring

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

Valuenumber nullable

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.

Pointsinteger nullable

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.

OriginalKeystring

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

RedeemOrigin0 | 1 | 2 | 3 | 4 | 5

0 = LandingPage 1 = Widget 2 = Copilot 3 = Checkout 4 = API 5 = PDV

ForceGenerateCouponboolean nullable

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

Response

ErrorMessagestring nullable

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

ErrorCodeinteger nullable

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

Codestring nullable

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.

CodeNamestring nullable

Symbolic enum name associated with Code, such as CheckoutNotFound.

Severity0 | 1 | 2

0 = Success 1 = Warning 2 = Error

HasWarningboolean

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.

HasErrorboolean

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.