> ## Documentation Index > Fetch the complete documentation index at: https://developers.bonifiq.com.br/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml https://api.bonifiq.com.br/swagger/Private%20APIs/swagger.json post /v1/pvt/Customer/{id}/cashback openapi: 3.0.0 info: title: BonifiQ Private APIs description: >- # Introduction This is the BonifiQ Private APIs documentation. With these endpoints you can interact with BonifiQ systems and enhance your program points. # Limitations These endpoints are intended to be used in backend communication so they are not CORS-compatible and cannot be used by in-browser frontend libraries (such as React, Angular, Vue, jQuery, etc) If are required to call BonifiQ API from a browser, please refer to our [Public APIs](https://api.bonifiq.com.br/apidocs/public) # Authentication These Private APis use the [Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) scheme. You need both an API Token (Username) and API Key (Password) to use with it You can generate this key pair in BonifiQ admin panel, at the "API Keys" menu. # How to use this page ## Making calls You can simulate, test and make calls to API from this Swagger page. To do that: - Click on the **Authorize** button - Inform the Username (API Token) and Passwoird (API Key) and click on **Authorize** - From the list bellow, choose an API call and click on **Try it out** - Inform the required parameters (if any) and click on **Execute** ## Verifying requests and responses bodies In every API Call there is an explanation of what each field means, theirs types and accepted values for all Requests and Responses. To view this information, just go to any API Call bellow and in the Responses section, click on the Schema. version: 1.0.0 servers: - url: https://api.bonifiq.com.br security: [] tags: - name: POS description: >- Flow methods to integrate BonifiQ with a POS system. Check the Flow Documentation link on the right externalDocs: description: Flow Documentation url: >- https://suporte.bonifiq.com.br/support/solutions/articles/159000319538-integrar-com-pdv - name: Checkout description: Operations related to checkout cashback redeem, refresh and removal - name: Customization description: Retrieve customizations for the loyalty program - name: Rewards description: Interact with rewards already redeemed paths: /v1/pvt/Customer/{id}/cashback: post: tags: - Customer summary: Add or remove cashback from a customer description: >- 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. operationId: Customer_ChangeCashback parameters: - name: id in: path required: true schema: type: string x-position: 1 requestBody: x-name: request description: Point changing information content: application/json: schema: $ref: '#/components/schemas/CustomerChangeCashbackRequest' required: true x-position: 2 responses: '200': description: '' content: application/json: schema: $ref: >- #/components/schemas/BaseExternalApiResponseOfCustomerPointsWithErrorResponse security: - Basic Authentication: [] components: schemas: CustomerChangeCashbackRequest: type: object description: Change Cashback balance from a Customer additionalProperties: false properties: Value: type: number description: >- Value (in R$) that will be added or removed from customer`s cashback balance format: decimal OperationType: description: Either is adding or removing cashback from customer oneOf: - $ref: '#/components/schemas/ChangePointOperation' Reason: type: string description: >- Information regarding why these cashback are being add/removed. Internal information only. Required. ChangeKey: type: string description: >- 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 CustomerReason: type: string description: >- 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. nullable: true BaseExternalApiResponseOfCustomerPointsWithErrorResponse: type: object description: Standard response envelope used by the External API. additionalProperties: false properties: ErrorMessage: type: string description: >- Error message returned when the request fails validation or processing. For warnings and successful responses, consumers should usually inspect `Result`, `Code` and `Severity` first. nullable: true ErrorCode: type: integer description: >- Legacy numeric error code derived from internal API errors when available. This field is relevant only for error flows that use `ApiResponseErrorDescription`. format: int32 nullable: true Result: description: Business payload returned by the endpoint. nullable: true oneOf: - $ref: '#/components/schemas/CustomerPointsWithErrorResponse' Code: type: string description: >- 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. nullable: true CodeName: type: string description: >- Symbolic enum name associated with `Code`, such as `CheckoutNotFound`. nullable: true Severity: description: >- 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. oneOf: - $ref: '#/components/schemas/ExternalApiResponseSeverity' HasWarning: type: boolean description: >- 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: type: boolean description: >- 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`. ChangePointOperation: type: integer description: |- Identify if the points are being given or taken \n0 - Adding Points 1 - Removing Points 0 = AddPoints 1 = RemovePoints x-enumNames: - AddPoints - RemovePoints enum: - 0 - 1 CustomerPointsWithErrorResponse: allOf: - $ref: '#/components/schemas/CustomerPointsResponse' - type: object description: Returns points customer have and an error if any additionalProperties: false properties: Error: type: string nullable: true ExternalApiResponseSeverity: type: integer description: |- 0 = Success 1 = Warning 2 = Error x-enumNames: - Success - Warning - Error enum: - 0 - 1 - 2 CustomerPointsResponse: type: object description: Customer Points Response Model additionalProperties: false properties: CustomerExists: type: boolean description: If True the customer was found on the Bonifiq DB InternalId: type: string description: ID for this customer on the Bonifiq DB PointsBalance: type: integer description: Amount of points for this customer. format: int32 PointsToExpire: type: array xml: wrapped: true items: xml: name: CustomerPointsToExpire oneOf: - $ref: '#/components/schemas/CustomerPointsToExpire' CashbackBalance: type: number description: >- When the cashback reward is active it returns the amount (in R$) of cashback the customer have Returns 0 when the cashback is inactive format: decimal RedeemKey: type: string description: Returns a key for this given point change nullable: true PointHistory: type: array description: A detailed list of point transactions for the customer. xml: wrapped: true items: xml: name: PointDetailItem oneOf: - $ref: '#/components/schemas/PointDetailItem' Name: type: string CustomerPointsToExpire: type: object description: Customer Points to expire Model additionalProperties: false properties: Points: type: integer description: Amount of Points format: int32 When: type: string description: Expiration Date of the points format: date-time PointDetailItem: type: object description: Represents a single point transaction detail. additionalProperties: false properties: Id: type: integer description: The unique identifier for the point transaction. format: int64 IsCanceled: type: boolean description: Indicates whether this history item was canceled. DateReceived: type: string description: The date when the points were received or redeemed. format: date-time ExpirationDate: type: string description: The calculated expiration date for these points. format: date-time nullable: true Amount: type: integer description: >- The amount of points in this transaction (positive for received, negative for redeemed). format: int32 CashbackAmount: type: number description: >- The amount of cashback associated with this transaction, if applicable. format: decimal nullable: true BranchId: type: string description: >- The ID of the branch associated with the point transaction (if applicable, e.g., from an order). nullable: true BranchName: type: string description: >- The name of the branch associated with the point transaction (if applicable, e.g., from an order). nullable: true OrderOrigin: description: >- The order origin associated with the point transaction when the point comes from a purchase order. nullable: true oneOf: - $ref: '#/components/schemas/OrderOrigin' OrderOriginDescription: type: string description: >- Human-readable description for the order origin when the point comes from a purchase order. nullable: true PointType: type: integer description: >- The type of the point transaction (e.g., Purchase, Signup, Birthday, etc.). format: int32 nullable: true PointTypeDescription: type: string description: Human-readable description of the point type. nullable: true OrderOrigin: type: integer description: |- 0 = Integration 1 = API 2 = Import 3 = PDV 4 = OfflineIntegration x-enumNames: - Integration - API - Import - PDV - OfflineIntegration enum: - 0 - 1 - 2 - 3 - 4 securitySchemes: Basic Authentication: type: http description: Use API Basic Auth Keys name: Basic Authentication in: header scheme: basic ````