Shopify-based customer segment filters

This page was printed on Jun 26, 2023. For the current version, visit https://help.shopify.com/en/manual/customers/customer-segmentation/customer-segments/customer-segmentation-reference/customer-segment-shopify.

Use this reference guide to understand the filter names, operators, and values that are used to build customer segments that are based on the default Shopify filters.

On this page

Abandoned checkout date

abandoned_checkout_date

Includes customers by the date that they last abandoned their cart.

Operators Exactly on date:=
Not on date:!=
On or before date:<=
Before date:<
On or after date:>=
After date:>
Between dates:BETWEEN AND
Doesn't exist:IS NULL
Exists:IS NOT NULL
Values
Format Absolute date:YYYY-MM-DD
Date offset examples:-4w,-10y
Named date:
  • Today:= today
  • Yesterday:= yesterday
  • In the last 7 days:>= 7_days_ago
  • In the last 30 days:>= 30_days_ago
  • In the last 90 days:>= 90_days_ago
  • In the last 12 months:> = 12 _months_ago
The named dates are default values and can't be changed. For custom dates, use a date offset
Example

Include customers who last abandoned their cart within the last week:abandoned_checkout_date >= 7_days_ago

Include customers who last abandoned their cart within the last eight months:abandoned_checkout_date > -8m
Notes Date values are based on entire days and depend on which time zone your store is in.

Anniversary

anniversary()

Includes customers by the date of the event associated with the date parameter.

Function parameters date(required): Use this parameter to specify which event you want to filter on.
Operators Exactly on date:=
Between dates:BETWEEN AND
Values
Format Absolute date:YYYY-MM-DD
Date offset examples:+4w,+3m
Named date:
  • Today:= today
  • In the next 7 days:BETWEEN today AND +7d
  • In the next 30 days:BETWEEN today AND +30d
Example

Include customers with a birthday in the next 30 days:
anniversary(date: 'metafields.facts.birth_date') BETWEEN today AND +30d
Notes
  • The year is is not used to segment when using absolute dates.
  • Date values are based on entire days and depend on which time zone your store is in.
  • To filter on birth dates, you need to either enable thefacts.birth_datestandard metafield or create your own custom metafield. Learn more aboutadding standard metafieldsorcreating custom metafield definitions.

Amount spent

amount_spent

Includes customers based on how much money they have spent in your store.

Operators Is equal to:=
Is not equal to:!=
Greater than:>
Smaller than:<
Smaller or equal to:<=
Greater or equal to:>=
Between:BETWEEN
Values
Format Number range:# AND #
Number:#
Decimal number: The decimal point (.) is used as the decimal separator.
Thousand separators, such as commas or spaces, are not accepted.
Language-specific formatted numbers are not accepted.
Example Include customers who have spent 1 to 999.99 in your store:
amount_spent BETWEEN 1 AND 999.99
Notes
  • The currency that is used is based on the currency that is selected for your store. Don't specify which currency is used by entering a currency symbol.
  • BETWEENincludes both the start and the end values. For example,amount_spent BETWEEN 1 AND 100includes customers who have spent at least 1 and as much as 100.

Cities

customer_cities

Includes customers who have an address in the specified city. Customers who have multiple addresses might be included in more than one customer segment that uses this filter.

Operators Contains this exact city:CONTAINS
Doesn't contain this exact city:NOT CONTAINS
Doesn't exist:IS NULL
Exists:IS NOT NULL
Values
Format countryCode-regionCode-cityCode
Example Include customers who have an address in New York City:
customer_cities CONTAINS 'US-NY-NewYorkCity'
Notes To find a city, you can start typing the name of the city, and then select the appropriate value from the list that is displayed.

Companies

companies

Includes customers from companies that have been configured asB2B customers.

Operators Contains this exact company ID:CONTAINS
Doesn't contain this exact company ID:NOT CONTAINS
Doesn't exist:IS NULL
Exists:IS NOT NULL
Values Company ID
Format
Example Is a B2B customer:
companies NOT NULL
Is not a B2B customer:
companies NULL
Includes customers who are affiliated with a specific company:
companies CONTAINS 3778915041302
Notes
  • When you create the customer segment, you can select the company by its name from the list that's displayed. Alternatively, you can start typing the title of the company, and then select it from the list.
  • The company ID, not the company name, is entered into the code. When you hover your cursor over the company ID, the company name is displayed.

Countries or regions

customer_countries

Includes customers who have an address in the specified country or region. Customers who have multiple addresses might be included in more than one customer segment that uses this filter.

Operators Contains this exact location:CONTAINS
Doesn't contain this exact location:NOT CONTAINS
Doesn't exist:IS NULL
Exists:IS NOT NULL
Values Use theISOtwo-letter country code.
Format
Example Include customers who have an address in the United States:
customer_countries CONTAINS 'US'
Notes To find a country, you can start typing the name of the country, and then select the appropriate value from the list that is displayed.

