Get Loyalty Balances

Get customer's loyalty balances

GET/v1/loyalty_programs/{loyaltyProgramId}/profile/{integrationId}/balances

Use it in a workflow

Add a step and choose the Talon.One connector.
Pick the Get Loyalty Balances action (under integration).
Fill in the fields below, then reference the result from later steps as {{getLoyaltyBalances.response.data}}.

Request

Path parameters

loyaltyProgramIdinteger (int64)required

Identifier of the profile-based loyalty program. You can get the ID with the [List loyalty programs](https://docs.talon.one/management-api#tag/Loyalty/operation/getLoyaltyPrograms) endpoint.

integrationIdstringrequired

The integration identifier for this customer profile. Must be: - Unique within the deployment. - Stable for the customer. Do not use an ID that the customer can update themselves. For example, you can use a database ID. Once set, you cannot update this identifier.

Query parameters

endDatestring (date-time)

Used to return expired, active, and pending loyalty balances before this timestamp. You can enter any past, present, or future timestamp value. > [!note] **Note** > - This must be an RFC3339 timestamp string. > - You can include a time component in your string, for example, `T23:59:59` to specify the end of the day. The time zone setting > considered is `UTC`. If you do not include a time component, a default time value of `T00:00:00` (midnight) in `UTC` is considered.

subledgerIdstring

The ID of the subledger by which we filter the data.

includeTiersboolean

Indicates whether tier information is included in the response. When set to `true`, the response includes information about the current tier and the number of points required to move to next tier.

Default false

includeProjectedTierboolean

Indicates whether the customer's projected tier information is included in the response. When set to `true`, the response includes information about the customer's active points and the name of the projected tier. **Note** We recommend filtering by `subledgerId` for better performance.

Default false

Response

Returns 200 with an object. Read it in later steps with {{getLoyaltyBalances.response.data.<field>}}.

balanceobject

Point balance of a ledger in the Loyalty Program.

activePointsnumber

Total amount of points awarded to this customer and available to spend.

pendingPointsnumber

Total amount of points awarded to this customer but not available until their start date.

spentPointsnumber

Total amount of points already spent by this customer.

expiredPointsnumber

Total amount of points awarded but never redeemed. They cannot be used anymore.

negativePointsnumber

Total amount of negative points. This implies that `activePoints` is `0`.

currentTierobject5 fields

projectedTierobject3 fields

pointsToNextTiernumber

The number of points required to move up a tier.

nextTierNamestring

The name of the next higher tier level in the loyalty program. **Note**: - Returns `null` if the customer has reached the highest available tier. - Returns the lowest level tier name if the customer is not currently assigned to any tier.

subledgerBalancesobject

Map of the loyalty balances of the subledgers of a ledger.

json

{
  "balance": {
    "projectedTier": {
      "projectedActivePoints": 198,
      "stayInTierPoints": 2,
      "projectedTierName": "Tier 1"
    },
    "negativePoints": 286,
    "activePoints": 286,
    "spentPoints": 150,
    "nextTierName": "Silver",
    "pointsToNextTier": 20,
    "expiredPoints": 286,
    "currentTier": {
      "expiryDate": {},
      "downgradePolicy": "one_down",
      "name": "bronze",
      "id": 11,
      "startDate": {}
    },
    "pendingPoints": 50
  },
  "subledgerBalances": {
    "mysubledger": {
      "activePoints": 286,
      "pendingPoints": 50,
      "spentPoints": 150,
      "expiredPoints": 25,
      "negativePoints": 0
    }
  }
}

Need more? See the Talon.One guide for connection setup and behaviour shared by every action.

Was this page helpful?