ListCustomers2 - Bubblehouse API

Returns a list of customers and their loyalty program data.

Method	GET or POST
Kind	Read-Only
URL	`https://app.bubblehouse.com/api/v2023061/<shop>/ListCustomers2`
Authentication	Shop Token

The returned customer records are orders by latest_change_id if include_updates is true, otherwise .

This API returns a JSON response by default, but that JSON could be huge. We recommend that you pick JSONL format via the format parameter.

Input

formatTabularDataFormat1optional
The response format you want: JSON, JSONL or CSV.
livebooleanoptional
If true, live-streams updates instead of stopping when reaching the newest entry. Requires a streaming-friendly output format (JSONL or CSV).
include_updatesbooleanoptional
Returns customer updates. If false, only returns each customer record ones. Only makes sense when streaming.
cursorstringoptional
The cursor to start or continue streaming from a certain point.
limitintegeroptional
The 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

JSON output format: the response is a JSON array of objects, each object having the following format.

JSONL output format: the response is a text file with one JSON object per line, each object having the following format.

CSV: the response is a CSV file with the following columns. (Column names correspond exactly to the JSON property names.)

You MUST ignore extra/undocumented properties, unless instructed otherwise by customer support. We can and will introduce new properties without notice, we can and will return extra undocumented properties, we can and will change undocumented properties without notice.

idbubbleflakerequired
Unique ID of the customer in the Bubblehouse system
shopidstringrequired but can be empty
An online shop ID of the customer.
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, or simply ignore the corresponding records.
earliest_change_idbubbleflakerequired
The ID of the corresponding change when streaming or polling updates. Note that multiple consecutive changes can be coalesced into a single row, so we report a range.
latest_change_idbubbleflakerequired
The ID of the corresponding change when streaming or polling updates. Note that multiple consecutive changes can be coalesced into a single row, so we report a range.
emailstringrequired but can be empty
The email address of the customer.
phonestringrequired but can be empty
The phone number of the customer.
first_namestringrequired but can be empty
The first (given) name of the customer.
last_namestringrequired but can be empty
The last (family) name of the customer.
full_namestringrequired but can be empty
The 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_importedbooleanrequired
Whether this customer has been imported from a prior loyalty system.
is_testerbooleanrequired
Whether this customer is an internal tester account.
birthdaydateoptional
The customer's birthday. The year is zero if unknown.
signup_timetimeoptional
When the customer has signed up for an online shop account, if known.
pts_balanceintegerrequired
The number of loyalty points the customer currently has.
pts_spendable_balanceintegerrequired
The number of loyalty points the customer currently can spend (equal to the balance minus the amount of locked points).
pts_earnedintegerrequired
The number of loyalty points the customer has ever earned.
pts_redeemedintegerrequired
The number of loyalty points the customer has redeemed towards benefits.
tierstringrequired but can be empty
The name of the tier this customer is on, empty string if none.
referrer_bhidbubbleflakerequired but can be empty
A Bubblehouse ID of the customer that has referred this one.
referrer_shopidstringrequired but can be empty
An 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_emailstringrequired but can be empty
The email address of the customer that has referred this one, an empty string if unknown.
referrals_sentintegerrequired
The number of referrals this customer has sent.
referrals_approvedintegerrequired
The number of approved referrals this customer has sent.
referrals_declinedintegerrequired
The number of declined referrals this customer has sent.
In a standard configuration, no referrals get declined, but some shops have non-standard limits configured.
cycles_activeintegerrequired
The number of subscription cycles the customer is currently considered to be on.
cycles_everintegerrequired
The maximum number of subscription cycles the customer has ever reached.
votesintegerrequired
The number of votes the customer has recorded.
voting_pointsintegerrequired
The number of points the customer has earned for voting.
first_vote_timetimeoptional
When the customer has recorded their earliest vote.
last_vote_timetimeoptional
When the customer has recorded their latest vote.
reviews_textintegerrequired
The number of non-media reviews the customer has posted.
reviews_photointegerrequired
The number of photo reviews the customer has posted.
reviews_videointegerrequired
The number of video reviews the customer has posted.
sources_usedstringrequired but can be empty
A space-separated list of point source (“Ways to Earn Points”) slugs that the customer has used.
achievements_unlockedstringrequired but can be empty
A space-separated list of achievement slugs that the customer CURRENTLY has unlocked.
achievements_ever_unlockedstringrequired but can be empty
A space-separated list of achievement slugs that the customer has EVER unlocked.
achievements_ever_usedstringrequired but can be empty
A space-separated list of achievement slugs that the customer has EVER used the benefits of.
cursorstringoptional
A cursor to continue streaming or loading customers from this point.

Specific Errors

Status	Error	Reason & Examples
None.

API-wide Errors

Status	Error	Reason & Examples
None.

Global Errors

Status	Error	Reason & Examples
401	invalid_token	The provided authentication token is invalid or has expired. `{"id":"invalid_token","message":"The token has expired"}`
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. `{"id":"rate_limit_exceeded","message":"You are over the read limit per second for this customer"}`
400	obsolete_global_api_version	The global API version you are trying to use is no longer supported. `{"id":"obsolete_global_api_version"}`
400	invalid_global_api_version	The global API version you are trying to use has never existed. `{"id":"invalid_global_api_version"}`
400	inaccessible_global_api_version	The global API version you are trying to use is not enabled on your account. `{"id":"inaccessible_global_api_version"}`