Customer2

Properties

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

  Example: "123456789"

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

  Example: "jane@example.com"

• phonestringoptional

  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_namestringoptional

  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.

  Example: "Jane"

• last_namestringoptional

  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.

  Example: "Doe"

• full_namestringoptional

  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.

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

  Example: {"widget_doodads":17}

• tagsarray of stringoptional

  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.

• optinboolean or nulloptional

  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_importedboolean or nulloptional

  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.

• birthdaydateoptional

  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_birthdaybooleanoptional

  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.

• anniversarydateoptional

  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_anniversarybooleanoptional

  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_codestringoptional

  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_codestringoptional

  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.

• custom_objectsmap from string keys to arrays of CustomObject1optional

  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.

• deletedbooleanoptional

  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.

Examples

{
  "id": "123456789"
}

{
  "email": "jane@example.com"
}

{
  "id": "123456789",
  "email": "jane@example.com",
  "first_name": "Jane",
  "last_name": "Doe",
  "extras": {
    "widget_doodads": 17
  }
}