Balances

The Balances API returns the total reward, point, credit, and benefit balances a Profile can spend, together with the dollar value of their points and a per-region breakdown of everything they hold. See Localisation for how regions and currencies shape a balance.

Totals are scoped to the profile’s region

The totals (reward_balance, credit_balance, point_balance, point_balance_dollars, benefit_balance, combined_balance_dollars) are what the Profile can spend in their active region. They include:

Incentives issued by a Definition in the Profile’s region
Incentives issued by a Definition that names no region

Incentives issued by a Definition in another region are left out of the totals, because the Profile cannot redeem them there. A Profile with no active region, or a tenant whose Definitions name no region, sees every unexpired Incentive in the totals.

Response fields

Field	Description
`region`	The region the totals were calculated for: `id`, `name`, `handle`, and `currency`. `null` when the Profile has no active region. A region with no currency is still returned, with `currency: null`.
`regions`	The breakdown of everything the Profile holds, one entry per region in the tenant plus one entry for Incentives that name no region. Empty when the tenant has no regions.
`localised`	`reward_balance`, `point_balance_dollars`, and `combined_balance_dollars` converted to the currency in the `currency` query parameter. Only present when a matching exchange rate exists.
`currency`	The exchange rate used for `localised`. Only present when a matching exchange rate exists.

The `regions` breakdown

Every region in the tenant is listed, whether or not the Profile holds anything there, so you can render the same rows for every Profile. The final entry has region: null and holds the Incentives whose Definition names no region.

Field	Description
`region`	The region’s `id`, `name`, `handle`, and `currency`, or `null` for the entry holding Incentives with no region.
`currency`	The region’s currency, or `null` for the entry holding Incentives with no region.
`reward_balance`	Unexpired reward value issued in this region.
`credit_balance`	Unexpired credit value issued in this region.
`point_balance`	Unexpired points issued in this region.
`point_balance_value`	`point_balance` converted at the tenant’s point to currency rate, in this entry’s currency.
`benefit_balance`	Unexpired benefit value issued in this region.
`combined_balance_value`	`point_balance_value` plus the reward, credit, and benefit balances for this entry.

The entries do not add up to the totals. The totals equal the Profile’s own region entry plus the entry with no region. The sum of every entry is everything the Profile holds, including Incentives from other regions that they cannot spend where they are.

{
  "data": {
    "reward_balance": 20,
    "credit_balance": 0,
    "point_balance": 500,
    "point_balance_dollars": 5,
    "benefit_balance": 0,
    "combined_balance_dollars": 25,
    "region": { "id": 2, "name": "United Kingdom", "handle": "uk", "currency": "GBP" },
    "regions": [
      {
        "region": { "id": 1, "name": "Australia", "handle": "au", "currency": "AUD" },
        "currency": "AUD",
        "reward_balance": 30,
        "credit_balance": 0,
        "point_balance": 1000,
        "point_balance_value": 10,
        "benefit_balance": 0,
        "combined_balance_value": 40
      },
      {
        "region": { "id": 2, "name": "United Kingdom", "handle": "uk", "currency": "GBP" },
        "currency": "GBP",
        "reward_balance": 20,
        "credit_balance": 0,
        "point_balance": 500,
        "point_balance_value": 5,
        "benefit_balance": 0,
        "combined_balance_value": 25
      },
      {
        "region": null,
        "currency": null,
        "reward_balance": 0,
        "credit_balance": 0,
        "point_balance": 0,
        "point_balance_value": 0,
        "benefit_balance": 0,
        "combined_balance_value": 0
      }
    ]
  }
}

Currency conversion

The totals are in the currency of the Profile’s region. A Profile with no active region, or in a region with no currency, has totals in the tenant’s default currency. Passing the currency query parameter converts from that base currency to the requested one using the configured exchange rate for that pair. For example, ?currency=NZD for a Profile in a GBP region uses the GBP to NZD rate.

Localisation
Points
Rewards
Credits
Event contexts for the balance.updated payload

Overview

Authentication

Profiles

Commerce

Incentives

Lists

Groups

Ratings and Interactions

Reactions

Organisations and access

Configuration

Platform

Questionnaires

Totals are scoped to the profile’s region

Response fields

The `regions` breakdown

Currency conversion

​Totals are scoped to the profile’s region

​Response fields

​The regions breakdown

​Currency conversion

​Related

Totals are scoped to the profile’s region

Response fields

The `regions` breakdown

Currency conversion

Related