Customers table

The customers table contains data about your customers. It includes historical metrics (such as the total amount that each customer has spent in your store) as well as forward-looking metrics (such the predicted number of days between future orders and the expected order value in the next 30 days).

This table also includes columns that segment customers into various categories (such as new, returning, promising, at risk, dormant, and loyal), which you can use to target marketing activities. The customers table contains one row per customer.

Columns

Anchor link to section titled "Columns"
Column Data type Description
customer_id numeric The ID of the customer. This is the primary key column for the customers table.
shop_id numeric The ID of the store. This column is a foreign key reference to the shop_id column in the shops table.
Order history
average_order_size numeric The average amount of money that the customer spends on orders from the store. The value is formatted in the store's currency and it is calculated using the following formula: total_order_value / total_order_count.
total_order_count numeric The total number of orders that the customer has made from this store across their lifetime.
total_order_value numeric The total amount of money that the customer has spent on orders from the store across their lifetime. The value is formatted in the store's currency.
first_order_date timestamp The date (ISO 8601) and time (UTC) when the customer placed their first order. The format is YYYY-MM-DD HH:mm:ss (for example, 2016-02-05 17:04:01).
last_order_date timestamp The date (ISO 8601) and time (UTC) when the customer placed their most recent order. The format is YYYY-MM-DD HH:mm:ss (for example, 2016-02-05 17:04:01).
rank numeric A numeric ranking of the customer's lifetime value for the store relative to all customers.
Segment categories
new boolean Returns true if the customer made their first order in the last 30 days. Otherwise returns false.
returning boolean Returns true when the customer has made more than one order. Returns false when the customer has made one order only. Returns Null when the customer exists in Shopify, but they have not made any orders. For example, this column can be null because the customer provided their contact information and then abandoned the checkout. Customers can also be created manually in the Shopify admin and by apps that use the Admin API.
loyal boolean Returns true when the customer has a high probability of returning, and has placed more orders than the average customer. Otherwise returns false.
at_risk boolean Returns true for repeat customers, who have a medium probability of returning and have not placed an order in a while. Otherwise returns false.
dormant boolean Returns true when the customer has a very low probability of returning to make another purchase. Otherwise returns false.
promising boolean Returns true when the customer has a high probability of returning and becoming a loyal customer. Otherwise returns false.
Predictions
predicted_average_number_of_days_between_orders numeric The predicted number of days between future orders.
expected_purchase_value_in_next_30_days numeric The total purchase amount of the orders that the customer is expected to make in the next 30 days. The value is formatted in the store's currency.
probability_of_returning float8 The probability that the customer will place another order in the future.
Account information
first_name varchar The first name of the customer.
last_name varchar The last name of the customer.
city varchar The city from the customer's billing address. For example, Topeka.
region varchar The name of the region, such as the province or state, from the customer's billing address. For example, Alberta, Florida. This column is the same as CustomerAddress.province in the Admin API.
country varchar The country from the customer's billing address. For example, United States.
email varchar The email of the customer.
phone varchar The phone number of the customer.
verified_email boolean Returns true when the customer's email has been verified. Otherwise returns false.
created_at timestamp The date (ISO 8601) and time (UTC) when the customer was added to the store. The format is YYYY-MM-DD HH:mm:ss (for example, 2018-02-05 17:04:01).
account_state varchar The status of the customer's account with the online store. A customer with an accountcan log into the store using their email and password. The state can be changed in the Shopify admin or by the customer, but not through the API. Default value is disabled. Valid values:
  • disabled - the customer doesn't have an active account. Customer accounts can be disabled from the Shopify admin at any time.
  • declined - the customer declined the email invite to create an account.
  • enabled - the customer has created an account.
  • invited - the customer has been sent an email invite to create an account.
accepts_marketing boolean Returns true when the customer has agreed to accept marketing. Otherwise returns false.

Examples

Anchor link to section titled "Examples"

The following example returns the names of loyal customers that are predicted to spend more than $500 in the next 30 days:

The following example lists the provinces of France where customers live:

The following example counts the returning customers grouped by when they made their first order:

Anchor link to section titled "Related information"