Credit & debit points

Overview

Every credit or debit in the Loyalty API goes through a two-phase lifecycle:

1. Create — the transaction is recorded with status pending. The member’s balance is not yet updated.
2. Complete or Cancel — you explicitly confirm or void the operation.

This pattern mirrors real-world eCommerce flows: credit points only when a purchase is confirmed, not when it is merely placed — and cancel the credit if the order is cancelled or returned.

Step 1: Create transaction / balance order  →  status: PENDING   (balance unchanged)
Step 2a: Complete                           →  status: COMPLETED  (balance updated)
Step 2b: Cancel                             →  status: CANCELLED  (balance unchanged)

Create a transaction

Endpoint: POST https://api.brevo.com/v3/loyalty/balance/programs/{pid}/transactions

Use this for non-purchase events: sign-up bonuses, birthday credits, manual adjustments, referral rewards.

$
curl --request POST \
>
  --url https://api.brevo.com/v3/loyalty/balance/programs/27xxdd7a-.../transactions \
>
  --header 'api-key: YOUR_API_KEY' \
>
  --header 'content-type: application/json' \
>
  --data '{
>
    "contactId": 12345,
>
    "balanceDefinitionId": "a74cxx1d-4a96-4xx3-804e-dc3xxd9axxeb",
>
    "amount": 50,
>
    "autoComplete": false,
>
    "meta": {
>
      "reason": "signup_bonus"
>
    }
>
  }'

Request parameters

Response (200)

1
{
2
  "id": "txn_aaa111-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
3
  "amount": 50,
4
  "balanceDefinitionId": "a74cxx1d-4a96-4xx3-804e-dc3xxd9axxeb",
5
  "contactId": 12345,
6
  "loyaltyProgramId": "27xxdd7a-af67-0020-ba65-19d60000a26e",
7
  "status": "pending",
8
  "createdAt": "2025-03-01T10:00:00.000Z",
9
  "updatedAt": "2025-03-01T10:00:00.000Z",
10
  "cancelledAt": null,
11
  "completedAt": null,
12
  "rejectReason": null,
13
  "rejectedAt": null
14
}

Complete a transaction

Endpoint: POST https://api.brevo.com/v3/loyalty/balance/programs/{pid}/transactions/{tid}/complete

Completing a transaction finalizes the credit or debit: the member’s balance is updated, tiers are re-evaluated, and reward rules are checked.

$
curl --request POST \
>
  --url https://api.brevo.com/v3/loyalty/balance/programs/27xxdd7a-.../transactions/txn_aaa111-.../complete \
>
  --header 'api-key: YOUR_API_KEY'

Path parameters

Response (200)

1
{
2
  "id": "txn_aaa111-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
3
  "amount": 50,
4
  "balanceDefinitionId": "a74cxx1d-4a96-4xx3-804e-dc3xxd9axxeb",
5
  "contactId": 12345,
6
  "loyaltyProgramId": "27xxdd7a-af67-0020-ba65-19d60000a26e",
7
  "status": "completed",
8
  "completedAt": "2025-03-01T10:05:00.000Z",
9
  "cancelledAt": null,
10
  "rejectReason": null,
11
  "rejectedAt": null
12
}

What happens after completion:

• Member’s balance is updated (e.g. 0 → 50 pts)
• If tier trigger is real_time: tier thresholds are evaluated and the member may be upgraded
• Webhook balance_value_updated is fired
• If a tier threshold is crossed: webhook tier_association_updated is fired
• If a reward rule matches: a voucher is attributed

When to call Complete:

Cancel a transaction

Endpoint: POST https://api.brevo.com/v3/loyalty/balance/programs/{pid}/transactions/{tid}/cancel

Cancelling a transaction voids it entirely. The member’s balance is not affected.

$
curl --request POST \
>
  --url https://api.brevo.com/v3/loyalty/balance/programs/27xxdd7a-.../transactions/txn_aaa111-.../cancel \
>
  --header 'api-key: YOUR_API_KEY'

Response (200)

1
{
2
  "id": "txn_aaa111-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
3
  "amount": 50,
4
  "status": "cancelled",
5
  "cancelledAt": "2025-03-01T10:05:00.000Z",
6
  "completedAt": null,
7
  "rejectReason": null
8
}

When to call Cancel:

Handling returns after delivery (balance already completed):

A completed transaction cannot be cancelled. Instead, create a new transaction with a negative amount (debit) and complete it.

$
# Step 1: create debit for returned order
$
--data '{
>
  "contactId": 12345,
>
  "balanceDefinitionId": "...",
>
  "amount": -100,
>
  "meta": { "reason": "return_order_789" }
>
}'
$
$
# Step 2: complete the debit
$
POST .../transactions/{debit_tid}/complete

Create a balance order

Endpoint: POST https://api.brevo.com/v3/loyalty/balance/programs/{pid}/create-order

A balance order is the right tool for crediting points on a purchase. It creates a single tracked event tied to a business order, which you later complete or cancel as one unit.

$
curl --request POST \
>
  --url https://api.brevo.com/v3/loyalty/balance/programs/27xxdd7a-.../create-order \
>
  --header 'api-key: YOUR_API_KEY' \
>
  --header 'content-type: application/json' \
>
  --data '{
>
    "contactId": 12345,
>
    "balanceDefinitionId": "a74cxx1d-4a96-4xx3-804e-dc3xxd9axxeb",
>
    "amount": 100,
>
    "source": "user",
>
    "dueAt": "2025-03-02T10:00:00.000Z",
>
    "meta": {
>
      "orderId": "order_789",
>
      "orderAmount": 89.99
>
    }
>
  }'

Request parameters

Response (200)

1
{
2
  "id": "ord_xyz789-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
3
  "transactionid": "txn_bbb222-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
4
  "contactId": 12345,
5
  "loyaltyProgramId": "27xxdd7a-af67-0020-ba65-19d60000a26e",
6
  "balanceDefinitionId": "a74cxx1d-4a96-4xx3-804e-dc3xxd9axxeb",
7
  "amount": 100,
8
  "source": "user",
9
  "dueAt": "2025-03-02T10:00:00.000Z",
10
  "processedAt": null,
11
  "createdAt": "2025-03-01T10:00:00.000Z",
12
  "updatedAt": "2025-03-01T10:00:00.000Z"
13
}

The order returns a transactionid. Use this to call /complete or /cancel when the purchase status is resolved.

Which endpoint to use?

Error handling