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

# POST /v1/products — search affiliate products

> Search 1B+ affiliate products refreshed daily using filters, sorting, pagination, and faceted search across 40+ fields and multiple networks.

Use `POST /v1/products` to search a database of over one billion affiliate products refreshed daily. You can filter by price, brand, availability, network, merchant, and dozens of other fields, then sort and paginate the results or request facet aggregations to power dynamic filter UIs.

## Query builder

Before writing code, use the interactive query builder at [app.affiliate.com/tools/product-search](https://app.affiliate.com/tools/product-search) to build and test queries in your browser.

## Request

**Endpoint:** `POST /v1/products`

### Headers

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`.
</ParamField>

<ParamField header="Authorization" type="string" required>
  Your API key as a Bearer token: `Bearer {your_api_key}`.
</ParamField>

### Body parameters

<ParamField body="search" type="array | string">
  Search criteria for products. Mutually exclusive with `query` — use one or the other. Pass a plain string for a quick lookup, or an array of filter objects for full control over field, value, and operator.

  **Simple string:**

  ```json theme={null}
  "search": "JBL Speaker"
  ```

  **Array of objects:**

  ```json theme={null}
  "search": [
    { "field": "name", "value": "laptop", "operator": "like" }
  ]
  ```

  See [Search criteria](#search-criteria) below for all supported fields and operators.
</ParamField>

<ParamField body="query" type="object">
  Structured rule-based query builder. Mutually exclusive with `search` — use one or the other. Allows grouping conditions with AND/OR logic across multiple rule sets.

  ```json theme={null}
  {
    "query": {
      "rules_operator": "any",
      "rules": [
        {
          "conditions_operator": "any",
          "conditions": [
            { "field": "name", "operator": "like", "value": "nike air" },
            { "field": "name", "operator": "like", "value": "adidas" }
          ]
        },
        {
          "conditions_operator": "all",
          "conditions": [
            { "field": "category", "operator": "like", "value": "shoes" }
          ]
        }
      ]
    }
  }
  ```

  | Field                           | Type   | Required | Description                                                                     |
  | ------------------------------- | ------ | -------- | ------------------------------------------------------------------------------- |
  | `rules_operator`                | string | No       | How rule groups are combined: `any` (OR) or `all` (AND). Defaults to `all`.     |
  | `rules`                         | array  | No       | Array of rule groups.                                                           |
  | `rules[].conditions_operator`   | string | Yes      | How conditions within the group combine: `any` (OR) or `all` (AND).             |
  | `rules[].conditions`            | array  | Yes      | Array of condition objects.                                                     |
  | `rules[].conditions[].field`    | string | Yes      | Field to filter on. See [Supported search fields](#supported-search-fields).    |
  | `rules[].conditions[].value`    | mixed  | Yes      | Value to match.                                                                 |
  | `rules[].conditions[].operator` | string | Yes      | Comparison operator. Case-insensitive. See [Search criteria](#search-criteria). |

  See [Query builder examples](#query-builder-examples) below.
</ParamField>

<ParamField body="fields" type="array | string">
  Limit which fields are returned. Pass an array of field name strings or a comma-separated string. When omitted, all fields are returned.

  ```json theme={null}
  ["id", "name", "final_price", "urls"]
  ```
</ParamField>

<ParamField body="per_page" type="integer" default="100">
  Number of results per page. Minimum is `1`; maximum depends on your subscription plan.
</ParamField>

<ParamField body="page" type="integer">
  Page number for pagination. Minimum is `1`; maximum depends on your subscription plan.
</ParamField>

<ParamField body="after" type="string">
  Cursor-based pagination token for accessing results beyond 10,000. Available on plans that support deep pagination. Use the `after` value returned in `meta` to fetch the next page.
</ParamField>

<ParamField body="sort_by" type="string">
  Field to sort results by. Accepted values: `relevance`, `id`, `barcode`, `name`, `description`, `commission_url`, `direct_url`, `image_url`, `currency`, `regular_price`, `final_price`, `on_sale`, `sale_discount`, `availability`, `stock_quantity`, `sku`, `brand`, `category`, `network`, `merchant`, `updated_at`, `started_at`.
</ParamField>

<ParamField body="sort_order" type="string">
  Sort direction. Accepted values: `asc`, `desc`.
</ParamField>

<ParamField body="networks" type="object">
  Network-specific configurations for affiliate link generation. When you omit this parameter, `commission_url` values contain `@@@` and `###` as placeholders that you replace with your affiliate ID and sub-ID manually. When you provide it, the API substitutes your IDs automatically.

  The key is the network ID as a string. Most networks require `affiliate_id`. The following networks require additional fields:

  | Network          | Extra required fields                             |
  | ---------------- | ------------------------------------------------- |
  | Adservice        | `mid`                                             |
  | AffiliateGateway | `site_id`                                         |
  | Belboon          | `adspace_id`                                      |
  | Effiliation      | `api_key`                                         |
  | Partnerize       | `application_key`, `user_api_key`, `publisher_id` |

  ```json theme={null}
  {
    "networks": {
      "329": {
        "affiliate_id": "your_affiliate_id",
        "sub_id": "your_sub_id"
      }
    }
  }
  ```
</ParamField>

<ParamField body="config" type="object">
  Optional configurations for supported third-party services. Each key is a service identifier and maps to a service-specific config object.

  **Shopnomix** — pass your `campaign_id` to have the API populate `urls.shopnomix` with a ready-to-use Shopnomix link:

  ```json theme={null}
  {
    "config": {
      "shopnomix": {
        "campaign_id": 12345678910
      }
    }
  }
  ```
</ParamField>

<ParamField body="pool_id" type="string">
  ULID of a pool belonging to the authenticated team. The pool's networks and merchants are combined with any explicitly passed filter values. Only one `pool_id` may be passed per request. Returns `422` if the pool does not exist or belongs to another team.
</ParamField>

<ParamField body="facets" type="string[]">
  Array of facets to include in the response. Returns aggregated network and merchant statistics alongside your results. Supports dot notation for specific sub-fields.

  Must be an **array of strings** (max 20 items). Passing a comma-separated string returns `422` (`The facets must be an array.`).

  Base facets: `network`, `merchant`, `final_price`. Dot notation is supported for sub-fields, e.g. `network.name`, `network.logo_url`, `merchant.product_count`, `final_price.min`, `final_price.max`.

  ```
  "facets": ["network", "merchant"]
  ```
</ParamField>

<ParamField body="duplicate_fields_to_exclude" type="string">
  Remove duplicate results based on field values. Two syntaxes are available:

  **Comma syntax** — fields are applied independently. Append `[N]` to cap results per unique value.

  ```
  "duplicate_fields_to_exclude": "name,merchant.id[10]"
  ```

  This keeps up to 10 products per merchant and also deduplicates by name.

  **OR syntax** — drop a result if *either* field has already appeared.

  ```
  "duplicate_fields_to_exclude": "merchant.id||name"
  ```

  This guarantees each merchant appears at most once *and* each product name appears at most once.

  **Rules for OR syntax:**

  * At most 2 fields per `||` group.
  * `[N]` per-value limits are not supported inside a `||` group.
  * Cannot be mixed with comma syntax in the same request.
  * Invalid combinations return `422` with a descriptive message.
  * `total` in the response is an estimated upper bound; the returned page may occasionally contain fewer items.

  Supported fields: `name`, `image_url`, `direct_url`, `barcode`, `merchant.id`.
</ParamField>

<ParamField body="balanced_mix" type="object">
  Advanced result balancing with round-robin interleaving and optional weighting. Use this to prevent high-volume merchants from dominating results.

  <Warning>
    `balanced_mix` and `duplicate_fields_to_exclude` cannot be used together. Use one or the other.
  </Warning>

  | Field           | Type    | Required | Description                                                                                           |
  | --------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------- |
  | `field`         | string  | Yes      | Field to balance by (e.g., `merchant.id`, `brand`)                                                    |
  | `max_per_value` | integer | Yes      | Maximum results per unique field value                                                                |
  | `interleave`    | boolean | No       | Distribute results round-robin across values (default: `false`)                                       |
  | `weights`       | object  | No       | Weight multipliers per value. Format: `{"value_id": multiplier}`. Unspecified values default to `1.0` |

  ```json theme={null}
  {
    "balanced_mix": {
      "field": "merchant.id",
      "max_per_value": 5,
      "interleave": true,
      "weights": {
        "54419": 2.0,
        "41357": 0.5
      }
    }
  }
  ```
</ParamField>

<ParamField body="click_tracking" type="boolean" default="false">
  When `true`, replaces your sub-ID with a `click_id` to enable consolidated click reporting.
</ParamField>

### `balanced_mix` vs `duplicate_fields_to_exclude`

| Feature                    | `duplicate_fields_to_exclude`              | `balanced_mix`            |
| -------------------------- | ------------------------------------------ | ------------------------- |
| Limit per value            | Yes — `field[N]` syntax (comma mode only)  | Yes — `max_per_value`     |
| OR-style multi-field dedup | Yes — `field1\|\|field2` (no `[N]` limits) | No                        |
| Comma-separated fields     | Yes (independent dedup per field)          | No — single field only    |
| Round-robin interleaving   | No                                         | Yes — `interleave: true`  |
| Weighted priorities        | No                                         | Yes — `weights`           |
| Best for                   | Simple deduplication                       | Advanced result diversity |

## Search criteria

The `search` parameter accepts either a plain string or an array of filter objects. Each object in the array specifies a `field`, `value`, and `operator`.

```json theme={null}
{
  "field": "name",
  "value": "wireless headphones",
  "operator": "LIKE"
}
```

**Multiple values:** Use `||` as a logical OR separator within the `value` string.

```json theme={null}
{ "field": "currency", "value": "USD||GBP||EUR", "operator": "=" }
```

<Note>
  To AND values, create separate filter objects in the array — each object is combined with AND logic.
</Note>

**Omitted operators** default to `=`.

**Case sensitivity:** Most fields are case-insensitive. The following fields are case-sensitive: `barcode`, `sku`, `mpn`, `asin`.

### Supported search fields

| Field                   | Operators                       | Notes                                                                                               |
| ----------------------- | ------------------------------- | --------------------------------------------------------------------------------------------------- |
| `id`                    | `=`, `!=`                       |                                                                                                     |
| `any`                   | `LIKE`                          | Searches name, description, barcode, brand, category, tags, SKU, ASIN, and more. Supports stemming. |
| `barcode`               | `=`, `!=`                       | Case-sensitive                                                                                      |
| `sku`                   | `=`, `!=`, `LIKE`               | Case-sensitive                                                                                      |
| `network.id`            | `=`, `!=`                       |                                                                                                     |
| `merchant.id`           | `=`, `!=`                       |                                                                                                     |
| `network.name`          | `=`, `!=`, `LIKE`, `NOT LIKE`   |                                                                                                     |
| `merchant.name`         | `=`, `!=`, `LIKE`, `NOT LIKE`   |                                                                                                     |
| `name`                  | `=`, `!=`, `LIKE`, `NOT LIKE`   |                                                                                                     |
| `description`           | `LIKE`, `NOT LIKE`              |                                                                                                     |
| `direct_url`            | `LIKE`, `=`, `NOT NULL`         | Supports domain-only (e.g., `www.apple.com`) or full product URLs                                   |
| `image_url`             | `=`, `!=`                       |                                                                                                     |
| `commission_url`        | `=`, `!=`                       |                                                                                                     |
| `currency`              | `=`, `!=`                       | ISO 4217 codes: USD, EUR, GBP, AUD, CAD, JPY, and more                                              |
| `final_price`           | `=`, `!=`, `>`, `<`, `>=`, `<=` | Float value                                                                                         |
| `regular_price`         | `=`, `!=`, `>`, `<`, `>=`, `<=` | Float value                                                                                         |
| `on_sale`               | `=`                             | `true` or `false`                                                                                   |
| `sale_discount`         | `=`, `!=`, `>`, `<`, `>=`, `<=` | Percentage                                                                                          |
| `availability`          | `=`                             | `InStock`, `OutOfStock`, or `Unknown`                                                               |
| `stock_quantity`        | `=`, `!=`, `>`, `<`, `>=`, `<=` |                                                                                                     |
| `brand`                 | `=`, `!=`, `LIKE`, `NOT LIKE`   |                                                                                                     |
| `category`              | `=`, `!=`, `LIKE`, `NOT LIKE`   |                                                                                                     |
| `color`                 | `=`, `!=`, `LIKE`, `NOT LIKE`   |                                                                                                     |
| `condition`             | `=`, `!=`, `LIKE`, `NOT LIKE`   |                                                                                                     |
| `country`               | `=`, `!=`, `LIKE`, `NOT LIKE`   |                                                                                                     |
| `gender`                | `=`, `!=`, `LIKE`, `NOT LIKE`   |                                                                                                     |
| `genre`                 | `=`, `!=`, `LIKE`, `NOT LIKE`   |                                                                                                     |
| `manufacturer`          | `=`, `!=`, `LIKE`, `NOT LIKE`   |                                                                                                     |
| `model`                 | `=`, `!=`, `LIKE`, `NOT LIKE`   |                                                                                                     |
| `size`                  | `=`, `!=`, `LIKE`, `NOT LIKE`   |                                                                                                     |
| `material`              | `=`, `!=`, `LIKE`, `NOT LIKE`   |                                                                                                     |
| `asin`                  | `=`, `!=`                       | Amazon networks only. Case-sensitive.                                                               |
| `mpn`                   | `=`, `!=`                       | Case-sensitive                                                                                      |
| `ean`                   | `=`, `!=`, `NOT NULL`           |                                                                                                     |
| `gtin`                  | `=`, `!=`, `NOT NULL`           |                                                                                                     |
| `tags`                  | `=`, `!=`, `LIKE`, `NOT LIKE`   |                                                                                                     |
| `publisher`             | `=`, `!=`, `LIKE`, `NOT LIKE`   |                                                                                                     |
| `subtitle`              | `=`, `!=`, `LIKE`, `NOT LIKE`   |                                                                                                     |
| `commissionable_status` | `=`                             | `commissionable`, `assumed_commissionable`, `not_commissionable`                                    |
| `commission_model`      | `=`                             | `CPC`, `CPS`                                                                                        |
| `author`                | `=`, `!=`, `LIKE`, `NOT LIKE`   |                                                                                                     |
| `artist`                | `=`, `!=`, `LIKE`, `NOT LIKE`   |                                                                                                     |
| `seller_party`          | `=`                             | `1st` or `first`, `3rd` or `third`, `unknown`                                                       |
| `started_at`            | `=`, `>`, `<`, `>=`, `<=`, `<>` | `YYYY-MM-DD` format                                                                                 |
| `updated_at`            | `=`, `>`, `<`, `>=`, `<=`, `<>` | `YYYY-MM-DD` format                                                                                 |

## Response

A successful request returns a JSON object with `meta`, an optional `facets` object, and a `data` array of product objects.

### `meta` object

| Field          | Type    | Description                                         |
| -------------- | ------- | --------------------------------------------------- |
| `total`        | integer | Total matching products                             |
| `from`         | integer | Starting index of this page                         |
| `to`           | integer | Ending index of this page                           |
| `current_page` | integer | Current page number                                 |
| `last_page`    | integer | Last available page                                 |
| `per_page`     | integer | Results per page                                    |
| `fields`       | array   | Fields included in each product object              |
| `after`        | string  | Cursor for deep pagination (null if not applicable) |
| `sort_by`      | string  | Active sort field                                   |
| `sort_order`   | string  | Active sort direction                               |
| `trace_id`     | string  | Request trace ID for support use                    |

### `facets` object

Only present when you include the `facets` parameter. Contains aggregated statistics about networks and merchants in your result set.

<Expandable title="networks facet fields">
  | Field                              | Type    | Description                 |
  | ---------------------------------- | ------- | --------------------------- |
  | `networks[].id`                    | integer | Network ID                  |
  | `networks[].name`                  | string  | Network name                |
  | `networks[].url`                   | string  | Network website URL         |
  | `networks[].logo_url`              | string  | Network logo URL            |
  | `networks[].merchant_count`        | integer | Total merchants in network  |
  | `networks[].merchant_count_active` | integer | Active merchants in network |
  | `networks[].product_count`         | integer | Total products in network   |
  | `networks[].group.id`              | integer | Network group ID            |
  | `networks[].group.name`            | string  | Network group name          |
  | `networks[].country.id`            | string  | Two-letter country code     |
  | `networks[].country.iso3`          | string  | Three-letter country code   |
  | `networks[].country.name`          | string  | Country name                |
</Expandable>

<Expandable title="merchants facet fields">
  | Field                          | Type    | Description                           |
  | ------------------------------ | ------- | ------------------------------------- |
  | `merchants[].id`               | integer | Merchant ID                           |
  | `merchants[].name`             | string  | Merchant name                         |
  | `merchants[].description`      | string  | Merchant description                  |
  | `merchants[].domains`          | array   | Merchant website domains              |
  | `merchants[].icon_url`         | string  | Merchant icon URL                     |
  | `merchants[].logo_url`         | string  | Merchant logo URL                     |
  | `merchants[].product_count`    | integer | Products available from this merchant |
  | `merchants[].origin_id`        | string  | Merchant's original network ID        |
  | `merchants[].network.id`       | integer | Network ID                            |
  | `merchants[].network.name`     | string  | Network name                          |
  | `merchants[].network.url`      | string  | Network website URL                   |
  | `merchants[].network.logo_url` | string  | Network logo URL                      |
</Expandable>

### Product object

Each item in the `data` array is a product object. Fields are organized by category below.

#### Core

| Field                   | Type   | Description                                                                                 |
| ----------------------- | ------ | ------------------------------------------------------------------------------------------- |
| `id`                    | string | Unique system-generated product identifier                                                  |
| `barcode`               | string | UPC, EAN, ISBN, or GTIN barcode                                                             |
| `name`                  | string | Product title from the merchant                                                             |
| `description`           | string | Full product description from the merchant                                                  |
| `commissionable_status` | string | Commission eligibility: `commissionable`, `assumed_commissionable`, or `not_commissionable` |

#### URLs

| Field            | Type   | Description                                                                                                                                                                   |
| ---------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `commission_url` | string | Affiliate URL with `@@@` (affiliate ID) and `###` (sub-ID) placeholders. Replace these with your values, or use the `networks` parameter to have the API do it automatically. |
| `direct_url`     | string | Direct unaffiliated merchant URL — no commission is earned from this URL                                                                                                      |
| `image_url`      | string | Primary product image URL                                                                                                                                                     |
| `urls.outclick`  | string | Enhanced tracking URL with dynamic routing via query parameters                                                                                                               |
| `urls.direct`    | string | Direct merchant URL (no tracking)                                                                                                                                             |
| `urls.affiliate` | string | Standard affiliate URL — replace `@@@` and `###`                                                                                                                              |
| `urls.shopnomix` | string | Shopnomix platform URL (where supported)                                                                                                                                      |

**Outclick URL query parameters:**

| Parameter           | Effect                                          |
| ------------------- | ----------------------------------------------- |
| `?format=direct`    | Redirect to direct merchant URL (no commission) |
| `?format=affiliate` | Redirect to affiliate URL (default)             |
| `?format=shopnomix` | Redirect to Shopnomix URL                       |
| `?sub_id=VALUE`     | Override sub-ID for campaign attribution        |

#### Pricing

| Field           | Type    | Description                                        |
| --------------- | ------- | -------------------------------------------------- |
| `currency`      | string  | ISO 4217 currency code (e.g., `USD`, `EUR`, `GBP`) |
| `regular_price` | float   | Original retail price                              |
| `final_price`   | float   | Current price after discounts                      |
| `on_sale`       | boolean | `true` when a discount is active                   |
| `sale_discount` | integer | Discount percentage applied to `regular_price`     |

#### Inventory

| Field            | Type    | Description                                                                  |
| ---------------- | ------- | ---------------------------------------------------------------------------- |
| `availability`   | string  | `InStock`, `OutOfStock`, or `null`                                           |
| `stock_quantity` | integer | Units available. May be `null` if the merchant does not report stock levels. |

#### Identifiers

| Field                 | Type         | Description                                                                              |
| --------------------- | ------------ | ---------------------------------------------------------------------------------------- |
| `mpn`                 | string       | Manufacturer part number (case-sensitive)                                                |
| `sku`                 | string       | Merchant stock-keeping unit (case-sensitive)                                             |
| `identifiers`         | object       | All product identifiers consolidated in one object. Each field is `null` if unavailable. |
| `identifiers.barcode` | string\|null | Primary barcode value.                                                                   |
| `identifiers.ean`     | string\|null | European Article Number.                                                                 |
| `identifiers.gtin`    | string\|null | Global Trade Item Number.                                                                |
| `identifiers.upc`     | string\|null | Universal Product Code.                                                                  |
| `identifiers.isbn`    | string\|null | International Standard Book Number.                                                      |
| `identifiers.mpn`     | string\|null | Manufacturer Part Number.                                                                |
| `identifiers.sku`     | string\|null | Stock Keeping Unit.                                                                      |
| `identifiers.asin`    | string\|null | Amazon Standard Identification Number.                                                   |

#### Attributes

| Field          | Type   | Description                                                           |
| -------------- | ------ | --------------------------------------------------------------------- |
| `brand`        | string | Brand name                                                            |
| `category`     | string | Hierarchical category path (e.g., `Electronics > Audio > Speakers`)   |
| `size`         | string | Size designation or dimensions                                        |
| `color`        | string | Color description                                                     |
| `gender`       | string | Target gender demographic (`null` for non-gender-specific items)      |
| `material`     | string | Primary construction materials                                        |
| `country`      | string | Country of origin                                                     |
| `condition`    | string | Product condition: `new`, `used`, `refurbished`, `open-box`           |
| `seller_party` | string | `first` (sold directly by merchant), `third` (reseller), or `unknown` |

#### Specialized attributes

| Field          | Type   | Description                                |
| -------------- | ------ | ------------------------------------------ |
| `genre`        | string | Genre classification for media products    |
| `manufacturer` | string | Manufacturer name (may differ from brand)  |
| `model`        | string | Model name or number                       |
| `author`       | string | Author (books and educational content)     |
| `artist`       | string | Artist name (music, art, creative content) |
| `tags`         | array  | Descriptive keyword tags                   |

#### Network and merchant

| Field               | Type    | Description                    |
| ------------------- | ------- | ------------------------------ |
| `network.id`        | integer | Affiliate network ID           |
| `network.name`      | string  | Affiliate network display name |
| `network.logo_url`  | string  | Network logo URL               |
| `merchant.id`       | integer | Merchant ID                    |
| `merchant.name`     | string  | Merchant display name          |
| `merchant.logo_url` | string  | Merchant logo URL              |

#### System

| Field        | Type   | Description                                                          |
| ------------ | ------ | -------------------------------------------------------------------- |
| `updated_at` | string | Timestamp when the product was last refreshed from the merchant feed |
| `started_at` | string | Timestamp when the product was first advertised by the merchant      |

## Examples

<CodeGroup>
  ```json 1. Simple search for "iPhone 14" theme={null}
  {
    "search": [
      {
        "field": "any",
        "value": "iPhone 14",
        "operator": "LIKE"
      }
    ],
    "per_page": 20,
    "sort_by": "final_price",
    "sort_order": "asc"
  }
  ```

  ```json 2. Barcode and SKU lookup theme={null}
  {
    "search": [
      {
        "field": "barcode",
        "value": "1234567890123",
        "operator": "="
      }
    ],
    "fields": ["id", "name", "brand", "final_price", "availability", "urls"]
  }
  ```

  ```json 3. Network and merchant specific search theme={null}
  {
    "search": [
      {
        "field": "network.name",
        "value": "Commission Junction||ShareASale",
        "operator": "LIKE"
      },
      {
        "field": "merchant.id",
        "value": "23",
        "operator": "="
      },
      {
        "field": "merchant.id",
        "value": "20",
        "operator": "!="
      },
      {
        "field": "commissionable_status",
        "value": "commissionable"
      }
    ],
    "networks": {
      "456": {
        "affiliate_id": "your_cj_affiliate_id",
        "sub_id": "multi_merchant_campaign"
      },
      "789": {
        "affiliate_id": "your_shareasale_id",
        "sub_id": "multi_merchant_campaign"
      }
    }
  }
  ```

  ```json 4. Advanced pet products search theme={null}
  {
    "page": 2,
    "per_page": 10,
    "sort_by": "final_price",
    "sort_order": "asc",
    "networks": {
      "329": {
        "affiliate_id": "your_affiliate_id_here",
        "sub_id": "pet_products_campaign"
      }
    },
    "search": [
      {
        "field": "name",
        "value": "dog toys || cat toys",
        "operator": "LIKE"
      },
      {
        "field": "on_sale",
        "value": true
      },
      {
        "field": "currency",
        "value": "GBP||EUR",
        "operator": "="
      },
      {
        "field": "brand",
        "value": "CatCo",
        "operator": "NOT LIKE"
      },
      {
        "field": "regular_price",
        "value": "2000",
        "operator": ">"
      },
      {
        "field": "merchant.name",
        "value": "Walmart",
        "operator": "LIKE"
      },
      {
        "field": "network.id",
        "value": "9",
        "operator": "="
      }
    ]
  }
  ```

  ```json 5. Electronics with brand filtering and price range theme={null}
  {
    "search": [
      {
        "field": "any",
        "value": "gaming laptop",
        "operator": "LIKE"
      },
      {
        "field": "final_price",
        "value": "100000",
        "operator": ">"
      },
      {
        "field": "final_price",
        "value": "300000",
        "operator": "<"
      },
      {
        "field": "availability",
        "value": "InStock"
      }
    ],
    "sort_by": "final_price",
    "sort_order": "desc",
    "per_page": 15,
    "networks": {
      "123": {
        "affiliate_id": "tech_affiliate_123",
        "sub_id": "gaming_laptops_q3"
      }
    }
  }
  ```
</CodeGroup>

## Query builder examples

### Multiple brands with exclusion

```json theme={null}
{
  "per_page": 10,
  "pool_id": "01kt72vmxq9f9f1gdkmfekrgxp",
  "sort_by": "relevance",
  "query": {
    "rules_operator": "any",
    "rules": [
      {
        "conditions_operator": "any",
        "conditions": [
          { "field": "name", "operator": "like", "value": "nike air" },
          { "field": "name", "operator": "like", "value": "adidas" }
        ]
      },
      {
        "conditions_operator": "all",
        "conditions": [
          { "field": "name", "operator": "not like", "value": "loafers" }
        ]
      },
      {
        "conditions_operator": "all",
        "conditions": [
          { "field": "category", "operator": "like", "value": "shoes" }
        ]
      }
    ]
  }
}
```

### Brand + price range (AND logic)

```json theme={null}
{
  "per_page": 20,
  "sort_by": "final_price",
  "sort_order": "asc",
  "query": {
    "rules_operator": "all",
    "rules": [
      {
        "conditions_operator": "any",
        "conditions": [
          { "field": "brand", "value": "Nike", "operator": "=" },
          { "field": "brand", "value": "Adidas", "operator": "=" }
        ]
      },
      {
        "conditions_operator": "all",
        "conditions": [
          { "field": "final_price", "value": "5000", "operator": "<=" },
          { "field": "availability", "value": "InStock", "operator": "=" }
        ]
      }
    ]
  }
}
```

## Error codes

| Status                      | Meaning                                                  |
| --------------------------- | -------------------------------------------------------- |
| `400 Bad Request`           | Invalid parameters or malformed request body             |
| `401 Unauthorized`          | Missing or invalid API key                               |
| `403 Forbidden`             | Your API key does not have permission for this operation |
| `429 Too Many Requests`     | Rate limit exceeded — slow down your request rate        |
| `500 Internal Server Error` | Server-side error — retry with exponential backoff       |