Analytics API
Read CallListCustomers3
Bulk export of all customers: email, phone, name, birthday, loyalty opt-in, points balance and lifetime totals, tier, referrer and referral counts. For member lists, reports and data sync.
| Kind | Read API call |
|---|---|
| Method | GET or POST |
| URL | https://app.bubblehouse.com/api/v2023061/<shop>/ListCustomers3 |
| Authentication | Shop Token |
Bubblehouse export APIs use a global incrementing version number that sweeps across all export data formats; see the Version History for the changelog. Older versions remain supported indefinitely but are not listed in the documentation.
Note that the output is in a tabular data format determined by the format parameter.
The response streams in batches, and each batch reads current data, so a long export is not one snapshot. A customer changed during the export can show values from before or after the change; customers added during the export appear at the end. Rows stay in Bubblehouse ID order, and unchanged customers appear exactly once. If the export is interrupted (for example by a server restart), the connection closes without completing the response; treat that as a failed export and rerun it.
Input
-
fieldsstring optionalWhich customer fields to include in the response.
Use a comma-separated filter string such as
default,ids,email,phone, orall.Supported values are field names from Customer2,
balance, and the built-in aspectsids,default, andall.balanceadds the customer's loyalty balance (see thebalanceoutput field).defaultleaves it out;allincludes it. Pick subfields withbalance(pts_pending,cur_tier).balancealone meansbalance(default): every subfield exceptreferral_stats. Add it withbalance(default,referral_stats)orbalance(all); it reads each customer's referral history, so large exports get noticeably slower.In CSV,
balanceobjects are flattened into one column per value, such asbalance_pts_pending,balance_cur_tier_nameandbalance_cur_tier_reqs_extra_spend.balance(cur_tier)selects allcur_tiercolumns;balance_cur_tier_nameorbalance(cur_tier_name)selects one. -
The response format you want: JSON, JSONL, CSV, or Excel CSV.
csvis the raw file.excel-csvuses the same columns andtext/csvbody. Numbers stay numbers, including negatives. Text that starts with=,+,-,@, tab, or CR gets a leading apostrophe. -
limitinteger optionalThe number of objects to return.
The default limit is 1000 (unless you're streaming), but feel free to use any number here. You can set the limit to -1 or a very large number to disable it; Bubblehouse will be happy to stream the entire list of customers. If you picked the JSON output format, be careful when processing a potentially huge response this generates.
Output
-
Unique ID of the customer in the Bubblehouse system.
-
custom_idstring optionalCustom external ID of the customer (for fully custom integrations).
For shops that use a fully custom integration, Bubblehouse can store an additional customer identifier defined by your system. When configured, it is exposed here as
custom_id. -
shopify_idstring optionalShopify customer ID (for shops that run on Shopify).
For shops that use Shopify as their ecommerce platform, Bubblehouse exposes the Shopify customer ID as
shopify_id. Other integrations will expose similar fields named<integration>_id. -
emailstring required but can be emptyThe email address of the customer.
-
phonestring required but can be emptyThe phone number of the customer.
-
first_namestring required but can be emptyThe first (given) name of the customer.
-
last_namestring required but can be emptyThe last (family) name of the customer.
-
full_namestring required but can be emptyThe full name of the customer.
The full name is filled in when we don't know the first/last name split, e.g. for online shops that do not have separate first/last name fields, or when sourcing customer data from a review system or another integration that only has a full name field.
-
is_importedboolean requiredWhether this customer has been imported from a prior loyalty system.
-
is_testerboolean requiredWhether this customer is an internal tester account.
-
The customer's birthday. The year is zero if unknown.
-
When the customer has signed up for an online shop account, if known.
-
When the customer's loyalty opt-in status last changed, whether opting in or opting out.
-
optin_originstring optionalThe source of the customer's last loyalty opt-in status change.
-
pts_balanceinteger requiredThe number of loyalty points the customer currently has.
-
pts_earnedinteger requiredThe number of loyalty points the customer has ever earned.
-
pts_redeemedinteger requiredThe number of loyalty points the customer has redeemed towards benefits.
-
pts_expiredinteger requiredThe number of loyalty points that have expired for this customer.
-
tierstring required but can be emptyThe name of the tier this customer is on, empty string if none.
-
When the customer entered their current tier, in the shop timezone.
-
is_referredboolean requiredWhether this customer has been referred by another customer.
-
referrer_shop_idstring required but can be emptyAn online shop ID of the customer that has referred this one.
Note that in some edge cases involving imports and integrations, the customer in Bubblehouse database might not have an associated account in the online shop, so this field might be empty. You can fall back to a Bubblehouse ID when identifying these customers.
-
referrer_emailstring required but can be emptyThe email address of the customer that has referred this one, an empty string if unknown.
-
referrals_sentinteger requiredThe number of referrals this customer has sent.
-
referrals_approvedinteger requiredThe number of approved referrals this customer has sent.
-
referrals_declinedinteger requiredThe number of referrals this customer has sent that have been ignored/declined/expired.
-
votesinteger requiredThe number of votes the customer has recorded.
-
reviewsinteger requiredThe total number of reviews (of any type) the customer has posted.
-
The customer's loyalty balance, with the same field names and values that CustomerBalance3 returns for this customer.
Present only when requested; see
fields. Values match a CustomerBalance3 call for the customer withoutmarket, withinclude_referralswhenreferral_statsis selected. Fields that CustomerBalance3 omits are omitted here; fields it returns asnullarenull.Subfields:
member,membership,program_enabled,pts_available,pts_available_value,pts_pending,pts_pending_value,total_spend,upgrade_spend,pts_earned,pts_redeemed,pts_expired,loyalty_anniversary_day,pts_next_rolling_expiration,spend_chunk,cur_tier,next_tier,subscription_status,redemption_limit,global_redemption_limit,referral_stats.Not included: program-wide data (
redemption,tiers,milestones,tier_features,offers,sources,assets,special_dates,voting,wallet_pass),unused_rewardsandpts_global_expiration. The customer's current and next milestones are insubscription_status.cur_tier.expirationmatches CustomerBalance3 and can differ fromtier_expiration, which accounts for tier renewal progress.CSV has one
balance_...column per value, named by joining the JSON path with underscores. A cell holds the JSON value: numbers and amounts as numbers (amounts with 6 decimals), text without quotes,true/false, days asYYYY-MM-DD, times as in JSON, lists such asslugsjoined with|. Missing objects andnullvalues give empty cells. CSV leaves out values CustomerBalance3 never fills:reqs.threshold_event,reqs.extra_event,reqs.extra_desc,reqs.progress, tierfeaturesandredemption_limit,expiration.downgraded_tier_name,expiration.keep_reqs,expiration.keep_extended_deadline,next_tier.start_time,next_tier.start_day,next_tier.expiration, andusedin redemption limits.
Global Errors
| Status | Error | Reason & Examples |
|---|---|---|
| 401 | invalid_token |
The provided authentication token is invalid or has expired. For example: |
| 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: |