--- title: "Add or remove points from a customer" method: POST path: "/v1/pvt/Customer/{id}/points" tags: ["Customer"] --- # Add or remove points from a customer `POST /v1/pvt/Customer/{id}/points` ## Request - Base URL: `https://api.bonifiq.com.br` - URL: `https://api.bonifiq.com.br/v1/pvt/Customer/{id}/points` - Auth: HTTP basic This endpoint allows you to add or remove points to/from a customer. ## Some important remarks - Use `OperationType=0` if you want to add points. Use `OperationType=1` if you want to remove points - If you want to add points, use a `positive` number (eg: 10). - If you want to remove points, 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 points 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-point request thus adding or removing more point than intended ### How to use this field Inform some string that is unique for this change. For instance: if you are adding 10 point 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 point are given/taken from the customer. This information is internal-use only, it will not be visible to the customer. ## Path parameters - `id` string, required ## Request body - CustomerChangePointRequest: Change Points from a customer. Either E-mail or CustomerId are required - `Points` integer: Amount of points to add or remove from customer. If adding it must be positive. If removing it must be negative - `OperationType` 0 | 1: Identify if the points are being given or taken \n0 - Adding Points 1 - Removing Points 0 = AddPoints 1 = RemovePoints - `Reason` string: Information regarding why these points are being add/removed. Internal information only. Required. - `ChangeKey` string: This is a unique key for this add/remove point removal. If you try to use the same key more than once it will result in error - `CustomerReason` string, 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 `200` - BaseExternalApiResponseOfCustomerPointsWithErrorResponse: Standard response envelope used by the External API. - `ErrorMessage` string, 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. - `ErrorCode` integer, nullable: Legacy numeric error code derived from internal API errors when available. This field is relevant only for error flows that use `ApiResponseErrorDescription`. - `Result` CustomerPointsWithErrorResponse: Returns points customer have and an error if any - `CustomerExists` boolean: If True the customer was found on the Bonifiq DB - `InternalId` string: ID for this customer on the Bonifiq DB - `PointsBalance` integer: Amount of points for this customer. - `PointsToExpire` object[]: Points to expire, ordered by expiration date. A batch with no expiration date of its own gets an estimated date, which may not happen. - `Points` integer: Amount of Points - `Cashback` number, nullable: Cashback value represented by the expiring points - `When` string, date-time: Expiration Date of the points - `NextPointsToExpire` CustomerPointsToExpire: Customer Points to expire Model - `Points` integer: Amount of Points - `Cashback` number, nullable: Cashback value represented by the expiring points - `When` string, date-time: Expiration Date of the points - `CashbackBalance` number: When the cashback reward is active it returns the amount (in R$) of cashback the customer have Returns 0 when the cashback is inactive - `RedeemKey` string, nullable: Returns a key for this given point change - `PointHistory` object[]: A detailed list of point transactions for the customer. - `Id` integer: The unique identifier for the point transaction. - `IsCanceled` boolean: Indicates whether this history item was canceled. - `DateReceived` string, date-time: The date when the points were received or redeemed. - `ExpirationDate` string, date-time, nullable: The calculated expiration date for these points. - `Amount` integer: The amount of points in this transaction (positive for received, negative for redeemed). - `CashbackAmount` number, nullable: The amount of cashback associated with this transaction, if applicable. - `BranchId` string, nullable: The ID of the branch associated with the point transaction (if applicable, e.g., from an order). - `BranchName` string, nullable: The name of the branch associated with the point transaction (if applicable, e.g., from an order). - `OrderOrigin` 0 | 1 | 2 | 3 | 4: 0 = Integration 1 = API 2 = Import 3 = PDV 4 = OfflineIntegration - `OrderOriginDescription` string, nullable: Human-readable description for the order origin when the point comes from a purchase order. - `PointType` integer, nullable: The type of the point transaction (e.g., Purchase, Signup, Birthday, etc.). - `PointTypeDescription` string, nullable: Human-readable description of the point type. - `OrderValue` number, nullable - `OrderId` string, nullable - `PendingOrders` object[]: Most recent orders still waiting to receive purchase points, with the estimated points and cashback. The estimate may change until the points are granted. - `OrderId` string, nullable: Order id from the client's store. - `OrderDate` string, date-time: Order date informed by the integration. - `OrderValue` number: Order amount considered for point calculation. - `PendingPoints` integer: Estimated points to be granted for this order. - `PendingCashback` number, nullable: Estimated cashback equivalent for this order when cashback is active. Otherwise null. - `Name` string - `Error` string, nullable - `Code` string, 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. - `CodeName` string, nullable: Symbolic enum name associated with `Code`, such as `CheckoutNotFound`. - `Severity` 0 | 1 | 2: 0 = Success 1 = Warning 2 = Error - `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`. ## Changes - **2026-10-20** `7e56e33f7825`: 1 info - added the optional property `Result/oneOf[#/components/schemas/CustomerPointsWithErrorResponse]/allOf[#/components/schemas/CustomerPointsResponse]/NextPointsToExpire` to the response with the `200` status - **2026-10-06** `d30d10ada229`: 1 info - added the optional property `Result/oneOf[#/components/schemas/CustomerPointsWithErrorResponse]/allOf[#/components/schemas/CustomerPointsResponse]/PendingOrders` to the response with the `200` status - **2026-07-21** `760e443ffa9b`: 2 info - added the optional property `Result/oneOf[#/components/schemas/CustomerPointsWithErrorResponse]/allOf[#/components/schemas/CustomerPointsResponse]/PointHistory/items/oneOf[#/components/schemas/PointDetailItem]/OrderId` to the response with the `200` status - added the optional property `Result/oneOf[#/components/schemas/CustomerPointsWithErrorResponse]/allOf[#/components/schemas/CustomerPointsResponse]/PointHistory/items/oneOf[#/components/schemas/PointDetailItem]/OrderValue` to the response with the `200` status [Operation history](https://skmtc.dev/bonifiq/apis/bonifiq-private-apis/changes/v1/pvt/Customer/:id/points/post.md) --- [API](https://skmtc.dev/bonifiq/apis/bonifiq-private-apis.md) - [All operations](https://skmtc.dev/bonifiq/apis/bonifiq-private-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/bonifiq/apis/bonifiq-private-apis/revisions/bac0977b23d5?raw)