> ## 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 /products/omni — unified product search

> Query Amazon and 1B+ affiliate products in one call. Search by ASIN, URL, barcode, or keyword with advanced filtering.

Use `POST /v1/products/omni` to search Amazon and your affiliate product database simultaneously in a single request. Rather than calling the Amazon API and your affiliate database separately and merging the results yourself, this endpoint aggregates both sources and returns a unified response.

## Advantages

* **Single call** — one request retrieves Amazon results and affiliate database results together
* **Flexible criteria** — search by ASIN, product URL, barcode, keyword, or broad `any` field
* **Advanced filtering** — apply precise field-level filters on top of any criteria type
* **Grouped responses** — use `group_by` to receive results organized by each search criteria item

## Request

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

### 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="criteria" type="array" required>
  An array of search criteria objects. Each object specifies a `field` and `value`. Only one criteria type is permitted per query.

  Supported fields: `asin`, `url`, `barcode`, `keyword`, `any`.

  ```json theme={null}
  {
    "criteria": [
      {
        "field": "asin",
        "value": "B07QK2SPP7||B08N5WRWNW"
      }
    ]
  }
  ```

  See [Criteria fields](#criteria-fields) below for details on each option.
</ParamField>

<ParamField body="networks" type="object">
  Network-specific configurations. When omitted, `commission_url` values contain `@@@` and `###` placeholders. When provided, the API substitutes your IDs automatically.

  For Amazon results, provide your Creator API credentials under the `"amazon"` key:

  ```json theme={null}
  {
    "networks": {
      "amazon": {
        "credential_id": "your_amz_credential_id",
        "credential_secret": "your_amz_credential_secret",
        "partner_tag": "your-tag-20",
        "locale": "US"
      },
      "329": {
        "affiliate_id": "your_affiliate_id",
        "sub_id": "your_sub_id"
      }
    }
  }
  ```

  Amazon `locale` maps to the marketplace (e.g., `US`, `GB`, `DE`, `CA`, `JP`). Other networks that 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` |
</ParamField>

<ParamField body="filter" type="array">
  Advanced filtering applied on top of the `criteria` search. Each filter object requires `field`, `operator`, and `value`.

  ```json theme={null}
  {
    "filter": [
      { "field": "availability", "operator": "=", "value": "InStock" },
      { "field": "final_price", "operator": "<=", "value": 10000 }
    ]
  }
  ```

  See [Filter fields and operators](#filter-fields-and-operators) for all supported fields.
</ParamField>

<ParamField body="fields" type="array | string">
  Fields to include in each product object. Pass an array of strings or a comma-separated string.

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

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

<ParamField body="page" type="integer">
  Page number for pagination. Minimum `1`.
</ParamField>

<ParamField body="after" type="string">
  Cursor for deep pagination beyond 10,000 results. Use the `after` value from the previous response's `meta` object.
</ParamField>

<ParamField body="sort_by" type="string">
  Sort field. Accepted values: `relevance`, `id`, `barcode`, `name`, `final_price`, `on_sale`, `regular_price`, `availability`, `stock_quantity`, `brand`, `category`, `updated_at`, `criteria_url`.

  `criteria_url` is a virtual, Omni-only value — it resolves to `relevance` at the query layer, but places the products matched directly off your `url` criteria ahead of the barcode-expansion results. This placement only applies to page 1; page 2 onward returns only the barcode-expansion continuation results.
</ParamField>

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

<ParamField body="group_by" type="string">
  Group results by a criteria index. Use `"criteria.0"` to group by the first (and typically only) criteria item — useful when searching multiple ASINs and wanting results organized per ASIN. Use `"none"` (default) for a flat, ungrouped list.
</ParamField>

<ParamField body="network_ids" type="string[]">
  Explicit list of network IDs to include in results.
</ParamField>

<ParamField body="merchant_ids" type="string[]">
  Explicit list of merchant IDs to include in results.
</ParamField>

<ParamField body="exclude_network_ids" type="string[]">
  Network IDs to exclude from results.
</ParamField>

<ParamField body="exclude_merchant_ids" type="string[]">
  Merchant IDs to exclude from results.
</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="duplicate_fields_to_exclude" type="string">
  Remove duplicate results based on field values. Two syntaxes:

  **Comma (AND)** — each field is applied independently; `[N]` caps results per unique value.

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

  **OR** — drop a result if *either* field has already appeared. At most 2 fields, no `[N]` limits, cannot mix with comma syntax. `total` is an estimated upper bound.

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

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

<ParamField body="facets" type="array">
  Retrieve aggregated statistics about the result set. Supported values: `final_price`, `network`, `merchant`.

  ```json theme={null}
  "facets": ["final_price", "network", "merchant"]
  ```
</ParamField>

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

## Criteria fields

| Field     | Description                                                                                                                                   |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `asin`    | Amazon Standard Identification Number. Up to 10 ASINs per call, separated by `\|\|`. Requires Amazon Creator API credentials in `networks`.   |
| `url`     | Direct product page URL. Supported merchants: Amazon, Target, Walmart, Home Depot, Best Buy.                                                  |
| `barcode` | UPC, EAN, GTIN, or ISBN code. Case-sensitive.                                                                                                 |
| `keyword` | Keyword search across product name, description, and related fields.                                                                          |
| `any`     | Broad search across all indexable fields including name, description, barcode, brand, category, tags, SKU, ASIN, and more. Supports stemming. |

<Note>
  You can pass multiple values to a single criteria using `||` (logical OR), for example `"B07QK2SPP7||B08N5WRWNW"` for ASINs. Case-sensitive fields (barcode, sku, mpn, asin) must match exactly.
</Note>

## Filter fields and operators

The `filter` array supports a rich set of fields and operators for precise result refinement.

| Field                   | Operators                             | Notes                                                                               |
| ----------------------- | ------------------------------------- | ----------------------------------------------------------------------------------- |
| `id`                    | `=`, `!=`                             |                                                                                     |
| `any`                   | `LIKE`                                | Broad search across all indexable fields                                            |
| `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`               |                                                                                     |
| `image_url`             | `=`, `!=`                             |                                                                                     |
| `commission_url`        | `=`, `!=`                             |                                                                                     |
| `currency`              | `=`, `!=`                             | ISO 4217 codes                                                                      |
| `final_price`           | `=`, `!=`, `>`, `<`, `>=`, `<=`, `<>` | Use `<>` with pipe-separated range: `"2000\|15000"`                                 |
| `regular_price`         | `=`, `!=`, `>`, `<`, `>=`, `<=`, `<>` | Use `<>` with pipe-separated range                                                  |
| `on_sale`               | `=`                                   | `true` or `false`                                                                   |
| `sale_discount`         | `=`, `!=`, `>`, `<`, `>=`, `<=`       |                                                                                     |
| `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` | `=`                                   |                                                                                     |
| `commission_model`      | `=`                                   | `CPC`, `CPS`                                                                        |
| `author`                | `=`, `!=`, `LIKE`, `NOT LIKE`         |                                                                                     |
| `artist`                | `=`, `!=`, `LIKE`, `NOT LIKE`         |                                                                                     |
| `seller_party`          | `=`                                   | `1st` or `first`, `3rd` or `third`, `unknown`. Supports `\|\|` for multiple values. |
| `added_at`              | `=`, `!=`, `>`, `<`, `>=`, `<=`, `<>` | `YYYY-MM-DD` format                                                                 |
| `updated_at`            | `=`, `!=`, `>`, `<`, `>=`, `<=`, `<>` | `YYYY-MM-DD` format                                                                 |

**Operator reference:**

| Operator   | Meaning                                                   |
| ---------- | --------------------------------------------------------- |
| `=`        | Exact match                                               |
| `!=`       | Not equal                                                 |
| `LIKE`     | Contains (partial match, case-insensitive unless noted)   |
| `NOT LIKE` | Does not contain                                          |
| `>`        | Greater than                                              |
| `<`        | Less than                                                 |
| `>=`       | Greater than or equal to                                  |
| `<=`       | Less than or equal to                                     |
| `<>`       | Between — use pipe-separated range value: `"2000\|15000"` |
| `NOT NULL` | Field has a value                                         |

## Response

A successful request returns `meta`, an optional `facets` object, a `data` array, and a `links` object.

### `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                     |
| `facets`       | array   | Facets requested (only present when facets were requested) |
| `after`        | string  | Deep pagination cursor                                     |
| `sort_by`      | string  | Active sort field                                          |
| `sort_order`   | string  | Active sort direction                                      |
| `group_by`     | string  | Grouping method applied (`none` or `criteria.{index}`)     |
| `trace_id`     | string  | Request trace ID for support use                           |

### `facets` object

Only present when you include the `facets` parameter.

| Field                     | Type   | Description                                                                       |
| ------------------------- | ------ | --------------------------------------------------------------------------------- |
| `facets.final_prices.min` | number | Lowest `final_price` in the result set                                            |
| `facets.final_prices.max` | number | Highest `final_price` in the result set                                           |
| `facets.networks`         | array  | Networks in results with `id`, `name`, and `product_count`                        |
| `facets.merchants`        | array  | Merchants in results with `id`, `name`, `product_count`, and associated `network` |

Use `final_prices` to drive price range sliders. Use `networks` and `merchants` to build filter checkbox lists showing only options that have matching results.

### `data` array

When `group_by` is `"none"` (default), `data` is a flat array of product objects identical in structure to the `/v1/products` search response, with the addition of `added_at`.

When `group_by` is `"criteria.0"`, each item in `data` has this shape:

```json theme={null}
{
  "criterion": {
    "field": "asin",
    "value": "B07QK2SPP7"
  },
  "results": [
    { "id": "AZN-B07QK2SPP7", "name": "...", "final_price": 89.95 }
  ]
}
```

### `links` object

| Field   | Type   | Description                                 |
| ------- | ------ | ------------------------------------------- |
| `self`  | string | Current request URL                         |
| `first` | string | URL of the first page                       |
| `prev`  | string | URL of the previous page (`null` on page 1) |
| `next`  | string | URL of the next page (`null` on last page)  |

### Product object

Product objects contain the same fields as the `/v1/products` response, plus one additional field:

| Field                 | Type         | Description                                                                              |
| --------------------- | ------------ | ---------------------------------------------------------------------------------------- |
| `added_at`            | string       | Timestamp when the product was first added to the system                                 |
| `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.                                                   |

## Amazon ASIN limitations

* Maximum **10 ASINs** per request (use `||` to separate them in the `value` string)
* Amazon results require **Creator API credentials** in the `networks` object under the `"amazon"` key
* For watches, include `start_value` in the criteria object

## Examples

<CodeGroup>
  ```json 1. Amazon ASIN lookup with Creator API credentials theme={null}
  {
    "fields": ["id", "name", "brand", "final_price", "commission_url", "urls", "availability"],
    "per_page": 10,
    "networks": {
      "amazon": {
        "credential_id": "your_amz_credential_id",
        "credential_secret": "your_amz_credential_secret",
        "partner_tag": "mytag-20",
        "locale": "US"
      }
    },
    "criteria": [
      {
        "field": "asin",
        "value": "B07QK2SPP7||B08N5WRWNW||B09JBQZPX8"
      }
    ],
    "sort_by": "final_price",
    "sort_order": "asc"
  }
  ```

  ```json 2. URL-based product lookup with filters theme={null}
  {
    "criteria": [
      {
        "field": "url",
        "value": "https://www.amazon.com/dp/B07QK2SPP7"
      }
    ],
    "filter": [
      {
        "field": "currency",
        "operator": "=",
        "value": "USD"
      },
      {
        "field": "availability",
        "operator": "=",
        "value": "InStock"
      }
    ],
    "networks": {
      "amazon": {
        "credential_id": "your_amz_credential_id",
        "credential_secret": "your_amz_credential_secret",
        "partner_tag": "your_amz_partner_tag",
        "locale": "US"
      }
    },
    "sort_by": "final_price",
    "sort_order": "asc"
  }
  ```

  ```json 3. Advanced filtering with price range (between operator) theme={null}
  {
    "criteria": [
      {
        "field": "any",
        "value": "bluetooth speaker"
      }
    ],
    "filter": [
      {
        "field": "final_price",
        "operator": "<>",
        "value": "2000|15000"
      },
      {
        "field": "brand",
        "operator": "LIKE",
        "value": "JBL"
      },
      {
        "field": "availability",
        "operator": "=",
        "value": "InStock"
      },
      {
        "field": "on_sale",
        "operator": "=",
        "value": true
      }
    ],
    "fields": ["id", "name", "brand", "final_price", "regular_price", "sale_discount", "urls", "merchant.name"],
    "sort_by": "final_price",
    "sort_order": "asc",
    "per_page": 20
  }
  ```

  ```json 4. Grouping results by criteria (multiple ASINs) theme={null}
  {
    "fields": "id,name,final_price,direct_url,image_url",
    "group_by": "criteria.0",
    "networks": {
      "amazon": {
        "credential_id": "your_amz_credential_id",
        "credential_secret": "your_amz_credential_secret",
        "partner_tag": "your_amz_partner_tag",
        "locale": "US"
      }
    },
    "criteria": [
      {
        "field": "asin",
        "value": "B096N66GHN||B0BGH753WB||B0B4X42BN6"
      }
    ]
  }
  ```

  ```json 5. Filtering by seller_party (first party vs third party) theme={null}
  {
    "criteria": [
      {
        "field": "any",
        "value": "laptop"
      }
    ],
    "filter": [
      {
        "field": "seller_party",
        "operator": "=",
        "value": "1st||unknown"
      },
      {
        "field": "merchant.name",
        "operator": "LIKE",
        "value": "best buy||walmart"
      }
    ],
    "fields": ["id", "name", "merchant", "seller_party", "final_price", "urls"],
    "sort_by": "final_price",
    "sort_order": "asc",
    "per_page": 100
  }
  ```

  ```json 7. Using facets for dynamic filtering theme={null}
  {
    "criteria": [
      {
        "field": "any",
        "value": "laptop"
      }
    ],
    "facets": ["final_price", "network", "merchant"],
    "filter": [
      {
        "field": "availability",
        "operator": "=",
        "value": "InStock"
      }
    ],
    "fields": ["id", "name", "brand", "final_price", "merchant", "network"],
    "sort_by": "final_price",
    "sort_order": "asc",
    "per_page": 50
  }
  ```
</CodeGroup>

## Error codes

| Status                      | Meaning                                                            |
| --------------------------- | ------------------------------------------------------------------ |
| `400 Bad Request`           | Invalid parameters, malformed request, or invalid filter operators |
| `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                 |