Loyalty API

Read Call

CustomerBalance3

One customer's loyalty status: available and pending points and their money value, lifetime earned, redeemed and expired points, current and next tier, expiring points, redemption limits. Optionally unused reward coupons, referral stats and the whole program: ways to earn, rewards, tiers, milestones.

Kind Read API call
Method GET or POST
URL https://app.bubblehouse.com/api/v2023061/<shop>/CustomerBalance3
Authentication Customer TokenShop Token
You have a choice of making this call from your server using a shop token and specifying a customer ID, or making this call from a web browser/app using a customer token you have generated on the server.

This endpoint provides comprehensive information about a customer's loyalty status, including points balance, tier status, and available rewards. It's the primary method for retrieving customer loyalty data for display in your application.

Use the optional parameters to control which data is included:

  • Omit include_unused_rewards for faster responses when rewards aren't needed
  • Only set include_referrals=true when you need the referral summary shown by the referral history UI
  • Set include_full_program=true when rendering program details or achievement progress from assets[].progress

Redemption Limits Structure

Redemption limits control how many points customers can redeem within specific time periods. The response includes:

  • redemption_limit - The effective limit currently applied to this customer
  • global_redemption_limit - The default limit for all customers
  • tiers[].redemption_limit - Tier-specific limits (only when include_full_program=true)

When a tier has its own redemption limit, it completely overrides the global limit for customers in that tier.

Input

  • customer CustomerIdentity1 required if using a shop token

    A customer to operate upon, when using a shop token.

    If you're using a customer token and decide to pass this field (which we do not recommend), it must match the customer from the token.

  • include_unused_rewards boolean optional

    If true, the return value will include unused_rewards property.

  • include_referrals boolean optional

    If true and referrals are enabled for this shop, the return value will include referral_stats populated with the same summary returned by CustomerReferrals2.

  • include_full_program boolean optional

    If true, the return value will include information for rendering an entire loyalty program: assets, sources, offers, tiers, milestones, voting and wallet_pass.

  • market MarketInput1 optional

    Optional market identity. When provided, all translatable strings are returned in the language configured for the matching market. When omitted, default copy is returned.

Output

See CustomerBalanceResult3.

API-wide Errors

Status Error Reason & Examples
404 empty_customer_identity

All fields of the customer identity ('customer' input parameter) have been empty when using a shop token. You need to either specify a non-empty value for one of the customer identity fields, or use a customer token.

404 customer_identity_partially_mismatches_matched_customer

A customer has been matched by one of the fields of the customer identity ('customer' input parameter), but some non-empty fields do not match Bubblehouse data on that customer.

400 missing_customer_identity

The customer identity ('customer' input parameter) has not been specified when using a shop token. You need to either specify a non-empty value for one of the customer identity fields, or use a customer token.

403 customer_identity_does_not_match_token

API call is using a customer token, but the customer identity in API params does not match the customer from the token.

404 no_customers_match_customer_identity

The customer identity ('customer' input parameter) does not match a known customer.

Global Errors

Status Error Reason & Examples
400 invalid_global_api_version

The global API version you are trying to use has never existed.

401 invalid_token

The provided authentication token is invalid or has expired.

For example: The token has expired

400 inaccessible_global_api_version

The global API version you are trying to use is not enabled on your account.

400 obsolete_global_api_version

The global API version you are trying to use is no longer supported.

429 rate_limit_exceeded

Your usage is over the rate limit. Ensure that you're not making duplicate calls, and contact our team for a rate limit increase.

For example: You are over the read limit per second for this customer

Previous
Cart2