# Filters Reference

Analytics endpoints (`POST /analytics/resource/{experienceId}` and the `POST /analytics/sitewide/*` endpoints) accept a `filters` parameter to narrow the result data as a **JSON object** in the request body.

The deprecated `GET /analytics/resource/{experienceId}` endpoint does not accept the new filters contract. It remains available only during the beta for the original query-parameter shape and will be removed when the beta version ends.

All filter fields are optional. Omit a field or set it to `null` to skip that filter.

#### Dimension Filters

| Field                   | Type      | Description                                   |
| ----------------------- | --------- | --------------------------------------------- |
| `deviceType`            | string    | `"any"`, `"mobile"`, or `"desktop"`           |
| `visitorType`           | string    | `"any"`, `"new"`, or `"returning"`            |
| `countryCodes`          | string\[] | ISO 3166-1 alpha-2 codes, e.g. `["US", "GB"]` |
| `sourceSitesOrChannels` | string\[] | Traffic channel names (see list below)        |

**Available traffic channels:** `Referral`, `All Social`, `Organic Social`, `Paid Social`, `Organic Search`, `Paid Search`, `Paid Shopping`, `Email`, `Google`, `Facebook`, `Instagram`, `Linktree`, `TikTok`, `Twitter`, `Direct`, `SMS`, `Meta`, `Youtube`, `Other`

#### Page & URL Filters

| Field         | Type   | Description                                                                       |
| ------------- | ------ | --------------------------------------------------------------------------------- |
| `landingPage` | object | `{ landingPageUrlPath: string, landingPageUrlPathFilterType: operator }`          |
| `urlParam`    | object | `{ queryParam: string, queryParamValue: string, queryParamFilterType: operator }` |

**Match operators** for `landingPageUrlPathFilterType`: `equals`, `contains`, `startsWith`, `endsWith`, `doesNotEqual`, `doesNotContain`, `doesNotStartWith`, `doesNotEndWith`, `isNull`, `isNotNull`

**Match operators** for `queryParamFilterType`: all of the above plus `regex`

#### User Behavior Filters

| Field                  | Type   | Description                                                                                                        |
| ---------------------- | ------ | ------------------------------------------------------------------------------------------------------------------ |
| `userBehavior`         | object | `{ viewedCheckout?: boolean, addedToCart?: boolean, viewedProductPage?: boolean, viewedCollectionPage?: boolean }` |
| `reachedCheckoutStage` | string | `"any"`, `"started"`, `"contact_info_submitted"`, `"address_info_submitted"`, `"added_to_cart"`                    |

#### Revenue & Order Filters

| Field                | Type           | Description                                          |
| -------------------- | -------------- | ---------------------------------------------------- |
| `minNetRevenue`      | number         | Minimum order net revenue (inclusive)                |
| `maxNetRevenue`      | number         | Maximum order net revenue (inclusive)                |
| `minShippingRevenue` | number         | Minimum shipping revenue (inclusive)                 |
| `maxShippingRevenue` | number         | Maximum shipping revenue (inclusive)                 |
| `shippingMethods`    | string\[]      | Shipping method names to include                     |
| `currency`           | string\[]      | ISO 4217 codes, e.g. `["USD", "EUR"]`                |
| `maxZScore`          | number \| null | Outlier Z-score threshold; `null` disables filtering |

#### Custom Events Filters

| Field                    | Type      | Description                                                                                                                                  |
| ------------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `triggeredCustomEvents`  | string\[] | Custom event identifiers. You can find the id for your custom event in the GET <https://api.intelligems.io/v25-10-beta/experiences> payload. |
| `customEventsFilterType` | string    | `"any"` (at least one), `"all"` (every event), `"none"` (none of the events)                                                                 |

#### Product Filters

| Field                    | Type      | Description                             |
| ------------------------ | --------- | --------------------------------------- |
| `experimentProductsOnly` | boolean   | Only include products in the experiment |
| `onlyProductIds`         | string\[] | Shopify product IDs to include          |
| `onlyProductHandles`     | string\[] | Shopify product handles to include      |

#### Advanced Targeting

| Field                                  | Type  | Description                                        |
| -------------------------------------- | ----- | -------------------------------------------------- |
| `pageTargeting`                        | array | Expression groups for page-level targeting         |
| `productTargeting`                     | array | Expression groups for product-level targeting      |
| `applyExperienceTargetingExperienceId` | UUID  | Reuse targeting config from an existing experience |

**Page targeting** — each group has `type` (one of: `utm`, `url`, `urlPath`, `device`, `visitor`, `trafficSource`, `country`, `referrer`, `cookie`, `klaviyo`, `landingPage`) and `queries` array. Each query: `{ key: string, value: string, filter: matchOperator, type: filterType }`.

**Product targeting** — each group has `type` (one of: `productId`, `collection`, `tag`, `price`, `inventory`) and `queries` array. Each query: `{ key: productAttribute, value: string | number, filter: productOperator, type: productAttribute }`. Product operators: `includes`, `doesNotInclude`, `greaterThan`, `lessThan`.

#### Example Filter Object

```json
{
  "deviceType": "mobile",
  "countryCodes": ["US", "CA"],
  "sourceSitesOrChannels": ["Paid Search", "Email"],
  "landingPage": {
    "landingPageUrlPath": "/collections/sale",
    "landingPageUrlPathFilterType": "startsWith"
  },
  "userBehavior": {
    "addedToCart": true
  },
  "minNetRevenue": 10,
  "maxNetRevenue": 500,
  "maxZScore": 3
}
```

For the resource and sitewide POST endpoints, send the filter object directly in the JSON body under `filters`.