POST /v1/products — search affiliate products

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

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:

"search": "JBL Speaker"

Array of objects:

"search": [
  { "field": "name", "value": "laptop", "operator": "like" }
]

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.

{
  "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.
`rules[].conditions[].value`	mixed	Yes	Value to match.
`rules[].conditions[].operator`	string	Yes	Comparison operator. Case-insensitive. See Search criteria.

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.

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

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.

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.

string

Sort direction. Accepted values: asc, desc.

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`

{
  "networks": {
    "329": {
      "affiliate_id": "your_affiliate_id",
      "sub_id": "your_sub_id"
    }
  }
}

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

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.

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

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.

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.

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`

{
  "balanced_mix": {
    "field": "merchant.id",
    "max_per_value": 5,
    "interleave": true,
    "weights": {
      "54419": 2.0,
      "41357": 0.5
    }
  }
}

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`

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.

{
  "field": "name",
  "value": "wireless headphones",
  "operator": "LIKE"
}

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

{ "field": "currency", "value": "USD||GBP||EUR", "operator": "=" }

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

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

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

Show 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

Show 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

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

{
  "search": [
    {
      "field": "any",
      "value": "iPhone 14",
      "operator": "LIKE"
    }
  ],
  "per_page": 20,
  "sort_by": "final_price",
  "sort_order": "asc"
}

{
  "search": [
    {
      "field": "barcode",
      "value": "1234567890123",
      "operator": "="
    }
  ],
  "fields": ["id", "name", "brand", "final_price", "availability", "urls"]
}

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

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

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

Query builder examples

Multiple brands with exclusion

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

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

Account

Networks

Merchants

Products

Tools

Watches

Product Lists

Pools

Reports

POST /v1/products — search affiliate products

Query builder

Request

Headers

Body parameters

`balanced_mix` vs `duplicate_fields_to_exclude`

Search criteria

Supported search fields

Response

`meta` object

`facets` object

Product object

Core

URLs

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

​Query builder

​Request

​Headers

​Body parameters

​balanced_mix vs duplicate_fields_to_exclude

​Search criteria

​Supported search fields

​Response

​meta object

​facets object

​Product object

​Core

​URLs

​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

Query builder

Request

Headers

Body parameters

`balanced_mix` vs `duplicate_fields_to_exclude`

Search criteria

Supported search fields

Response

`meta` object

`facets` object

Product object

Core

URLs

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