Loyalty API

CustomerBalance3

Returns detailed balance information Bubblehouse holds on the given customer. This includes information on loyalty point balance, tiers, achievements held and used, etc.

MethodGET or POST
KindRead-Only
URLhttps://app.bubblehouse.com/api/v2023061/<shop>/CustomerBalance3
AuthenticationCustomer 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_full_program=true when rendering full loyalty program pages

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

  • customerCustomerIdentity1required 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_rewardsbooleanoptional

    If true, the return value will include unused_rewards property.

  • include_full_programbooleanoptional

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

Output

Response format common to CustomerBalance3 and LoggedOutBalance1.

  • pts_availableintegerrequired

    Number of loyalty points available for spending.

  • pts_available_valuemonetaryoptional

    Monetary value of the loyalty points available for spending.

    Null if loyalty points are not directly convertible to monetary amounts for this shop.

  • pts_pendingintegerrequired

    Number of loyalty points earned by the customer but not yet available for spending.

  • pts_pending_valuemonetaryoptional

    Monetary value of the loyalty points earned by the customer but not yet available for spending.

    Null if loyalty points are not directly convertible to monetary amounts for this shop.

  • pts_earnedintegerrequired

    Total number of loyalty points the customer has earned over their entire history.

  • pts_redeemedintegerrequired

    Total number of loyalty points the customer has redeemed over their entire history.

  • pts_expiredintegerrequired

    Total number of loyalty points that have expired from the customer's account.

  • total_spendmonetaryrequired

    Total amount spent by the customer that counts toward loyalty.

  • upgrade_spendmonetaryrequired

    Amount spent by the customer that counts toward upgrade or renewal of a loyalty tier.

  • loyalty_anniversary_daydateoptional

    The date when the customer joined the loyalty program, used for anniversary rewards.

    This date represents when the customer first joined the loyalty program. It's used to calculate anniversaries for sending rewards, special offers, or congratulatory messages.

    If the customer hasn't formally joined the loyalty program or if anniversary tracking is disabled, this field will be empty or the day value will be zero.

  • pts_global_expirationtimeoptional

    A future moment in time when all customer points are going to expire, if any.

    Null if global points expiration is disabled for this shop.

  • pts_next_rolling_expirationCustomerRollingPointExpiration3optional

    Describes the next batch of points that will expire, including expiration time and amount.

    Null if rolling points expiration is disabled for this shop or if there are no points scheduled to expire.

  • redemptionRedemptionConfiguration2optional

    Monetary value of 1 loyalty point.

    Null if loyalty points are not directly convertible to monetary amounts for this shop.

  • cur_tierTierStatus3optional

    Customer's current tier.

    Null if the shop has no initial tier configured and the customer hasn't earned any tiers. Never null if the shop has an initial tier.

  • next_tierTierStatus3optional

    A tier one step higher than the customer's current tier.

  • subscription_statusCustomerSubscriptionStatus3required if milestones are enabled

    Information on the customer's subscription loyalty.

  • redemption_limitRedemptionLimitInfo1optional

    The effective redemption limit currently applied to this customer.

    Shows the actual limit that will be enforced when the customer attempts to redeem points. When both global and tier-specific limits exist, the tier limit takes precedence, completely overriding the global limit.

    Will be null if:

    • No redemption limits are configured
    • Points don't have monetary value (redemption is disabled)
    • The customer has unlimited redemptions

    The remaining field shows how many points the customer can still redeem in the current period before hitting the limit.

  • global_redemption_limitRedemptionLimitInfo1optional

    The global redemption limit configured for all customers.

    This is the default limit that applies to customers when their tier doesn't have a specific redemption limit configured. When a tier has its own redemption limit, that tier limit completely overrides this global limit.

    Will be null if no global redemption limit is configured.

  • unused_rewardsarray of AvailableReward1required if include_unused_rewards is enabled

    A list of rewards that the customer can use.

  • sourcesarray of Source2required if include_full_program is enabled

    A list of all point sources (aka Ways to Earn) enabled on this store and visible to this customer.

  • offersarray of Offer1required if include_full_program is enabled

    A list of all offers (i.e. vendibles and other redeemable offers) enabled on this store and visible to this customer.

  • tiersarray of TierStatus3required if include_full_program is enabled

    A list of all tiers enabled on this store and visible to this customer.

    Each tier in this array includes its configuration, features, and any redemption limits specific to that tier.

    Tier redemption limits are now embedded in each tier object as the redemption_limit field, replacing the previous separate tier_redemption_limits array.

  • milestonesarray of MilestoneStatus3required if include_full_program and milestones are enabled

    A list of all milestones enabled on this store and visible to this customer.

  • tier_featuresarray of TierFeature1required if include_full_program is enabled

    A list of all tier features defined for the shop.

    These are the feature definitions that apply across all tiers. Each tier in the tiers array includes its own features field with the specific values for that tier.

Specific Errors

StatusErrorReason & Examples

None.

API-wide Errors

StatusErrorReason & Examples
400missing_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.

{"id":"missing_customer_identity"}
404empty_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.

{"id":"empty_customer_identity"}
404no_customers_match_customer_identity

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

{"id":"no_customers_match_customer_identity"}
404customer_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.

{"id":"customer_identity_partially_mismatches_matched_customer"}
403customer_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.

{"id":"customer_identity_does_not_match_token"}

Global Errors

StatusErrorReason & Examples
401invalid_token

The provided authentication token is invalid or has expired.

{"id":"invalid_token","message":"The token has expired"}
429rate_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.

{"id":"rate_limit_exceeded","message":"You are over the read limit per second for this customer"}
400obsolete_global_api_version

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

{"id":"obsolete_global_api_version"}
400invalid_global_api_version

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

{"id":"invalid_global_api_version"}
400inaccessible_global_api_version

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

{"id":"inaccessible_global_api_version"}
Previous
Status2
Next
LoggedOutBalance1