---
updatedAt: 2026-05-18T09:46:26.000Z
agentTools:
  projectIndex: https://triplewhale.readme.io/llms.txt
---

# Customers Table

customers_table

The Customers table provides customer profiles from sales and email/SMS platforms. One row per customer per platform; a customer on both a sales and email/SMS platform appears in multiple rows. Only customers with a `customer_id` from a connected platform are included. No Pixel data.

> 📋 Table Guide
>
> **What You Can Answer With This Table**
>
> * Who are our customers, and how can we identify or contact them? — use `email_address`, `phone`, `country`
> * What is a customer’s consent status for email and SMS marketing? — use `email_marketing_consent_status`, `sms_marketing_consent_opt_in_level`
> * Which customers are most valuable? — use `amount_spent`, `orders`
>
> **Before You Query**
>
> * This table is not time-series. No `event_date` filter is needed.
>
> **Key Relationships**
>
> | Table                                                                                                       | Join Key                                                | Use This Join To                                                                      |
> | :---------------------------------------------------------------------------------------------------------- | :------------------------------------------------------ | :------------------------------------------------------------------------------------ |
> | [Orders](https://triplewhale.readme.io/docs/orders-table)                                                   | `customer_id_key`                                       | Analyze order history and spending behavior for each customer                         |
> | [Pixel Orders](https://triplewhale.readme.io/docs/pixel-orders-table)                                       | `customer_id_key`                                       | Analyze channel and campaign attribution for each customer's orders                   |
> | [Customer Journey](https://triplewhale.readme.io/docs/customer-journey-table)                               | `customer_id`                                           | Analyze on-site behavior and purchase paths for known customers                       |
> | [Subscriptions](https://triplewhale.readme.io/docs/subscriptions-table)                                     | `customer_id`                                           | Analyze subscription status, cadence, and cancellation behavior for each customer     |
> | [CS Tickets](https://triplewhale.readme.io/docs/cs-tickets-table)                                           | `customer_id`                                           | Analyze support history and satisfaction signals alongside customer profile and value |
> | [Customer Segmentation](https://triplewhale.readme.io/docs/customer-segmentation-table)                     | `customer_id` or `email_address` to `customer_identity` | Group customer profiles into behavioral cohorts                                       |
> | [Customer Segmentation Analytics](https://triplewhale.readme.io/docs/customer-segmentation-analytics-table) | `customer_id` or `email_address` to `customer_identity` | Compare customer profiles with pre-aggregated segment performance                     |
> | [Pixel Custom Conversions](https://triplewhale.readme.io/docs/pixel-custom-conversions-table)               | `email_address` to `email`                              | Connect custom conversion activity to customer profiles and lifecycle value           |
>
> <br />
>
> **When to Use a Different Table**
>
> * Use [Customer Journey table](https://triplewhale.readme.io/docs/customer-journey-table) when you need customer journeys or on-site event paths. The Customers table is for customer profile and lifetime value data.
> * Use [Customer Segmentation Analytics table](https://triplewhale.readme.io/docs/customer-segmentation-analytics-table) when you need segment-level performance metrics. The Customers table is for individual customer profiles, not segment aggregates.
>
> *[View the full Triple Whale Data Ontology →](https://triplewhale.readme.io/docs/triple-whale-data-ontology)*

***

# Dimensions

Dimensions are immutable properties that can be used for grouping data.

<Table align={["left","left","left","left"]}>
  <thead>
    <tr>
      <th>
        Title
      </th>

      <th>
        ID
      </th>

      <th>
        Type
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        Address Line 1
      </td>

      <td>
        `address1`
      </td>

      <td>
        string
      </td>

      <td>
        The first line of the customer's default address.

        Example value: `764 Example Dr.`
      </td>
    </tr>

    <tr>
      <td>
        Address Line 2
      </td>

      <td>
        `address2`
      </td>

      <td>
        string
      </td>

      <td>
        The second line of the customer's default address.

        Example value: `Apt. 603`
      </td>
    </tr>

    <tr>
      <td>
        City
      </td>

      <td>
        `city`
      </td>

      <td>
        string
      </td>

      <td>
        The city of the customer's default address.

        Example value: `San Francisco`
      </td>
    </tr>

    <tr>
      <td>
        Coordinates Validated
      </td>

      <td>
        `coordinates_validated`
      </td>

      <td>
        boolean
      </td>

      <td>
        Indicates whether the customer coordinates were successfully validated.

        Possible values: `true`, `false`
      </td>
    </tr>

    <tr>
      <td>
        Country
      </td>

      <td>
        `country`
      </td>

      <td>
        string
      </td>

      <td>
        The country of the customer's default address. See [list of countries](https://shopify.dev/docs/api/storefront/latest/enums/CountryCode).

        Example values: `United States`, `Canada`, `United Kingdom`
      </td>
    </tr>

    <tr>
      <td>
        Country Code
      </td>

      <td>
        `country_code`
      </td>

      <td>
        string
      </td>

      <td>
        The country code of the customer's default address. See [list of countries](https://shopify.dev/docs/api/storefront/latest/enums/CountryCode).

        Example values: `US`, `CA`, `GB`
      </td>
    </tr>

    <tr>
      <td>
        Customer Created Date
      </td>

      <td>
        `created_at`
      </td>

      <td>
        timestamp
      </td>

      <td>
        The time at which the customer record was created. Formatted according to the [ISO 8601 international standard](https://www.iso.org/iso-8601-date-and-time-format.html).

        Example value: `2019-05-22 21:01:29`
      </td>
    </tr>

    <tr>
      <td>
        Customer ID
      </td>

      <td>
        `customer_id`
      </td>

      <td>
        string
      </td>

      <td>
        The unique identifier for the customer, assigned by the main sales platform.

        Example value: `5209503793328`
      </td>
    </tr>

    <tr>
      <td>
        Customer ID Key
      </td>

      <td>
        `customer_id_key`
      </td>

      <td>
        string
      </td>

      <td>
        Join key for connecting this table to other tables (e.g. Orders or Pixel Orders tables). Contains `customer_id` for Shopify shops and `email_address` for non-Shopify shops (e.g., Amazon, BigCommerce, WooCommerce).

        Example values: `5209503793328`, `customer@example.com`
      </td>
    </tr>

    <tr>
      <td>
        Customer Tags
      </td>

      <td>
        `customer_tags`
      </td>

      <td>
        repeated string
      </td>

      <td>
        Tags associated with the customer, set in the main sales platform.

        Example values: `Active Subscriber`, `PayPal_user`, `Login with FB`
      </td>
    </tr>

    <tr>
      <td>
        Display Name
      </td>

      <td>
        `display_name`
      </td>

      <td>
        string
      </td>

      <td>
        The display name of the customer.

        Example value: `John Doe`
      </td>
    </tr>

    <tr>
      <td>
        Email Address
      </td>

      <td>
        `email_address`
      </td>

      <td>
        string
      </td>

      <td>
        The primary email address associated with the customer’s account.

        Example value: `customer@example.com`
      </td>
    </tr>

    <tr>
      <td>
        Email Marketing Consent Collected From
      </td>

      <td>
        `email_marketing_consent_collected_from`
      </td>

      <td>
        string
      </td>

      <td>
        The source from which the customer's email marketing consent was collected.
      </td>
    </tr>

    <tr>
      <td>
        Email Marketing Consent Opt-In Level
      </td>

      <td>
        `email_marketing_consent_opt_in_level`
      </td>

      <td>
        string
      </td>

      <td>
        The level of consent provided by the customer for email marketing.

        Example values: `SINGLE_OPT_IN`, `UNKNOWN`
      </td>
    </tr>

    <tr>
      <td>
        Email Marketing Consent Status
      </td>

      <td>
        `email_marketing_consent_status`
      </td>

      <td>
        string
      </td>

      <td>
        The current status of the customer's email marketing consent.

        Example values: `NEVER_SUBSCRIBED`, `NOT_SUBSCRIBED`, `UNSUBSCRIBED`, `SUBSCRIBED`
      </td>
    </tr>

    <tr>
      <td>
        Email Marketing Consent Updated Date
      </td>

      <td>
        `email_marketing_consent_updated_at`
      </td>

      <td>
        timestamp
      </td>

      <td>
        The time at which the email marketing consent was updated. Formatted according to the [ISO 8601 international standard](https://www.iso.org/iso-8601-date-and-time-format.html).

        Example value: `2019-05-22 21:01:29`
      </td>
    </tr>

    <tr>
      <td>
        First Name
      </td>

      <td>
        `first_name`
      </td>

      <td>
        string
      </td>

      <td>
        The customer's first name.

        Example value: `John`
      </td>
    </tr>

    <tr>
      <td>
        Last Name
      </td>

      <td>
        `last_name`
      </td>

      <td>
        string
      </td>

      <td>
        The customer's last name.

        Example value: `Doe`
      </td>
    </tr>

    <tr>
      <td>
        Last Order ID
      </td>

      <td>
        `last_order_id`
      </td>

      <td>
        string
      </td>

      <td>
        The ID of the most recent order from the customer, according to the main sales platform.

        Example value: `4930225799243`
      </td>
    </tr>

    <tr>
      <td>
        Latitude
      </td>

      <td>
        `latitude`
      </td>

      <td>
        string
      </td>

      <td>
        The latitude associated with the customer's location.

        Example value: `34.1413713`
      </td>
    </tr>

    <tr>
      <td>
        Locale
      </td>

      <td>
        `locale`
      </td>

      <td>
        string
      </td>

      <td>
        The locale setting associated with the customer's account.

        Example values: `en-US`, `en_GB`, `de`
      </td>
    </tr>

    <tr>
      <td>
        Longitude
      </td>

      <td>
        `longitude`
      </td>

      <td>
        string
      </td>

      <td>
        The longitude associated with the customer's location.

        Example value: `-118.8639169`
      </td>
    </tr>

    <tr>
      <td>
        Metafields
      </td>

      <td>
        `metafields`
      </td>

      <td>
        record repeated
      </td>

      <td>
        Custom key–value pairs attached to each customer record, used to store additional structured or unstructured data beyond standard fields.
      </td>
    </tr>

    <tr>
      <td>
        Metafield ID
      </td>

      <td>
        `metafields.metafield_id`
      </td>

      <td>
        string
      </td>

      <td>
        The unique identifier of the metafield record.

        Example values: `44187839136031`
      </td>
    </tr>

    <tr>
      <td>
        Metafield Key
      </td>

      <td>
        `metafields.key`
      </td>

      <td>
        string
      </td>

      <td>
        The unique key of the metafield within its namespace, indicating what data it holds.

        Example values: `promised_delivery_date`,  `zone`, `agree_to_terms`
      </td>
    </tr>

    <tr>
      <td>
        Metafield Value
      </td>

      <td>
        `metafields.value`
      </td>

      <td>
        string
      </td>

      <td>
        The raw stored value of the metafield. Format depends on the metafield type (e.g., text, date, boolean, JSON). 

        Example values: `2025-11-10`, `true`, `#241194`, `5a`
      </td>
    </tr>

    <tr>
      <td>
        Metafield Namespace
      </td>

      <td>
        `metafields.namespace`
      </td>

      <td>
        string
      </td>

      <td>
        Logical grouping used to organize metafields by source or purpose.

        Example values: `custom`, `klaviyo`, `checkoutblocks`
      </td>
    </tr>

    <tr>
      <td>
        Metafield Type
      </td>

      <td>
        `metafields.type`
      </td>

      <td>
        string
      </td>

      <td>
        The data type of the metafield value (e.g., text, date, boolean, JSON, reference).

        Example values: `date`, `boolean`, `json`, `single_line_text_field`, `customer_reference`
      </td>
    </tr>

    <tr>
      <td>
        Metafield Updated Date
      </td>

      <td>
        `metafields.updated_at`
      </td>

      <td>
        timestamp
      </td>

      <td>
        When the metafield was last updated, in shop time zone.

        Example value: `2025-10-21 07:08:01`
      </td>
    </tr>

    <tr>
      <td>
        Metafield Created Date
      </td>

      <td>
        `metafields.created_at`
      </td>

      <td>
        timestamp
      </td>

      <td>
        When the metafield was first created, in shop time zone.

        Example value: `2025-10-21 07:08:01`
      </td>
    </tr>

    <tr>
      <td>
        Note
      </td>

      <td>
        `note`
      </td>

      <td>
        string
      </td>

      <td>
        Note attached to the customer profile.
      </td>
    </tr>

    <tr>
      <td>
        Phone
      </td>

      <td>
        `phone`
      </td>

      <td>
        string
      </td>

      <td>
        The customer's phone number.

        Example value: `18005550199`
      </td>
    </tr>

    <tr>
      <td>
        Platform
      </td>

      <td>
        `platform`
      </td>

      <td>
        string
      </td>

      <td>
        The platform associated with the customer record.

        Example values: `shopify`, `klaviyo`
      </td>
    </tr>

    <tr>
      <td>
        Product Subscriber Status
      </td>

      <td>
        `product_subscriber_status`
      </td>

      <td>
        string
      </td>

      <td>
        The customer's subscription status for products.

        Example values: `ACTIVE`, `PAUSED`, `CANCELLED`, `NEVER_SUBSCRIBED`
      </td>
    </tr>

    <tr>
      <td>
        SMS Marketing Consent Collected From
      </td>

      <td>
        `sms_marketing_consent_collected_from`
      </td>

      <td>
        string
      </td>

      <td>
        The source from which the customer's SMS marketing consent was collected.
      </td>
    </tr>

    <tr>
      <td>
        SMS Marketing Consent Opt-In Level
      </td>

      <td>
        `sms_marketing_consent_opt_in_level`
      </td>

      <td>
        string
      </td>

      <td>
        The level of consent provided by the customer for SMS marketing.

        Example values: `SINGLE_OPT_IN`, `CONFIRMED_OPT_IN`
      </td>
    </tr>

    <tr>
      <td>
        SMS Marketing Consent Updated Date
      </td>

      <td>
        `sms_marketing_consent_updated_at`
      </td>

      <td>
        timestamp
      </td>

      <td>
        The time at which the sms marketing consent was updated. Formatted according to the [ISO 8601 international standard](https://www.iso.org/iso-8601-date-and-time-format.html).

        Example value: `2019-05-22 21:01:29`
      </td>
    </tr>

    <tr>
      <td>
        State
      </td>

      <td>
        `state`
      </td>

      <td>
        string
      </td>

      <td>
        The state or province of the customer's default address.

        Example values: `Oregon`, `British Colombia`, `Michigan`
      </td>
    </tr>

    <tr>
      <td>
        State Code
      </td>

      <td>
        `state_code`
      </td>

      <td>
        string
      </td>

      <td>
        The state or province code of the customer's default address.

        Example values: `OR`, `BC`, `MI`
      </td>
    </tr>

    <tr>
      <td>
        Predicted Spend Tier
      </td>

      <td>
        `statistic_predicted_spend_tier`
      </td>

      <td>
        string
      </td>

      <td>
        A predicted tier for how much the customer is likely to spend.

        Example values: `LOW`, `MEDIUM`, `HIGH`
      </td>
    </tr>

    <tr>
      <td>
        Customer Status
      </td>

      <td>
        `status`
      </td>

      <td>
        string
      </td>

      <td>
        The current status of the customer in the system.

        Example values: `INVITED`, `ENABLED`, `DISABLED`, `UNSUBSCRIBED`, `NEVER_SUBSCRIBED`, `DECLINED`
      </td>
    </tr>

    <tr>
      <td>
        Tax Exempt
      </td>

      <td>
        `tax_exempt`
      </td>

      <td>
        boolean
      </td>

      <td>
        Indicates whether the customer is exempt from tax.

        Possible values: `true`, `false`
      </td>
    </tr>

    <tr>
      <td>
        Valid Email Address
      </td>

      <td>
        `valid_email_address`
      </td>

      <td>
        boolean
      </td>

      <td>
        Whether the email address has passed a validation check.

        Possible values: `true`, `false`
      </td>
    </tr>

    <tr>
      <td>
        Verified Email Address
      </td>

      <td>
        `verified_email_address`
      </td>

      <td>
        boolean
      </td>

      <td>
        Whether the email address has been verified by the platform.

        Possible values: `true`, `false`
      </td>
    </tr>

    <tr>
      <td>
        Zip/Postal Code
      </td>

      <td>
        `zip`
      </td>

      <td>
        string
      </td>

      <td>
        The zip or postal code of the customer's defaults address.

        Example values: `48104`, `18235-2239`, `CH25 9BH`
      </td>
    </tr>
  </tbody>
</Table>

# Measures

Measures are numeric fields that can be aggregated and/or combined to calculate new metrics.

| Title        | ID             | Type    | Description                                        |
| :----------- | :------------- | :------ | :------------------------------------------------- |
| Amount Spent | `amount_spent` | numeric | The total amount spent by the customer.            |
| Orders       | `orders`       | numeric | The total number of orders placed by the customer. |

<HTMLBlock>{`
<style>
  .content-toc {
    flex: 0 0 220px !important;
}
  .rm-Guides .content-body {
    max-width: calc(100% - 140px) !important;
    width: 960px !important;
}
</style>
`}</HTMLBlock>