Sign in

v5

latestOpenAPI 3.0.02026-08-04811,0021.1 MB
Customer

Add or remove cashback from a customer

This endpoint allows you to add or remove cashback to/from a customer balance. Internally it will convert the value into points and debit it from customer,..

Some important remarks

  • Use OperationType=0 if you want to add cashback. Use OperationType=1 if you want to remove cashback
  • If you want to add cashback, use a positive number (eg: 10).
  • If you want to remove cashback, use a negative number (eg: -10)

The ChangeKey field

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

How to use this field

Inform some string that is unique for this change. For instance: if you are adding R$10 for customerID=ABC regarding the OrderId=123 purchase he just made, our key could be ADD-ABC-10-123 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

The Reason field

This field is important to track why some cashback are given/taken from the customer. This information is internal-use only, it will not be visible to the customer.

post/v1/pvt/Customer/{id}/cashback

Path parameters

idstring required

Request body

Valuenumber

Value (in R$) that will be added or removed from customer`s cashback balance

OperationType0 | 1

Identify if the points are being given or taken \n0 - Adding Points 1 - Removing Points

0 = AddPoints 1 = RemovePoints

Reasonstring

Information regarding why these cashback are being add/removed. Internal information only. Required.

ChangeKeystring

This is a unique key for this add/remove cashback. If you try to use the same key more than once it will result in error

CustomerReasonstring nullable

Customer-facing reason displayed in the customer's points history. Optional, max 255 characters. HTML tags are stripped automatically. If null, empty, or whitespace, the default system message is shown.

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.