Skip to main content
Access to individual endpoints can be restricted per account. If a request to this endpoint returns 403 with error code endpoint_not_enabled and you expect to have access, contact your account representative.
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 to build and test queries in your browser.

Request

Endpoint: POST /v1/products

Headers

string
required
Must be application/json.
string
required
Your API key as a Bearer token: Bearer {your_api_key}.

Body parameters

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:
Array of objects:
See Search criteria below for all supported fields and operators.
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.
See Query builder examples below.
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. identifiers is not a valid field name (it returns 422); request barcode instead, or omit fields to receive the full identifiers object.
integer
default:"100"
Number of results per page. Minimum is 1; maximum depends on your subscription plan.
integer
Page number for pagination. Minimum is 1; maximum depends on your subscription plan.
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.
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
Field to sort results by. Accepted values: relevance, id, barcode, ean, gtin, upc, isbn, asin, name, currency, regular_price, final_price, sale_discount, stock_quantity, commissionable_status, brand, category, color, gender, size, author, network.id, network.name, merchant.id, merchant.name, added_at, updated_at. Any other value returns 422.Not every searchable field is sortable. description, sku, mpn, on_sale, availability, material, condition, model, commission_model, and the URL fields (commission_url, direct_url, image_url) can be searched and filtered on but cannot be sorted by.Use the dotted forms network.name and merchant.name — bare network and merchant are rejected.
string
Sort direction. Accepted values: asc, desc.
Text sorts (color, gender, size, author, brand, category, name) order by the raw merchant-supplied value and are case-sensitive, so they suit stable pagination better than presentation. Products with no value for the sort field are kept in the results and sort last in both directions.
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:
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:
string
ID of a pool belonging to the authenticated team, with or without the pool_ prefix. The pool’s networks and merchants are searched together with any network_ids or merchant_ids you pass, so those add merchants to the pool for that request. Only one pool_id may be passed per request. Returns 422 if the pool does not exist or belongs to another team, and 404 if the pool has been deleted.Platform accounts: when pool_id is omitted, the search runs against your team’s default pool. If the team has no default pool, the request returns 422 unless you pass search_all. A merchant.id condition inside search only narrows results within the pool.
string | string[]
Leave out products that carry restricted content. Pass one value, a comma-separated list ("sexual,alcohol"), or an array. Values are flag names (sexual, adult_media, alcohol, weapons, tobacco, cannabis, drugs) or a group (restricted, mature). Nothing is filtered unless you send this. An unknown value returns 422 and lists the allowed ones. See Restricted content.
boolean
Platform accounts only, and only when enabled for your account. Searches the whole catalog instead of a pool; any pool_id is ignored. Returns 422 if your account isn’t allowed to use it.
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.
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.
This keeps up to 10 products per merchant and also deduplicates by name.OR syntax — drop a result if either field has already appeared.
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.
object
Advanced result balancing with round-robin interleaving and optional weighting. Use this to prevent high-volume merchants from dominating results.
balanced_mix and duplicate_fields_to_exclude cannot be used together. Use one or the other.
boolean
default:"false"
When true, replaces your sub-ID with a click_id to enable consolidated click reporting.

balanced_mix vs duplicate_fields_to_exclude

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.
Multiple values: Use || as a logical OR separator within the value string.
To AND values, create separate filter objects in the array — each object is combined with AND logic.
Omitted operators default to =. Case sensitivity: Most fields are case-insensitive. The following fields are case-sensitive: barcode, sku, mpn, asin.

Supported search fields

Merchant filters

Filter products by the store that sells them. brand = Nike asks whether the item listing names Nike as its brand. merchant.brand = Nike asks whether the store sells Nike, and returns everything it carries, Nike or not. Use || to pass several values, and combine fields by adding separate filter objects.

Restricted content

Products can carry one or more flags, so you can keep restricted content out of your results. Nothing is filtered unless you ask. Two groups save you listing flags: restricted is every flag above, and mature is sexual plus adult_media. Lingerie and underwear are not flagged. Flags are a best-effort screen based on a product’s name, category and, for some terms, its description, plus stores that specialize in a flagged category. They reduce restricted content but do not guarantee its absence. The simplest form is the top-level exclude_flags parameter:
The same filter works as a search criterion, for use inside your own rules. Use = to return only flagged products:
merchant.flags asks about the store rather than the product. It drops a specialist shop wholesale, but will not remove a flagged product sold by a general marketplace. Use flags to filter a catalog.

Product fields vs. merchant filters

Some attributes exist on both the product and the merchant. The product field matches the individual listing (narrower); the merchant. filter matches the store that sells it (wider). To restrict results to a market, use merchant.countries_market.

Response

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

meta object

facets object

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

Product object

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

Core

URLs

Using urls.outclick isn’t required — direct, affiliate, and shopnomix all work as standalone links — but it’s the only one of the four that Affiliate.com records a click for, so it’s strongly recommended whenever you want that click to appear in your reporting. Outclick URL query parameters: Omitting ?format= follows your pool’s outclick priority setting (outclick_provider_order — see Pool Settings): the first provider in that order able to carry the click wins. The network link can always carry it, so by default a plain outclick uses the affiliate link, not Shopnomix.

Pricing

Inventory

Identifiers

Attributes

Specialized attributes

Network and merchant

System

Examples

Query builder examples

Multiple brands with exclusion

Brand + price range (AND logic)

Error codes