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 tags from your ecommerce system, used for segmentation and targeting

  These are the tags associated with the customer in your ecommerce system (e.g. membership levels, demographic groups, or other customer attributes like "vip", "wholesale", or "employee"). Setting this field completely replaces the customer's current shop tags in Bubblehouse.

  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.

  To add or remove individual tags without replacing the full set, use add_tags and remove_tags instead.

• add_tags array of string optional

  Tags to add to the customer's shop tags without replacing existing ones

  Appends the specified tags to the customer's shop tags (tags reflecting the external ecommerce system). Duplicate tags are automatically ignored.

  Use this when you want to add specific tags without affecting other tags the customer already has. If you want to replace all tags at once, use the tags field instead.

• remove_tags array of string optional

  Tags to remove from the customer

  Removes the specified tags from both the customer's shop tags (from the ecommerce system) and internal Bubblehouse-managed tags. Tags that are not present are silently ignored.

  Use this when you want to remove specific tags without affecting other tags the customer has. If you want to replace all shop tags at once, use the tags field instead.

• add_bh_tags array of string optional

  Bubblehouse-managed tags to add to the customer

  Appends the specified tags to the customer's Bubblehouse-managed tags. These are separate from the shop tags managed by your ecommerce system. Duplicate tags are automatically ignored.

  Bubblehouse tags are managed internally and are not synced back to your ecommerce platform. They are useful for loyalty-specific segmentation that should not appear in your ecommerce system.

  Bubblehouse tags are rarely exposed to API clients. Use this field only when instructed by the Bubblehouse team.

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

• email_marketing_consent ConsentStatus1 optional

  The customer's email marketing consent status

  When set to subscribed, the customer may be eligible for points via email subscription rewards (if configured).

• email_marketing_consent_change_time time optional

  When the customer's email marketing consent status last changed

  This timestamp is used for hysteresis prevention when awarding points for email subscriptions. If the store requires membership for subscription rewards, customers will only receive points if they subscribed after becoming a full loyalty member.

  When integrating with Bubblehouse, provide this timestamp if your system tracks when consent was given. This enables accurate reward eligibility checks for customers who subscribed before joining the loyalty program.

• sms_marketing_consent ConsentStatus1 optional

  The customer's SMS marketing consent status

  When set to subscribed, the customer may be eligible for points via SMS subscription rewards (if configured).

• sms_marketing_consent_change_time time optional

  When the customer's SMS marketing consent status last changed

  This timestamp is used for hysteresis prevention when awarding points for SMS subscriptions. If the store requires membership for subscription rewards, customers will only receive points if they subscribed after becoming a full loyalty member.

  When integrating with Bubblehouse, provide this timestamp if your system tracks when consent was given. This enables accurate reward eligibility checks for customers who subscribed before joining the loyalty program.

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