> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shoppex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Email segmentation filters

> JSON filter rules for email marketing audience segments

Email marketing segments use a JSON object called `filter_rules`.

You can create segments in the dashboard under **Marketing -> Email -> Audience -> Segments** or through `POST /dev/v1/email-marketing/segments`.

<Note>
  All top-level rules are combined with `AND`. Empty JSON (`{}`) means all eligible subscribed contacts.
</Note>

For keys that accept an array, entries inside that array are combined as `OR`. For example, `"country": ["DE", "AT"]` means Germany or Austria.

## Product purchase

Use product filters when you want customers who bought a specific product. Product filters match paid invoices with status `COMPLETED`, `PARTIAL_REFUND`, or `REFUNDED`. Developer invoices are excluded.

```json theme={"system"}
{
  "product_id": "PRODUCT_ID_OR_UNIQID"
}
```

Multiple products:

```json theme={"system"}
{
  "product_ids": ["PRODUCT_ID_1", "PRODUCT_UNIQID_2"]
}
```

Nested form:

```json theme={"system"}
{
  "product": {
    "uniqids": ["product_abc", "product_def"]
  }
}
```

Supported product keys:

| Key                   | Value        |
| --------------------- | ------------ |
| `product_id`          | string       |
| `product_ids`         | string array |
| `productId`           | string       |
| `productIds`          | string array |
| `product.id`          | string       |
| `product.ids`         | string array |
| `product.product_id`  | string       |
| `product.product_ids` | string array |
| `product.productId`   | string       |
| `product.productIds`  | string array |
| `product.uniqid`      | string       |
| `product.uniqids`     | string array |

## Spending

Spending filters use the customer profile `total_spent` field.

Customers who spent at least 100:

```json theme={"system"}
{
  "min_total_spent": 100
}
```

Customers who spent at most 500:

```json theme={"system"}
{
  "max_total_spent": 500
}
```

Range:

```json theme={"system"}
{
  "min_total_spent": 100,
  "max_total_spent": 500
}
```

CamelCase is also supported:

```json theme={"system"}
{
  "minTotalSpent": 100,
  "maxTotalSpent": 500
}
```

## Order count

Order count filters use the customer profile `order_count` field.

```json theme={"system"}
{
  "min_order_count": 2
}
```

```json theme={"system"}
{
  "max_order_count": 10
}
```

CamelCase is also supported:

```json theme={"system"}
{
  "minOrderCount": 2,
  "maxOrderCount": 10
}
```

## Country

Country filters use ISO 3166-1 alpha-2 country codes from the customer profile.

```json theme={"system"}
{
  "country": "DE"
}
```

Multiple countries:

```json theme={"system"}
{
  "country": ["DE", "AT", "CH"]
}
```

`country_code` is also supported:

```json theme={"system"}
{
  "country_code": "US"
}
```

`country_code` can also be an array.

## Tags

Match one tag:

```json theme={"system"}
{
  "tags": {
    "contains": "vip"
  }
}
```

Match any tag:

```json theme={"system"}
{
  "tags": {
    "any": ["vip", "wholesale"]
  }
}
```

Require all tags:

```json theme={"system"}
{
  "tags": {
    "all": ["vip", "repeat-buyer"]
  }
}
```

## Consent basis

Segments can narrow contacts to a specific marketing consent basis. Campaign sends only include eligible subscribed contacts.

```json theme={"system"}
{
  "consent_basis": "SOFT_OPT_IN"
}
```

```json theme={"system"}
{
  "consent_basis": "CONSENT"
}
```

`consent` is also supported:

```json theme={"system"}
{
  "consent": "CONSENT"
}
```

Both `consent_basis` and `consent` can also be arrays:

```json theme={"system"}
{
  "consent_basis": ["CONSENT", "SOFT_OPT_IN"]
}
```

## Source

Use source when you need contacts created through a specific path.

```json theme={"system"}
{
  "source": "backfill:paid_invoice"
}
```

Multiple sources:

```json theme={"system"}
{
  "source": ["customer_portal", "backfill:paid_invoice"]
}
```

Examples of common sources include `customer_portal`, `dev-api`, `manual`, `backfill:paid_invoice`, and automation sources like `automation:post_purchase`.

## Last activity

Last activity filters use the email contact `updated_at` timestamp.

```json theme={"system"}
{
  "last_activity": {
    "within_days": 30
  }
}
```

CamelCase is also supported:

```json theme={"system"}
{
  "lastActivity": {
    "withinDays": 30
  }
}
```

## Combined examples

Customers from Germany who bought a product and spent at least 100:

```json theme={"system"}
{
  "country": "DE",
  "product_id": "PRODUCT_ID_OR_UNIQID",
  "min_total_spent": 100
}
```

VIP customers in DACH countries who ordered at least twice:

```json theme={"system"}
{
  "country": ["DE", "AT", "CH"],
  "tags": {
    "contains": "vip"
  },
  "min_order_count": 2
}
```

Recent paid-invoice contacts for one product:

```json theme={"system"}
{
  "source": "backfill:paid_invoice",
  "product_id": "PRODUCT_ID_OR_UNIQID",
  "last_activity": {
    "within_days": 30
  }
}
```

## Data source notes

* Product filters use paid invoice line items.
* Spending, order count, and country filters use customer profile fields.
* Tags, consent basis, source, and last activity use email audience contact fields.
* Contacts must still be subscribed, send-eligible, and linked to a known customer or paid buyer.