ListCustomers2

Returns a list of customers and their loyalty program data.

This call is deprecated. We strive to avoid churn and maintain backward compatibility indefinitely, so there is no rush to upgrade, but please use ListCustomers3 in new code whenever possible.

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

The v2 and v3 contracts are identical in behavior except that v2 emits the customer Bubblehouse ID under the field name bh_id while v3 emits it as bhid.

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.

Input

• fields string optional

  Which customer fields to include in the response.

  Use a comma-separated filter string such as default, ids,email,phone, or all.

  Supported values are field names from Customer2 and the built-in aspects ids, default, and all.

• format TabularDataFormat1 optional

  The response format you want: JSON, JSONL or CSV.

• limit integer optional

  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

• bh_id bubbleflake required

  Unique ID of the customer in the Bubblehouse system.

• custom_id string optional

  Custom 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_id string optional

  Shopify 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.

• email string required but can be empty

  The email address of the customer.

• phone string required but can be empty

  The phone number of the customer.

• first_name string required but can be empty

  The first (given) name of the customer.

• last_name string required but can be empty

  The last (family) name of the customer.

• full_name string required 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_imported boolean required

  Whether this customer has been imported from a prior loyalty system.

• is_tester boolean required

  Whether this customer is an internal tester account.

• birthday date optional

  The customer's birthday. The year is zero if unknown.

• signup_time time optional

  When the customer has signed up for an online shop account, if known.

• pts_balance integer required

  The number of loyalty points the customer currently has.

• pts_earned integer required

  The number of loyalty points the customer has ever earned.

• pts_redeemed integer required

  The number of loyalty points the customer has redeemed towards benefits.

• pts_expired integer required

  The number of loyalty points that have expired for this customer.

• tier string required but can be empty

  The name of the tier this customer is on, empty string if none.

• is_referred boolean required

  Whether this customer has been referred by another customer.

• referrer_shop_id string required 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_email string required but can be empty

  The email address of the customer that has referred this one, an empty string if unknown.

• referrals_sent integer required

  The number of referrals this customer has sent.

• referrals_approved integer required

  The number of approved referrals this customer has sent.

• referrals_declined integer required

  The number of referrals this customer has sent that have been ignored/declined/expired.

• votes integer required

  The number of votes the customer has recorded.

• reviews integer required

  The total number of reviews (of any type) the customer has posted.

Global Errors

Status	Error	Reason & Examples
401	invalid_token	The provided authentication token is invalid or 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.