--- 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` 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` 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 - `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`. --- [API](https://skmtc.net/bonifiq/apis/bonifiq-private-apis.md) · [All operations](https://skmtc.net/bonifiq/apis/bonifiq-private-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/bonifiq/bonifiq-private-apis/revisions/070a57eeffdc/schema)