POST /products/omni — unified product search

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

string

required

Must be application/json.

string

required

Your API key as a Bearer token: Bearer {your_api_key}.

Body parameters

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.

{
  "criteria": [
    {
      "field": "asin",
      "value": "B07QK2SPP7||B08N5WRWNW"
    }
  ]
}

See Criteria fields below for details on each option.

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:

{
  "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`

array

Advanced filtering applied on top of the criteria search. Each filter object requires field, operator, and value.

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

See Filter fields and operators for all supported fields.

array | string

Fields to include in each product object. Pass an array of strings or a comma-separated string.

["id", "name", "final_price", "urls", "merchant"]

integer

default:"100"

Results per page. Minimum 1; maximum depends on your subscription plan.

integer

Page number for pagination. Minimum 1.

string

Cursor for deep pagination beyond 10,000 results. Use the after value from the previous response’s meta object.

boolean

default:"false"

By default, meta.total does not count past 10,000 matches — if there are more, it reports 10000. Set to true for the precise count instead; this runs an extra query, so expect a bit of added latency.

string

Sort field. Accepted values: relevance, criteria_url, barcode, ean, gtin, name, currency, regular_price, final_price, sale_discount, stock_quantity, brand, category, network.name, merchant.name. Any other value returns 422.Omni’s sortable set is narrower than the one on POST /v1/products. These values are accepted there but return 422 here: id, upc, isbn, asin, commissionable_status, color, gender, size, author, network.id, merchant.id, added_at, updated_at. Use the .name form of the relationship sorts, not .id.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.

string

Sort direction: asc or desc.

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.

string[]

Explicit list of network IDs to include in results.

string[]

Explicit list of merchant IDs to include in results.

string[]

Network IDs to exclude from results.

string[]

Merchant IDs to exclude from results.

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:

{
  "config": {
    "shopnomix": {
      "campaign_id": 12345678910
    }
  }
}

string

Bare ULID of a pool belonging to the authenticated team (the pool_-prefixed form returns 422). 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.

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.

array

Retrieve aggregated statistics about the result set. Supported values: final_price, network, merchant.

"facets": ["final_price", "network", "merchant"]

boolean

default:"false"

When true, replaces your sub-ID with a click_id for consolidated reporting.

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. A pasted barcode, ASIN, SKU, or MPN is also matched exactly against its identifier field (ASIN matching is case-insensitive; barcode, SKU, and MPN are case-sensitive). Supports stemming.

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.

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. By default this does not count past 10,000 — if there are more matches, it reports `10000`. Send `exact_total: true` in the request for the precise count.
`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. Sized to your plan’s pagination limit (10,000 results by default), not to `total` — so once `total` exceeds that limit, `last_page` stops short of `total ÷ per_page`. See `after` above for paging past the limit on plans that support it.
`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, returned as you sent it.
`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

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:

{
  "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

{
  "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"
}

{
  "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"
}

{
  "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
}

{
  "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"
    }
  ]
}

{
  "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
}

{
  "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
}

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

Account

Networks

Merchants

Products

Tools

Watches

Product Lists

Pools

Reports

POST /products/omni — unified product search

Advantages

Request

Headers

Body parameters

Criteria fields

Filter fields and operators

Response

`meta` object

`facets` object

`data` array

`links` object

Product object

Amazon ASIN limitations

Examples

Error codes

​Advantages

​Request

​Headers

​Body parameters

​Criteria fields

​Filter fields and operators

​Response

​meta object

​facets object

​data array

​links object

​Product object

​Amazon ASIN limitations

​Examples

​Error codes

Advantages

Request

Headers

Body parameters

Criteria fields

Filter fields and operators

Response

`meta` object

`facets` object

`data` array

`links` object

Product object

Amazon ASIN limitations

Examples

Error codes