Customer account status

customer_account_status

包括顾客the specifiedcustomer accountstatus.

Operators Is equal to:=
Is not equal to:!=
Values Declined:'DECLINED'The customer was invited to create an account, but declined.
Disabled:'DISABLED'The customer has not created an account.
Enabled:'ENABLED'The customer created an account.
Invited:'INVITED'The customer has been invited to create an account.
Format
Example Include customers who have been invited to create an account, but declined:
customer_account_status = 'DECLINED'
Notes

Customer added date

customer_added_date

Includes customers based on the date that they were added to your store.

Operators Exactly on date:=
Not on date:!=
On or before date:<=
Before date:<
On or after date:>=
After date:>
Between dates:BETWEEN AND
Values
Format Absolute date:YYYY-MM-DD
Date offset examples:-4w,-10y
Named date:
  • Today:= today
  • Yesterday:= yesterday
  • In the last 7 days:>= 7_days_ago
  • In the last 30 days:>= 30_days_ago
  • In the last 90 days:>= 90_days_ago
  • In the last 12 months:> = 12 _months_ago
The named dates are default values and can't be changed. For custom dates, use a date offset.
Example

Include customers who were added within the last week:
customer_added_date >= 7_days_ago

Include customers who were added within the last eight months:
customer_added_date > -8m

Include customers who were added during a specific date range:
customer_added_date BETWEEN 2022-12-01 AND 2022-12-31
Notes Date values are based on entire days and depend on which time zone your store is in.

Customer email domain

customer_email_domain

Includes customers whose email address belongs to the specified domain. The domain name is the part of the email address after the@symbol, for example,gmail.com.

Operators Is equal to:=
Is not equal to:!=
Doesn't exist:IS NULL
Exists:IS NOT NULL
Values

The following domain names are offered as suggestions. You're not limited to these domain names. You can manually enter any other valid domain names.

gmail.com:'gmail.com'
yahoo.com:'yahoo.com'
hotmail.com:'hotmail.com'
aol.com:'aol.com'
msn.com:'msn.com'
live.com:'live.com'
outlook.com:'outlook.com'
yahoo.ca:'yahoo.ca'
Format
Example Include customers whose email domain is shopify.com:
customer_email_domain = 'shopify.com'
Notes

Customer language

customer_language

Includes customers based on the language that the customer uses to communicate with your store.

Operators Is equal to:=
Is not equal to:!=
Doesn't exist:IS NULL
Exists:IS NOT NULL
Values Use the ISO 639-1 two-letter language code.
Format

The following values are examples of some common ISO language codes. Your data isn't limited to these language codes. You can manually enter any other valid language codes, but the values that are offered to you as suggested values in the editor are the only ones that are available in your customer data.

English:'en'
French:'fr'
西班牙语:'es'
German:'de'
意大利:'it'
Japanese:'ja'
Russian:'ru'
Example

Include customers who communicate with your store in English:
customer_language = 'en'

Exclude customers who communicate with your store in Canadian English:
customer_language != 'en‑CA'
Notes
  • You can add the locale ISO code to the value to specify a dialect for that language. For example, you can use'en‑US'for the United States and'en‑GB'for the United Kingdom, or'pt‑PT'for Portugal and'pt‑BR'for Brazil.
  • The filter value acts as a wildcard if only the language prefix is specified. For example, if the filter value is'en', then your results include customers whose language is set to'en'and customers whose language is set to'en‑GB','en‑CA', and so on.

Customer tags

customer_tags

Includes customers based on their tags.

Operators Contains this exact tag:CONTAINS
Doesn't contain this exact tag:NOT CONTAINS
Doesn't exist:IS NULL
Exists:IS NOT NULL
Values The name of a customer tag.
Format
Example Include customers who have the GoldStatus tag:
customer_tags CONTAINS 'GoldStatus'
Notes

Tags are not case sensitive.

Learn more about tags and their considerations.

Email events

shopify_email.EVENT()

Includes customers based on selected email events. Supported events (EVENT) include the following:

  • Bounced:bounced
  • Clicked:clicked
  • Delivered:delivered
  • Marked as spam:marked_as_spam
  • Opened:opened
  • Unsubscribed:unsubscribed
