ListCustomers2

Returns a list of customers and their loyalty program data.

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

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

Note that the output is in a tabular data format determined by the format parameter.

Input

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