Add or remove points from a customer

curl --request POST \
  --url https://api.bonifiq.com.br/v1/pvt/Customer/{id}/points \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "Points": 123,
  "Reason": "<string>",
  "ChangeKey": "<string>",
  "CustomerReason": "<string>"
}
'

{
  "ErrorMessage": "<string>",
  "ErrorCode": 123,
  "Result": {
    "CustomerExists": true,
    "InternalId": "<string>",
    "PointsBalance": 123,
    "PointsToExpire": [
      {
        "Points": 123,
        "When": "2023-11-07T05:31:56Z"
      }
    ],
    "CashbackBalance": 123,
    "RedeemKey": "<string>",
    "PointHistory": [
      {
        "Id": 123,
        "IsCanceled": true,
        "DateReceived": "2023-11-07T05:31:56Z",
        "ExpirationDate": "2023-11-07T05:31:56Z",
        "Amount": 123,
        "CashbackAmount": 123,
        "BranchId": "<string>",
        "BranchName": "<string>",
        "OrderOriginDescription": "<string>",
        "PointType": 123,
        "PointTypeDescription": "<string>"
      }
    ],
    "Name": "<string>",
    "Error": "<string>"
  },
  "Code": "<string>",
  "CodeName": "<string>",
  "HasWarning": true,
  "HasError": true
}

Customer

Add or remove points from a customer

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.

POST

pvt

Customer

{id}

points

Add or remove points from a customer

curl --request POST \
  --url https://api.bonifiq.com.br/v1/pvt/Customer/{id}/points \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "Points": 123,
  "Reason": "<string>",
  "ChangeKey": "<string>",
  "CustomerReason": "<string>"
}
'

{
  "ErrorMessage": "<string>",
  "ErrorCode": 123,
  "Result": {
    "CustomerExists": true,
    "InternalId": "<string>",
    "PointsBalance": 123,
    "PointsToExpire": [
      {
        "Points": 123,
        "When": "2023-11-07T05:31:56Z"
      }
    ],
    "CashbackBalance": 123,
    "RedeemKey": "<string>",
    "PointHistory": [
      {
        "Id": 123,
        "IsCanceled": true,
        "DateReceived": "2023-11-07T05:31:56Z",
        "ExpirationDate": "2023-11-07T05:31:56Z",
        "Amount": 123,
        "CashbackAmount": 123,
        "BranchId": "<string>",
        "BranchName": "<string>",
        "OrderOriginDescription": "<string>",
        "PointType": 123,
        "PointTypeDescription": "<string>"
      }
    ],
    "Name": "<string>",
    "Error": "<string>"
  },
  "Code": "<string>",
  "CodeName": "<string>",
  "HasWarning": true,
  "HasError": true
}

Authorizations

Authorization

string

header

required

Use API Basic Auth Keys

Path Parameters

string

required

Body

application/json

Point changing information

Change Points from a customer. Either E-mail or CustomerId are required

Points

integer<int32>

Amount of points to add or remove from customer. If adding it must be positive. If removing it must be negative

OperationType

enum<integer>

Either is adding or removing points from customer

Available options:

0,

1

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 | null

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 - application/json

Standard response envelope used by the External API.

ErrorMessage

string | null

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<int32> | null

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

Result

object

Business payload returned by the endpoint.

Show child attributes

Code

string | null

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 | null

Symbolic enum name associated with Code, such as CheckoutNotFound.

Severity

enum<integer>

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.

Available options:

0,

1,

2

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.

Retrieve the amount of points of a given customer Retrieve pending purchase points and cashback for a given customer.