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.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
Body parameters
Search criteria for products. Mutually exclusive with Array of objects:See Search criteria below for all supported fields and operators.
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: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.
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.Number of results per page. Minimum is
1; maximum depends on your subscription plan.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.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.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.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.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: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: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.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.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.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.Remove duplicate results based on field values. Two syntaxes are available:Comma syntax — fields are applied independently. Append 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:
[N] to cap results per unique value.- 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
422with a descriptive message. totalin the response is an estimated upper bound; the returned page may occasionally contain fewer items.
name, image_url, direct_url, barcode, merchant.id.Advanced result balancing with round-robin interleaving and optional weighting. Use this to prevent high-volume merchants from dominating results.
When
true, replaces your sub-ID with a click_id to enable consolidated click reporting.balanced_mix vs duplicate_fields_to_exclude
Search criteria
Thesearch parameter accepts either a plain string or an array of filter objects. Each object in the array specifies a field, value, and operator.
|| 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.
=.
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:
= 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); themerchant. 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 withmeta, 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 thedata 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.