Function parameters activity_id(optional): Use this parameter to select the marketing activity ID that you want to filter.
since(optional): Use this parameter to specify a start date for the event.
until(optional): Use this parameter to specify an end date for the event.
Operators Is equal to:=
Is not equal to:!=
Value true,false
Format Supported formats foractivity_id:
  • ID(single value)
  • List : A set of values with implicit "OR". AListis a set of comma-separated values wrapped with parentheses. For example:(1, 2, 3). There is a limit of 500 activity IDs in a list.

    SupportedDateformats forsinceanduntil:
    • Absolute date:YYYY-MM-DD
    • Date offset example:-4wor-10y
    • Named date:
      • Today:= today
      • Yesterday:= yesterday
      • In the last 7 days:>= 7_days_ago
      • In the last 30 days:>= 30_days_ago
      • In the last 90 days:>= 90_days_ago
      • In the last 12 months:> = 12 _months_ago
    		•
    Example Specify whether an email event happened using a=or!=operator:
    shopify_email.opened(activity_id: 135195754518) = false
    shopify_email.opened(activity_id: 135195754518) != true

    Use the parameteractivity_idto specify the marketing activity ID that you want to filter on:
    shopify_email.delivered(activity_id: 135195754518) = true

    Use the parametersinceto specify a start date for an email event:
    shopify_email.delivered(activity_id: 135195754518, since: 2022-01-01) = false

    Use the parameteruntilto specify an end date for an email event:
    shopify_email.delivered(activity_id: 135195754518, until: 2022-01-01) = true

    Use the parameterssinceanduntilto specify both a start and end date for an email event:
    shopify_email.bounced(activity_id: 135195754518, since: 12_months_ago, until: today) = false
    Notes
    • When you create a customer segment using theactivity_idparameter, you can select the marketing activity by its name from the list that's displayed.
    • Absence of bothsinceanduntilparameters means that results will be filtered for all time, with no set start or end date.
    • Absence ofactivity_idmeans that your filter includes all Shopify email activities.

    Email subscription status

    email_subscription_status

    Includes customers based on whether they are subscribed to your marketing email.

    Operators Is equal to:=
    Is not equal to:!=
    Doesn't exist:IS NULL
    Exists:IS NOT NULL
    Values Not subscribed:'NOT_SUBSCRIBED'The customer hasn't subscribed to your marketing email.
    Subscribed:'SUBSCRIBED'The customer is subscribed to your marketing email.
    Pending:'PENDING'The customer is in the process of subscribing to your marketing email.
    Invalid:'INVALID'The customer’s email address marketing state is invalid.
    Format
    Example Include customers who have subscribed to your email marketing:
    email_subscription_status = 'SUBSCRIBED'
    Notes

    Last order date

    last_order_date

    Includes customers who placed their last order on the date specified.

    Operators Exactly on date:=
    Not on date:!=
    On or before date:<=
    Before date:<
    On or after date:>=
    After date:>
    Between dates:BETWEEN AND
    Doesn't exist:IS NULL
    Exists:IS NOT NULL
    Values
    Format Absolute date:YYYY-MM-DD
    Date offset examples:-4w,-10y
    Named date:
    • Today:= today
    • Yesterday:= yesterday
    • In the last 7 days:>= 7_days_ago
    • In the last 30 days:>= 30_days_ago
    • In the last 90 days:>= 90_days_ago
    • In the last 12 months:> = 12 _months_ago
    The named dates are default values and can't be changed. For custom dates, use a date offset.
    Example

    Include customers whose last order was placed since last week:
    last_order_date >= 7_days_ago

    Include customers whose last order was placed since eight months ago:
    last_order_date > -8m
    Notes Date values are based on entire days and depend on which time zone your store is in.

    Number of orders

    number_of_orders

    Includes customers based on the number of orders that they have placed in your store.

    Operators Is equal to:=
    Is not equal to:!=
    Greater than:>
    Smaller than:<
    Smaller or equal to:<=
    Greater or equal to:>=
    Between:BETWEEN
    Values The value that you enter must be a whole number.
    Format Number range:# AND #
    Number:#
    Example Include customers who have placed more than 10 orders:
    number_of_orders > 10
    Notes BETWEENincludes both the start and the end values. For example,number_of_orders BETWEEN 1 AND 100includes customers who have placed at least 1 order and as many as 100 orders.

    Predicted spend tier

    predicted_spend_tier

    Includes customers who are within the specified predicted spend tier.

    This filter is only available if your store made more than 100 sales.

    Learn more aboutpredicted spend tier.

    Operators Is equal to:=
    Is not equal to:!=
    Doesn't exist:IS NULL
    Exists:IS NOT NULL
    Values 'HIGH'
    “媒介”
    'LOW'
    Format
    Example Include customers who are in the HIGH tier:
    predicted_spend_tier = 'HIGH'
    Notes

    Product subscription status

    product_subscription_status

    Includes customers who have the specifiedproduct subscriptionstatus.

    This filter is only available if you use a subscription app.

    Operators Is equal to:=
    Is not equal to:!=
    Doesn't exist:IS NULL
    Exists:IS NOT NULL
    Values Active:'SUBSCRIBED'The customer has an active product subscription.
    Cancelled:'CANCELLED'The customer has canceled their product subscription.
    Expired:'EXPIRED'The customer's product subscription has expired.
    Failed:'FAILED'The customer has a failed payment.
    Never subscribed:'NEVER_SUBSCRIBED'The customer never subscribed.
    Paused:'PAUSED'The customer has paused their product subscription.
    Format
    Example Include customers who have an active product subscription:
    product_subscription_status = 'SUBSCRIBED'
    Notes

    产品购买

    products_purchased()

    Includes customers who purchased the specified product. In addition, you can include customers who bought the product during a specified date range.


    Function parameters id(optional): Use this parameter to specify the product a customer has purchased that you want to filter.
    tag(optional): Use this parameter to specify a product tag for purchased products that you want to filter.
    since(optional): Use this parameter to specify a start date for the event.
    until(optional): Use this parameter to specify an end date for the event.
    Operators Is equal to:=
    Is not equal to:!=
    Value true,false
    Format Supported formats forid:
  • ID(single value)
  • List : A set of values provided as a list. For example:(1012132033639, 2012162031638, 32421429314657). There is a limit of 500 product IDs in a list.

    Supported formats fortag:
  • String(single value)

    SupportedDateformats forsinceanduntil:

    Absolute date:YYYY-MM-DD
    Date offset examples:-4w,-10y
    Named date:
    • Today:= today
    • Yesterday:= yesterday
    • In the last 7 days:>= 7_days_ago
    • In the last 30 days:>= 30_days_ago
    • In the last 90 days:>= 90_days_ago
    • In the last 12 months:> = 12 _months_ago
    The named dates are default values and can't be changed. For custom dates, use a date offset.
    		•
    Example Specify whether a product has been purchased using a=or!=operator:products_purchased() != true
    products_purchased(身份证:2012162031638)= true
    products_purchased(id: (2012162031638, 1012132033639)) = falseproducts_purchased(tag: 'red') = true


    Filter customers that purchased a specific product since January 1, 2022 until today:
    products_purchased(id: 1012132033639, since: 2022-01-01, until: today) = true
    Filter customers that purchased a product with the tag'red'since January 1, 2022 until today:
    products_purchased(tag: 'Red', since: 2022-01-01, until: today) = true
    Within the last 30 days:
    products_purchased(since: 30_days_ago) = true
    Until January 1, 2022:
    products_purchased(until: 2022-01-01) = true

    In date ranges, the order of thesinceanduntilparameters doesn't matter. You can express between January 1, 2022 and June 1, 2022 (inclusive) in either of the following ways:

    Between January 1, 2022 and June 1, 2022 (inclusive):
    products_purchased(id: 1012132033639, since: 2022-01-01, until: 2022-06-01) = true
    Between January 1, 2022 and June 1, 2022 (inclusive):
    products_purchased(id: 1012132033639, until: 2022-06-01, since: 2022-01-01) = true
    Notes
    • When you create the customer segment using theidparameter, you can select the product by its name or image from the list that's displayed. Alternatively, you can start typing the title of the product, and then select it from the list.
    • The product ID, not the product title, is entered into the code. When you hover your cursor over the product ID, the product title and image are displayed.
    • Absence of bothsinceanduntilparameters means that results will be filtered for all time, with no set start or end date.
    • Absence ofidmeans that your filter includes all products.

    SMS subscription status

    sms_subscription_status

    Includes customers based on whether they are subscribed to your marketing SMS text messages.

    Learn more aboutcollecting customer contact information.

    Operators Is equal to:=
    Is not equal to:!=
    Doesn't exist:IS NULL
    Exists:IS NOT NULL
    Values Subscribed:'SUBSCRIBED'The customer is subscribed to your marketing SMS text messages.
    Pending:'PENDING'The customer is in the process of subscribing to your marketing SMS text messages.
    Redacted:'REDACTED'The customer has pending redaction because of a GDPR erasure request
    Unsubscribed:'UNSUBSCRIBED'The customer has unsubscribed from your marketing SMS text messages.
    Not subscribed:'NOT_SUBSCRIBED'The customer never subscribed to your marketing SMS text messages.
    Format
    Example Include customers who have subscribed to your marketing SMS text messages:
    sms_subscription_status = 'SUBSCRIBED'
    Notes

    States or provinces

    customer_regions

    Includes customers who have an address in the specified region within a country. Customers who have multiple addresses might be included in more than one customer segment that uses this filter.

    Operators Contains this exact location:CONTAINS
    Doesn't contain this exact location:NOT CONTAINS
    Doesn't exist:IS NULL
    Exists:IS NOT NULL
    Values Use theISOcountry code with the ISO 3166-2 subdivision code.
    Format
    Example Include customers who have an address in New York State:
    customer_regions CONTAINS 'US-NY'
    Notes To find a region, you can start typing the name of the region, and then select the appropriate value from the list that is displayed.

    Ready to start selling with Shopify?

    Try it free