> For the complete documentation index, see [llms.txt](https://docs.giftcardfactory.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.giftcardfactory.app/misc/segment-query-selector.md).

# Segment Query Selector

The **Customer segment query** tab of the [Recipients Selector](/misc/recipients-selector.md) lets you target customers with Shopify's **segment query language** — the same language that powers **Customers → Segments** in your Shopify admin — without first saving a segment. The query is stored with the operation and **resolved when it runs**, so the audience always reflects your latest customer data.

{% hint style="info" %}
**Not the same as the Customers query tab.** The [Customers query](/misc/customers-query-selector.md) tab uses Shopify's *search* syntax (`tag:vip AND orders_count:>5`). The segment query tab uses the *segment* language (`customer_tags CONTAINS 'vip' AND number_of_orders > 5`). They have different field names and operators — don't mix them.
{% endhint %}

### How to Use the Segment Query Field

1. Switch to the **Customer segment query** tab in the Recipients section.
2. Type your query (or click one of the **Examples** buttons to start from a template).
3. The app validates the query as you type and shows how many customers match **right now**. Syntax errors are shown with Shopify's own message (e.g. `'nope' filter cannot be found`).
4. Save. The query is stored with the operation; the actual recipient list is computed when it executes.

### Query Structure

A query is one or more **conditions** joined with `AND`, `OR` and `NOT`, with parentheses for grouping:

```
customer_tags CONTAINS 'vip' AND amount_spent >= 500
```

```
(customer_tags CONTAINS 'gold' OR customer_tags CONTAINS 'platinum') AND NOT customer_tags CONTAINS 'exclude'
```

**Operators:** `=`, `!=`, `>`, `>=`, `<`, `<=`, `CONTAINS`, `NOT CONTAINS`, `STARTS_WITH`, `ENDS_WITH`, `BETWEEN … AND …`, `IS NULL`, `IS NOT NULL`. Text values are wrapped in single quotes; numbers and dates are **not** quoted.

### Common Use Cases & Examples

#### Tags

**Customers with a tag:**

```
customer_tags CONTAINS 'vip'
```

**Any of several tags:**

```
customer_tags CONTAINS 'gold' OR customer_tags CONTAINS 'platinum'
```

#### Spend & Orders

**Spent 500 or more (lifetime):**

```
amount_spent >= 500
```

**Repeat customers:**

```
number_of_orders >= 3
```

**Big spenders who haven't ordered lately:**

```
amount_spent > 1000 AND last_order_date < -90d
```

#### Dates (relative and absolute)

Relative dates count back from today in your **shop's timezone** and are written without quotes: `-7d`, `-30d`, `-6m`, `-1y`. You can also use `today`, `yesterday` and absolute dates such as `2026-01-31`.

**Ordered in the last 30 days:**

```
last_order_date > -30d
```

**New customers (added in the last 7 days):**

```
customer_added_date > -7d
```

**Signed up in a date range:**

```
customer_added_date BETWEEN 2026-01-01 AND 2026-03-31
```

#### Birthdays & Anniversaries (metafields)

Segment queries can match **customer metafields** — as long as a **metafield definition** exists for them (Settings → Custom data → Customers). Store the birthday as a `date` metafield (for example `facts.birth_date`) and use the `anniversary` function:

```
anniversary(date: 'metafields.facts.birth_date') = today
```

Combine with a scheduled daily campaign to send a gift card on every customer's birthday. Note that **function parameters are named** — `anniversary(date: '…')` works, `anniversary('…')` does not.

**Metafield value checks:**

```
metafields.custom.loyalty_tier = 'gold'
```

#### Marketing Consent

Recommended for any campaign that sends email:

```
customer_tags CONTAINS 'vip' AND email_subscription_status = 'SUBSCRIBED'
```

#### Location

```
customer_countries CONTAINS 'CA'
```

```
customer_cities CONTAINS 'US-NY-NewYorkCity'
```

#### Products Purchased

```
products_purchased(id: 1234567890) = true
```

```
products_purchased(tag: 'summer-collection') = true
```

#### Store Credit

Target customers by their store credit balance (great for [Store Credit Bulk Add](/bulk-operations/store-credit-bulk-add.md) top-ups or reminder-style campaigns):

```
store_credit_accounts MATCHES (balance > 0)
```

```
store_credit_accounts MATCHES (balance >= 50) AND store_credit_accounts MATCHES (currency = 'USD')
```

Each `MATCHES (...)` clause may contain **one** field — use several clauses joined with `AND` for multiple conditions.

### Liquid Templating

Like the Customers query tab, the segment query is rendered with [Liquid](/misc/customers-query-selector.md#understanding-liquid-templating) before it runs, so `{{ "now" | date: "%Y-%m-%d" }}` works. In practice you rarely need it: the segment language has **built-in relative dates** (`today`, `-30d`) that resolve in your shop's timezone, whereas Liquid's `"now"` uses the server clock. Prefer the built-in forms.

### Limits

* Operations resolving **more than 3000 customers** are paused (bulk operations) or paused with an error (campaigns) to prevent accidental mass sending. The count preview warns you before you save.
* Customers without an email address are skipped for email-based operations.
* The preview count reflects **today's** data; scheduled runs use the data at execution time.

### Troubleshooting

**"… filter cannot be found" / syntax error**

* Check the field name against [Shopify's segment filter reference](https://help.shopify.com/en/manual/customers/customer-segmentation/customer-segments-reference).
* Text values need single quotes; dates and numbers must be unquoted.
* Functions need named parameters: `anniversary(date: '…')`.

**Metafield query is rejected**

* A **metafield definition** must exist for the customer metafield (date, number, text or boolean types) before it can be queried.

**"Found 0 customers"**

* Verify the tag / value spelling — matches are exact.
* Relative dates only look **backwards** (`-30d`); future dates must be written as absolute dates.

**Query works in Shopify admin but not here**

* Copy the query from Shopify's segment editor exactly — the app runs the same engine. Contact <support@code57.pl> with the query and we'll help.

### Related

* [Recipients Selector](/misc/recipients-selector.md) — all five ways to choose recipients.
* [Customers Query Selector](/misc/customers-query-selector.md) — the search-syntax alternative with Liquid date examples.
* Shopify: [Customer segments reference](https://help.shopify.com/en/manual/customers/customer-segmentation/customer-segments-reference).