Customer2

Represents customer data that Bubblehouse takes in.

Kind	Type
Used in	CustomerDetails1, EstimateAccrual1, UpdateCustomers3, UpdateOrders4

Properties

• id string required in most cases

  ID of the customer in the ecommerce system

  There are two cases when this field may be omitted, and in both cases you have to provide an email instead. (1) When referencing an already existing customer by email. (2) When pushing data for a customer that does not yet exist in your ecommerce system (so it truly does not have an ID); we'll populate an ID later when we encounter customer data with the same email address.

  In case of Shopify, this is just a number without gid://shopify/Customer/ prefix. If your system gives similar fixed prefixes to products, we recommend that you strip them as well.

• email string highly recommended

  Email address of the customer

  It is highly recommended that you specify this field. Many use cases require the emails outright, including integration of Bubblehouse with most third-party tools like review systems and email marketing solutions.

  That said, if the customer truly does not have a known email in your system, you can obviously omit this field.

• phone string optional

  Phone number of the customer

  We currently do not treat phone numbers in any special way. In particular, you cannot identify a customer by phone number only without providing an id.

• first_name string optional

  The given name of the customer

  Bubblehouse will fall back to name if that field is provided and first_name and last_name are not.

• last_name string optional

  The family name of the customer

  Bubblehouse will fall back to name if that field is provided and first_name and last_name are not.

• full_name string optional

  The full name of the customer

  Bubblehouse will fall back to first_name + " " + last_name if one of those field is provided and full_name is not.

• extras JSON object (string keys and arbitrary values) optional

  Any additional data you want to associate with the customer.

  You can set up conditions (on promos, achievements, tiers, etc) to target only customers with specific values of extras. Ask our customer support team for that.

• tags array of string optional

  Customer labels or groups that can be used for segmentation and targeting

  Tags provide a way to categorize and group customers in your ecommerce system. Examples include membership levels, demographic groups, participation in specific programs, or other customer attributes like "vip", "wholesale", or "employee".

  You can use tags with Bubblehouse to implement conditional rewarding, where different customer segments receive different rewards or point multipliers. For example, you might offer VIP customers double points or exclusive access to certain achievements.

  Unlike extras, tags are simple string values without additional structure, making them ideal for straightforward categorization.

• optin boolean or null optional

  Whether the customer has opted into the loyalty program

  Can be true (opted in), false (opted out), or null (unknown). This is a tristate value.

  Only use this property when instructed by Bubblehouse staff.

• is_imported boolean or null optional

  Whether the customer was imported from another system

  Can be true (imported), false (not imported), or null (unknown). This is a tristate value used to distinguish between organically created and imported customers.

  Only use this property when instructed by Bubblehouse staff.

• birthday date optional

  The customer's date of birth

  Used for birthday rewards. Format as YYYY-MM-DD.

  Use 0-MM-DD format if the year is unknown.

• remove_on_null_birthday boolean optional

  If true, removes the birthday field when a null/empty value is provided

  This is a special flag used when you want to explicitly clear a previously set birthday value.

• anniversary date optional

  The date of the customer's loyalty anniversary — the day when they signed up for the loyalty program

  Used for anniversary rewards and special occasion marketing. Format as YYYY-MM-DD.

• remove_on_null_anniversary boolean optional

  If true, removes the anniversary field when a null/empty value is provided

  This is a special flag used when you want to explicitly clear a previously set anniversary value.

• referral_code string optional

  The referral code this customer used when signing up (as a referee)

  This is the code that was provided by another customer (the referrer) and used by this customer during signup to establish the referral relationship.

  Bubblehouse automatically processes referral codes used in orders. This property is for scenarios where referral codes are collected as part of the signup procedure, or through a separate UX outside of Bubblehouse.

• personal_referrer_code string optional

  The unique referral code assigned to this customer (as a referrer)

  This is the code that this customer can share with others to refer new customers. When someone signs up using this code, this customer becomes their referrer.

  Normally, Bubblehouse handles creation of referral codes automatically. This property is for scenarios where personal referral codes are pregenerated outside of Bubblehouse.

  You need to talk to Bubblehouse team prior to using this property.

• social_handles object (SocialPlatform1 to string) optional

  Social media handles for customer identification and matching

  A mapping of social media platform identifiers to the customer's handle (username) on that platform. This allows Bubblehouse to identify customers by their social media presence in addition to email and ecommerce ID.

  Handle Format

  Handles are normalized automatically: the @ prefix is stripped if present, and handles are matched case-insensitively. For example, @JohnDoe, johndoe, and JOHNDOE are all treated as the same handle.

  Customer Matching

  When you push customer data with social handles, Bubblehouse uses them to identify existing customers. If a customer is found by their social handle, additional identifiers (like email) will be adopted onto that customer record. If multiple identifiers point to different existing customers, Bubblehouse will report a conflict error.

  Example

  {
    "email": "john@example.com",
    "social_handles": {
      "tiktok": "johndoe",
      "instagram": "john_doe_official",
      "twitter": "johnd"
    }
  }

• custom_objects map from string keys to arrays of CustomObject1 optional

  Custom objects associated with the customer

  Allows attaching complex custom data structures to customers. Each custom object has an id field (mapping integration keys to IDs) and a data field (arbitrary JSON data).

  You need to talk to Bubblehouse team prior to using this property.

• deleted boolean optional

  Set to true to delete this customer in our system

  Bubblehouse does not have deletion APIs for most objects; instead, pass deleted: true when updating an object. Note that we won't delete the data immediately, in case there are other objects referencing this one.