CustomerBalanceResult3

Response format common to CustomerBalance3 and LoggedOutBalance1.

Kind	Type
Used in	CustomerBalance3, LoggedOutBalance1

Properties

• pts_available integer required

  Number of loyalty points available for spending.

• pts_available_value monetary optional

  Monetary value of the loyalty points available for spending.

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

• pts_pending integer required

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

• pts_pending_value monetary optional

  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_earned integer required

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

• pts_redeemed integer required

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

• pts_expired integer required

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

• total_spend monetary required

  Total amount spent by the customer that counts toward loyalty.

• upgrade_spend monetary required

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

• loyalty_anniversary_day date optional

  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_expiration time optional

  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_expiration CustomerRollingPointExpiration3 optional

  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.

• redemption RedemptionConfiguration2 optional

  Monetary value of 1 loyalty point.

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

• cur_tier TierStatus3 optional

  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_tier TierStatus3 optional

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

• subscription_status CustomerSubscriptionStatus3 required if milestones are enabled

  Information on the customer's subscription loyalty.

• redemption_limit RedemptionLimitInfo1 optional

  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_limit RedemptionLimitInfo1 optional

  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_rewards array of AvailableReward1 required if include_unused_rewards is enabled

  A list of rewards that the customer can use.

• sources array of Source2 required 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.

• offers array of Offer1 required 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.

• tiers array of TierStatus3 required 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.

• milestones array of MilestoneStatus3 required if include_full_program and milestones are enabled

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

• tier_features array of TierFeature1 required 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.