# 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.

<figure><img src="/files/30uv9A4fcKdb84CMT2RA" alt=""><figcaption></figcaption></figure>

### 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:**

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

**Get tomorrow's date:**

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

(86400 is the number of seconds in a day)

**Get date from 7 days ago:**

```liquid
{{ "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

#### Scheduled 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:

* **Email Support:** <support@code57.pl>

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

***

{% hint style="info" %}
**Pro Tip:** Save successful queries in a document for future reference. You can reuse and adapt them for different campaigns!
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.giftcardfactory.app/misc/customers-query-selector.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.