Customers Query Selector

The Customer Query selector is a powerful tool that helps you target specific customers for your campaigns. This guide will show you how to create queries to find exactly the right customers at the right time.

What is a Customer Query?

A Customer Query is a search filter that automatically finds customers based on specific criteria when your campaign runs. It combines two powerful features:

  1. Shopify's search syntax - The same search language used throughout Shopify

  2. Liquid templating - Dynamic values that change based on when the campaign runs (like dates)

How to Use the Customer Query Field

1. Testing Your Query

Before saving your campaign, always use the Test Query button. This shows you:

  • How many customers currently match your query

  • If there are any errors in your query syntax

Important: The test runs with today's date and time, so results may differ when your campaign actually executes.

2. Query Structure

A basic query looks like this:

tag:birthday-06-15

A dynamic query with Liquid looks like this:

tag:*{{ "now" | date: "%m-%d" }}

Common Use Cases & Examples

Birthday Campaigns

Find customers with birthdays today:

tag:*{{ "now" | date: "%m-%d" }}

  • tag:* searches for tags containing the pattern

  • {{ "now" | date: "%m-%d" }} generates today's date in month-day format (e.g., "06-15")

  • Requires customers to have tags like birthday-06-15 for June 15th birthdays

Find customers with birthdays this month:

tag:*{{ "now" | date: "%m" }}

  • Uses only the month (e.g., "06" for June)

  • Works with tags like birthday-month-06

Anniversary Campaigns

Find customers who joined exactly 1 year ago:

tag:*{{ "now" | date: "%Y" | minus: 1 }}-{{ "now" | date: "%m-%d" }}

  • Calculates last year's date dynamically

  • Works with tags like joined-2024-06-15

Tag-Based Targeting

Find VIP customers:

tag:vip

Find customers with multiple tags:

tag:vip AND tag:email-subscriber

Find customers with any of several tags:

tag:gold OR tag:platinum OR tag:diamond

Location-Based Targeting

Find customers in specific city:

city:London

Find customers in specific country:

country:Canada

Combine location with tags:

country:USA AND tag:vip

Email Subscription Status

Find customers who accept marketing:

email_marketing_consent:subscribed

Find customers who don't accept marketing:

email_marketing_consent:unsubscribed

Understanding Liquid Templating

Liquid is the templating language that makes your queries dynamic. It's enclosed in double curly braces: {{ }}

Date Formatting

The most common use is formatting dates:

Format
Output
Example

%Y

Year (4 digits)

2025

%y

Year (2 digits)

25

%m

Month (01-12)

06

%-m

Month (1-12, no leading zero)

6

%d

Day (01-31)

15

%-d

Day (1-31, no leading zero)

5

%B

Full month name

June

%b

Short month name

Jun

Date Filters

Get current date/time:

{{ "now" | date: "%Y-%m-%d" }}

Get tomorrow's date:

{{ "now" | date: "%s" | plus: 86400 | date: "%m-%d" }}

(86400 is the number of seconds in a day)

Get date from 7 days ago:

{{ "now" | date: "%s" | minus: 604800 | date: "%m-%d" }}

(604800 is the number of seconds in 7 days)

Advanced Query Examples

Seasonal Campaigns

Summer birthday customers (June-August):

tag:birthday-06* OR tag:birthday-07* OR tag:birthday-08*

Holiday season customers:

tag:*12-* AND email_marketing_consent:subscribed

Customer Engagement

Customers who haven't purchased in 90 days but are tagged:

tag:at-risk AND orders_count:>0

High-value customers:

tag:high-value AND email_marketing_consent:subscribed

Dynamic Monthly Campaigns

First day of current month:

tag:*{{ "now" | date: "%m" }}-01

Last week of current month:

tag:*{{ "now" | date: "%m" }}-2* OR tag:*{{ "now" | date: "%m" }}-3*

Query Operators

AND Operator

Customers must match all conditions:

tag:vip AND city:London

OR Operator

Customers must match at least one condition:

tag:gold OR tag:platinum

NOT Operator

Exclude customers matching a condition:

tag:customer NOT tag:exclude-from-campaigns

Wildcards (*)

Match partial patterns:

tag:birthday-*

Finds all tags starting with "birthday-"

Setting Up Customer Tags

For date-based campaigns (like birthdays), you need to tag your customers in Shopify first:

Birthday Tag Format

Recommended format: birthday-MM-DD

Examples:

  • birthday-01-15 (January 15)

  • birthday-06-30 (June 30)

  • birthday-12-25 (December 25)

How to Tag Customers

  1. Go to Shopify Admin → Customers

  2. Select a customer

  3. In the Tags field, add: birthday-MM-DD (replace with actual date)

  4. Save the customer

Tip: You can bulk tag customers by:

  • Importing a CSV with tags

  • Using Shopify Flow

  • Using a third-party app

Best Practices

1. Always Test Your Query

Click the Test Query button before saving. This prevents errors and shows you how many customers will be targeted.

2. Start Simple

Begin with basic queries and add complexity gradually:

  • Start: tag:birthday

  • Add date: tag:birthday-{{ "now" | date: "%m-%d" }}

  • Add consent: tag:birthday-{{ "now" | date: "%m-%d" }} AND email_marketing_consent:subscribed

3. Use Consistent Tag Formats

Stick to one format for similar tags:

  • ✅ Good: birthday-01-15, birthday-02-20

  • ❌ Bad: birthday-01-15, bday-2-20, birthday_march_10

4. Consider Email Consent

Always consider adding email consent to avoid sending to customers who opted out:

your-query AND email_marketing_consent:subscribed

5. Watch Your Customer Count

If your test shows more than 250 customers, consider:

  • Narrowing your query with additional filters

  • Checking if your tag format is too broad

  • Splitting into multiple campaigns

Troubleshooting

"Query returned an error"

  • Problem: Syntax error in your query

  • Solution: Check for:

    • Typos in operators (AND, OR, NOT)

    • Missing or extra curly braces {{ }}

    • Incorrect date format codes

"Found 0 customers"

  • Problem: No customers match your criteria

  • Solution:

    • Verify your customers have the required tags

    • Test without Liquid first: replace dynamic dates with fixed dates

    • Check for typos in tag names

"Found more than 250 customers"

This is a safety limit. If you see this:

  • Your query might be too broad

  • Check for wildcards that match too many tags

  • Add more specific filters to narrow results

Example fix:

❌ tag:customer
✅ tag:customer AND tag:birthday-{{ "now" | date: "%m-%d" }}

Query works in test but not during campaign

  • Problem: Time-based queries may differ between test and execution

  • Solution:

    • Remember that {{ "now" }} uses the campaign's execution time

    • Test queries will use the current moment

    • Scheduled campaigns run at specific times, affecting date-based filters

Examples by Campaign Type

Birthday Gift Cards Campaign

Daily birthday campaign:

tag:birthday-{{ "now" | date: "%m-%d" }} AND email_marketing_consent:subscribed

Birthday month campaign:

tag:birthday-{{ "now" | date: "%m" }}* AND email_marketing_consent:subscribed

Anniversary Campaign

Customer join anniversary:

tag:joined-{{ "now" | date: "%m-%d" }} AND orders_count:>0

VIP Customer Campaign

VIP customers in specific region:

tag:vip AND country:United States AND email_marketing_consent:subscribed

Re-engagement Campaign

Customers tagged for re-engagement this month:

tag:reengage-{{ "now" | date: "%Y-%m" }}

Getting Help

If you need assistance creating the right query for your campaign:

When contacting support, include:

  1. What you're trying to achieve

  2. Your current query

  3. The error message or unexpected result

  4. How many customers you expect vs. actual results

Pro Tip: Save successful queries in a document for future reference. You can reuse and adapt them for different campaigns!

PreviousSending Customer NotificationsNextRecipients Selector

Last updated