# Affiliate.com API — Full Documentation

Affiliate.com aggregates and normalizes product data from 30+ affiliate networks and tens of thousands of merchant programs into a single searchable API — over a billion products, consistently structured across identifiers (barcode/SKU/MPN), pricing, inventory, and commission fields.

The REST API is organized around products (search, plus a unified cross-network Omni search), networks, merchants, identifier-conversion tools, product watches (webhook-based price/stock alerts), product lists (saved collections), and pools (reusable network+merchant scopes). Authenticate with a bearer token generated at Settings > API Keys (team-scoped, shared rate limit); all endpoints live under https://api.affiliate.com. An MCP server is also available for AI agents, exposing a read/search + identifier-conversion subset of this API.

---

## Agentic commerce

- [Affiliate.com agent storefront](https://zeroclick.affiliate.com/llms.txt): AI agents can purchase from Affiliate.com autonomously or with their human's approval through ZeroClick. Agents without a payment method can set one up on the spot.
  Complete purchasing guide: https://zeroclick.affiliate.com/llms-full.txt - live pricing: https://zeroclick.affiliate.com/manifest.json

---

## Getting Started

---

# Affiliate.com API overview and getting started guide

Source: https://guides.affiliate.com/introduction.md

> ## 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.

# Affiliate.com API overview and getting started guide

> The Affiliate.com API gives you programmatic access to over a billion affiliate products across hundreds of networks and merchants worldwide.

The Affiliate.com API is a REST API that lets you search and retrieve affiliate product data from networks like Impact, Rakuten, Awin, and many more. You can search products, set price-drop watches, build curated product lists, and convert identifiers — all from a single API key.

All API requests go to the base URL:

```
https://api.affiliate.com
```

The API only accepts HTTPS connections. HTTP requests receive an HTTP 301 redirect to the equivalent HTTPS resource. All responses are JSON.

## Get your API token

To make requests, you need an API token. You can create one at [app.affiliate.com](https://app.affiliate.com/).

<Steps>
  <Step title="Sign in to app.affiliate.com">
    Go to [app.affiliate.com](https://app.affiliate.com/) and sign in to your account.
  </Step>

  <Step title="Open API Keys">
    In the left sidebar, click **API Keys** under the Settings section.
  </Step>

  <Step title="Create a key">
    Click **+ Create API Key**, give it a name, and copy it somewhere safe — you won't be able to view it again.
  </Step>

  <Step title="Add the token to your requests">
    Include the token in the `Authorization` header of every API request:

    ```http theme={null}
    Authorization: Bearer YOUR_API_TOKEN
    ```
  </Step>

  <Step title="Make your first request">
    Try listing available networks to confirm your token works:

    ```http theme={null}
    GET https://api.affiliate.com/v1/networks
    Authorization: Bearer YOUR_API_TOKEN
    ```
  </Step>
</Steps>

## Key capabilities

| Capability | Description |
| - | - |
| **Product search** | Search over a billion products across affiliate networks with filtering, sorting, and faceted results |
| **Watches** | Monitor specific products for price changes or availability updates and receive notifications |
| **Lists** | Create and manage curated collections of affiliate products |
| **Conversion tools** | Convert between product identifiers — barcodes, SKUs, ASINs, and more |
| **Networks & merchants** | Browse and filter the affiliate networks and merchants available in the platform |

## Common parameters

These parameters are available on all list endpoints:

| Parameter | Type | Default | Description |
| - | - | - | - |
| `fields` | string | — | Comma-separated list of fields to include in the response |
| `page` | integer | `1` | Page number to retrieve |
| `per_page` | integer | `100` | Number of items per page |

## Response codes

| Code | Meaning |
| - | - |
| `200` | Request succeeded |
| `401` | Missing, malformed, or invalid API token |
| `422` | Usage limit exceeded for your subscription plan |
| `429` | Rate limit exceeded — too many requests per minute |
| `503` | Unexpected traffic spike; the server is usually back within five minutes |

## Rate limits

Rate limits are enforced per API key and measured in requests per minute. Your specific limit depends on your subscription plan. If you exceed the per-minute limit, you receive an `HTTP 429` response. If you exceed your plan's total usage limit, you receive an `HTTP 422` response.

If you receive an `HTTP 503`, wait a few minutes before retrying. For persistent `5XX` errors, contact support at [support@affiliate.com](mailto:support@affiliate.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.

---

# Authenticate your requests to the Affiliate.com API

Source: https://guides.affiliate.com/authentication.md

> ## 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.

# Authenticate your requests to the Affiliate.com API

> Create an API token at app.affiliate.com and include it as a Bearer token in the Authorization header on every API request you make.

Every request to the Affiliate.com API must include an API token. You create and manage tokens at [app.affiliate.com](https://app.affiliate.com/). Tokens are scoped to your team account, so all members of your team share the same rate limits.

## Pass your token

Include your token in the `Authorization` header as a Bearer token:

```http theme={null}
Authorization: Bearer YOUR_API_TOKEN
```

For example, a complete request looks like this:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://api.affiliate.com/v1/networks \
    -H "Authorization: Bearer YOUR_API_TOKEN"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.affiliate.com/v1/networks', {
    headers: {
      'Authorization': 'Bearer YOUR_API_TOKEN'
    }
  });
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.affiliate.com/v1/networks',
      headers={'Authorization': 'Bearer YOUR_API_TOKEN'}
  )
  ```
</CodeGroup>

<Warning>
  Keep your API token secure. Never expose it in client-side code, browser-accessible JavaScript, or public code repositories. If a token is compromised, rotate it immediately from [app.affiliate.com](https://app.affiliate.com/).
</Warning>

## Authentication errors

If your token is missing, malformed, or invalid, the API returns:

```
HTTP 401 Unauthorized
```

Check that you're including the `Authorization` header and that the token value is correct.

## Rate limit errors

| Code | Cause |
| - | - |
| `429 Too Many Requests` | You exceeded the requests-per-minute limit for your API key |
| `422 Unprocessable Entity` | You exceeded the total usage limit for your subscription plan |

Rate limits are measured per API key. Your per-minute limit depends on your subscription. If you receive a `429`, wait before retrying. If you receive a `422`, you've exhausted your plan's request quota.

## Network-specific credentials

Some affiliate networks require additional parameters beyond your API token to return affiliate links. You supply these inside the `networks` object when calling the product search endpoint. If you provide a network object but omit required fields, the API returns a `422` error listing the missing items.

| Network | Required parameter(s) |
| - | - |
| Adservice | `mid` |
| The Affiliate Gateway | `sid` |
| Belboon | `adspace_id` |
| Effiliation | `api_key` |
| Partnerize | `application_key`, `user_api_key`, `publisher_id` |

Here's how to supply network credentials in a product search request:

<CodeGroup>
  ```json Adservice theme={null}
  {
    "networks": {
      "1200": {
        "affiliate_id": "your_affiliate_id",
        "sub_id": "your_sub_id",
        "mid": "your_mid"
      }
    }
  }
  ```

  ```json The Affiliate Gateway theme={null}
  {
    "networks": {
      "650": {
        "affiliate_id": "your_affiliate_id",
        "sub_id": "your_sub_id",
        "sid": "your_site_id"
      }
    }
  }
  ```

  ```json Belboon theme={null}
  {
    "networks": {
      "253": {
        "affiliate_id": "your_affiliate_id",
        "sub_id": "your_sub_id",
        "adspace_id": "your_adspace_id"
      }
    }
  }
  ```

  ```json Effiliation theme={null}
  {
    "networks": {
      "805": {
        "affiliate_id": "your_affiliate_id",
        "sub_id": "your_sub_id",
        "api_key": "your_api_key"
      }
    }
  }
  ```

  ```json Partnerize theme={null}
  {
    "networks": {
      "811": {
        "affiliate_id": "your_affiliate_id",
        "sub_id": "your_sub_id",
        "application_key": "your_application_key",
        "user_api_key": "your_user_api_key",
        "publisher_id": "your_publisher_id"
      }
    }
  }
  ```
</CodeGroup>

For most other networks, you only need to supply `affiliate_id` and optionally `sub_id`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.

---

# Your First Request

Source: https://guides.affiliate.com/first-request.md

> ## 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.

# Your First Request

> Make your first API request to search products and get affiliate links.

With your API token ready, let's make your first request: searching for products.

## Search for Products

Search products using POST with a search query.  In this example we will search the recommended "any" field,  which will compare the value to *any* text field including 'name', 'description', 'category', 'merchant' and 'brand'.

```bash theme={null}
curl -X POST https://api.affiliate.com/v1/products \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "search": [
      {"field": "any", "value": "wireless headphones", "operator": "LIKE"}
    ]
  }'
```

```javascript theme={null}
const response = await fetch('https://api.affiliate.com/v1/products', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.AFFILIATE_API_TOKEN}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    search: [
      { field: 'any', value: 'wireless headphones', operator: 'LIKE' }
    ]
  })
});
const data = await response.json();
console.log(data);
```

```python theme={null}
import requests

response = requests.post(
    'https://api.affiliate.com/v1/products',
    headers={
        'Authorization': f'Bearer {api_token}',
        'Content-Type': 'application/json'
    },
    json={
        'search': [
            {'field': 'any', 'value': 'wireless headphones', 'operator': 'LIKE'}
        ]
    }
)
print(response.json())
```

```php theme={null}
$ch = curl_init('https://api.affiliate.com/v1/products');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode([
        'search' => [
            ['field' => 'any', 'value' => 'wireless headphones', 'operator' => 'LIKE']
        ]
    ]),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('AFFILIATE_API_TOKEN'),
        'Content-Type: application/json'
    ]
]);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
print_r($data);
```

### Response

```json theme={null}
{
  "data": [
    {
         "id": "1024588527555724845",
         "barcode": "607536460997",
         "name": "Bluetooth headphones. Wireless headphones. portable",
         "description": "Binaural HD call + intelligent noise reduction. Using the most advanced Bluetooth 5.0 technology it provides faster and more stable connectivity more realistic sound and reduced power consumption. The unique stereo design provides high-quality sound allowing you to enjoy high-quality wireless music anytime anywhere. There is an intelligent digital display showing the power the headset can be connected to different devices as long as there is a Bluetooth function can be connected. Product name: Bluetooth wireless headset; Waterproof: IPX5; Bluetooth version: V5.0; Bluetooth connection range: 10 meters; Headphone battery capacity: 30mah; Charging case battery capacity: 150MA; Packaging content: a pair of earphones; 1 x charging case; 1 x data cable. Only the above packaging contents excluding other products. Note: Light reflections and different displays may cause items in the picture to be slightly different colors than the real thing. The allowable measurement error is +/-1-3cm.",
         "image_url": "https://i5.walmartimages.com/asr/90a809ec-8f4f-4c54-95e9-32d9f5862c9e.120a5f2cb2b9b9664bb90837ac480d4e.jpeg?odnHeight=450&odnWidth=450&odnBg=ffffff",
         "urls": {
            "outclick": "https://outclick.co/a/eyJpdiI6IlRrVVB3VWQxaVhFeC96VlJLblN6T3c9PSIsInZhbHVlIjoiamg4VzVUMEVKRWFVeVJ0UTBwRFpLMTNpQ1o3bGlheENQZHZUNnlKdmR3bFptOEMvNUE3NllxNGpjYjlCR21yM3gzaEwvakRPMHVmQld6bkNiQ09GMDg5YStKQzFuVkhSenp3aTZGb0lPSEJpQ0d4eTBKL21xRW1hR2JXRGJvcDZLc005SWNXRVFac0hkS1UrZmtCTWtXZ25yNm1RTzhaVmszUzQ1SWhiZzNOMmRBMW5SVGQyeGxQL3dkZjlkVDdqWkRraUxKNmxXWnRvbjhWNTFuNFgvcVhYQ0tNVG40b2UzSWFieG1BQnppb3VmbndCck1NYjRNYkdnejg2NkVSVTBmKzdyakJIQzVidmh0M29JTkdEZHp4OEl2OVlwRW1ReFBNZzlBL3JvYTV2TUVjeTdSNE9uYjhWNERHTmVEcjVPaVdsUWZESTF5VXEvcEs1TW1EakR2d3A0RXhSK09kZ3JZeGg1RWRWSUxyZUlqejFnb2dlUC96bDhlbFVQZUs4WnExK29OR3VwQWhvZlFnZ0FadUdLU3JsMHJQbVNSUGxFZE5Hb1VIaTZQVXdVUDAvLzBEVGVVemllVFpsUndUUEZ0UkpwZE84eTFzd3FxeTJZVE5HcytlUGxZWjRhUCtCUVdOTDFwWHlSVkNNbzMxTTM2eW1mWnJLaUFjQXJvYXE3NXJKeXQ5QklDT2ptclFKU2o0ZVdObnVEblBWVnprdXc1SEJidFlRVmlnZVpuc0VoOGR5bnIzNUVTODRNSDZqM2lzN3lzbm9paEhOUmJmUmZlRE5Kb3MvL2NDd0FKckFFV3FWdEZNSlNEUUNPb0NNWkNsWDczcDEvV2VCUXEwSWp4eTB3QzJ3dDBMQnRlN3hsV2RveFF1UVBtUXRSWHV6WGVnRnFqeVltOStMam0zVHVnUzdXV1hTSmlWYWUrUVJ6QmdoZzVPQXNqRStYK1ZIVXduVjlJdUhySzZDQnM2UWZRbkpQL0MxZ0c0K21PTGpYbVBPU3NjbHBTSnZsSFBkRDJVNHJVaFBBYThUZmhOT3hnK0tmQVc4bjAzZkY2SlhwRmk1SFd5dnV3WGpseHdWeWd5dXBtUzlhVjhzeU4vS3ArR1N0YVgzWkRvZDN6UHZNR0hPS2VkOW8vVk81V3QrSDd2WmJSSU9IazF2aGdjdldIUXJUUzVsbFV1b05xanFUNURTSmt4ckdLeXlFRFlueE1ZdVFPRGk4WERiNmQ3bFRIbkNRWkw4TDhIazFvdHhpLzhzcW9yMkFOb1FGTnZBUmJ4eS82WkNMOUh4V25tSjBlMkFkbzdPVWUyenliYmhTcDdXMGIycHJMRTJQb2dmY0d1SzJHV0NZR0tkN1ZrK0V6dU9QeGowL2o0OUdXcHZ4N2tYK2dxaTVxOEgxZmplYU9tU2k0RzhrYUNReGF2Ykc3RFlzcVdWb3I1RmliaVNqRXZEaHN3SklYQ2hkZmxiR29hekhkUnEwSGw5Z1hLUlBZd3MxaC9FWVoyQXRIWHVKYXV0Sk1NdHNCSFFKUlJLa09tZ3lBRWVtUVRSaXpFR0JNWU03aFI4WUtjRTRRTFZ1WUwxUUtjMkpueTJaa1ljemdycXo1emxHQVdKUVMzVDBJWGhYeDBiNlVXdnJoNlBTTVVqTjJUb3pOakY3cEs3NDJxUTI2S2creGxLbmlIeUxxVW5RYUhza0ZLdnJsT2ZnNE4zMHlmbDkrWm03ZEJhcjlta1FBRWpGSWlBSjBWdnN0L1VEb2JBRFA2SXMyOHg4RDJYQVZXOTI0SksrNEY1U3R0M1ZQbUJ2MisyZ1h6UnZ6UUdVcDhKZWJHSmJoRjdOcDJ2WFNrVUx0U3NNQ0Rab0JmMkxta2kwQXhwNmZQVHNSZFd3MkZiMnVCTjBFTXY3cDk4M0ErNmQvUnJmWWVQdVp1OTZaNkE3aEZqOCtWdDVXdFhCaGc4bFJHZGVUSm1UVHNCUGJscHNEOUhXZk1PTUJtUFM0YWNycHFlT042cGwyRzI1bjEzU3BRZEoxNE5XNDZLdDRkR0k4M3VjdWlDMDNUUkl4MmkzVU1ZRGtzZWxneHg4SXpYODV3S1FSRUtTRGJBOVdoRVFudz0iLCJtYWMiOiJmYTU2NmQzODI5YzgxNGFiMzcwNDFiNzYyYzU1OGQ5YTk1YmRmYzU1MWNkNjE0MTc2N2RiY2JmYjU0MzQ3ODBlIiwidGFnIjoiIn0=?affiliate_id=@@@&sub_id=###",
            "direct": "https://www.walmart.com/ip/Bluetooth-headphones-Wireless-headphones-portable/14709523111",
            "affiliate": "https://goto.walmart.com/c/@@@/1285387/9383?prodsku=14709523111&u=https%3A%2F%2Fwww.walmart.com%2Fip%2FBluetooth-headphones-Wireless-headphones-portable%2F14709523111&intsrc=CATF_9768",
            "shopnomix": "https://r.v2i8b.com/api/v1/bid/redirect?url=https%3A%2F%2Fwww.walmart.com%2Fip%2FBluetooth-headphones-Wireless-headphones-portable%2F14709523111&campaign_id=@@@"
         },
         "currency": "USD",
         "regular_price": 18.41,
         "final_price": 18.41,
         "on_sale": false,
         "sale_discount": 0,
         "availability": "InStock",
         "commissionable_status": "assumed_commissionable",
         "seller_party": "third",
         "sku": "14709523111",
         "category": "Electronics > Walmart Restored > Restored Tech > Walmart Restored Audio > Walmart Restored Headphones",
         "condition": "New",
         "network": {
            "id": 335,
            "name": "Impact US",
            "logo_url": "https://img.affiliate.com/logos/groups/10020/128x128.png"
         },
         "merchant": {
            "id": 102458,
            "name": "Walmart",
            "logo_url": "https://img.affiliate.com/logos/merchants/102458/logo.png"
         },
         "added_at": "2026-03-22 09:57:20",
         "updated_at": "2026-03-22 09:57:20"
      }
  ],
  "meta": {
    "page": 1,
    "per_page": 10,
    "total": 342
  }
}
```

## Using Affiliate Links

The response offers multiple ways to monetize products.  If you have your own merchant relationships, you can replace the '@@@' with the applicable network publisher ID and '###' with an applicable subtracking ID.

Additionally, it is recommended you take advantage of our click tracking technology by using `urls.outclick` instead of `urls.affiliate` which can be used to build a fully hydrated picture of your customer's journey.

## Handle Errors

Check the response status and handle errors:

```javascript theme={null}
const response = await fetch(url, options);

if (!response.ok) {
  const error = await response.json();
  console.error(`Error: ${error.error.code} - ${error.error.message}`);
  return;
}

const data = await response.json();
```

```python theme={null}
response = requests.get(url, headers=headers)

if not response.ok:
    error = response.json()
    print(f"Error: {error['error']['code']} - {error['error']['message']}")
else:
    data = response.json()
```

```php theme={null}
$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => $headers
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode >= 400) {
    $error = json_decode($response, true);
    echo "Error: {$error['error']['code']} - {$error['error']['message']}";
} else {
    $data = json_decode($response, true);
}
```

## Next Steps

Now that you've made your first requests, learn about integration patterns for building robust applications.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.

---

## Core Concepts

---

# Affiliate product data model: fields and structure

Source: https://guides.affiliate.com/concepts/products.md

> ## 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.

# Affiliate product data model: fields and structure

> A reference for the product data model — covering URLs, pricing, inventory, identifiers, attributes, and how to work with each field group.

A product in the Affiliate.com API represents a single item available for sale through an affiliate merchant. Products are sourced from merchant feeds across hundreds of networks and refreshed daily. Each product record normalizes data from the merchant into a consistent structure regardless of which network provided it.

You search for products by sending a `POST` request to:

```
POST /v1/products
```

## Core fields

| Field | Type | Description |
| - | - | - |
| `id` | string | System-generated unique identifier for the product across all networks |
| `barcode` | string | Standardized product identifier — UPC, EAN, ISBN, or GTIN. Case-sensitive |
| `name` | string | Product title as provided by the merchant |
| `description` | string | Full product description including features and specifications |
| `commissionable_status` | string | Commission eligibility: `confirmed_commissionable`, `assumed_commissionable`, `commissionable`, or `not_commissionable` |

## URLs

Each product includes several URL types. The `urls` object is the recommended way to access them.

| Field | Type | Description |
| - | - | - |
| `commission_url` | string | Legacy affiliate URL. Replace `@@@` with your affiliate ID and `###` with your sub ID. Prefer `urls` instead |
| `direct_url` | string | Direct link to the product page on the merchant's site — no affiliate tracking |
| `image_url` | string | URL to the primary product image |
| `urls` | object | Structured collection of URL types — see below |

### The `urls` object

```json theme={null}
{
  "urls": {
    "outclick": "https://outclick.co/a/ENCRYPTED_TOKEN",
    "direct": "https://shop.example.com/products/item-123",
    "affiliate": "https://partners.example-network.com/click?merchant=12345&aff=@@@",
    "shopnomix": "https://r.v2i8b.com/api/v1/bid/redirect?url=..."
  }
}
```

| Field | Description |
| - | - |
| `urls.outclick` | **Recommended.** Enhanced tracking URL with support for dynamic query parameters (see below) |
| `urls.direct` | Direct merchant link with no affiliate tracking |
| `urls.affiliate` | Standard network affiliate URL. Replace `@@@` with your affiliate ID and `###` with your sub ID |
| `urls.shopnomix` | Specialized URL for Shopnomix platform integration |

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 parameters

You can append query parameters to the `outclick` URL at runtime to control its behavior:

| Parameter | Effect |
| - | - |
| `?format=direct` | Redirects to the direct merchant URL — no commission |
| `?format=affiliate` | Redirects through the affiliate tracking URL (default behavior) |
| `?format=shopnomix` | Redirects through the Shopnomix URL |
| `?sub_id=VALUE` | Overrides the sub ID for campaign-level attribution |

Omitting `?format=` follows your pool's **outclick priority** setting (`outclick_provider_order` — see [Pool Settings](/api-reference/pools/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.

For example, to send a user through the affiliate link with a custom sub ID:

```
https://outclick.co/a/ENCRYPTED_TOKEN?format=affiliate&sub_id=summer_sale_2025
```

## Pricing

| Field | Type | Description |
| - | - | - |
| `currency` | string | ISO 4217 three-letter currency code (e.g., `USD`, `EUR`, `GBP`) |
| `regular_price` | float | Standard retail price before any discounts (e.g., `119.99`) |
| `final_price` | float | Current selling price after discounts (e.g., `99.99`) |
| `on_sale` | boolean | `true` if the product is currently discounted |
| `sale_discount` | float | Discount amount in the product's currency |

## Inventory

| Field | Type | Description |
| - | - | - |
| `availability` | string | `InStock` or `OutOfStock` |
| `stock_quantity` | integer | Number of units available. May be `null` if the merchant doesn't provide stock levels |

## Identifiers

| Field | Type | Description |
| - | - | - |
| `mpn` | string | Manufacturer part number. Case-sensitive |
| `sku` | string | Merchant-specific inventory identifier. Case-sensitive |
| `barcode` | string | UPC, EAN, GTIN, or ISBN. Case-sensitive |
| `asin` | string | Amazon Standard Identification Number. Available on Amazon seller networks only. Case-sensitive |

## Attributes

| Field | Type | Description |
| - | - | - |
| `brand` | string | Brand or manufacturer name |
| `category` | string | Hierarchical category path (e.g., `"Home & Garden > Outdoor Storage > Shelters"`) |
| `size` | string | Size designation as provided by the merchant |
| `color` | string | Color as provided by the merchant |
| `gender` | string | Target gender demographic (e.g., `"Men"`, `"Women"`, `"Unisex"`). May be `null` |
| `material` | string | Primary materials used in construction |
| `country` | string | Country of origin |
| `condition` | string | Product condition: `new`, `used`, `refurbished`, or `open-box` |
| `seller_party` | string | Whether the product is sold first-party (`1st`), third-party (`3rd`), or `unknown` |

## Network and merchant info

Each product includes embedded `network` and `merchant` objects identifying where the listing comes from:

| Field | Type | Description |
| - | - | - |
| `network.id` | integer | Unique identifier for the affiliate network |
| `network.name` | string | Display name of the network |
| `network.logo_url` | string | URL to the network's logo |
| `merchant.id` | integer | Unique identifier for the merchant |
| `merchant.name` | string | Display name of the merchant |
| `merchant.logo_url` | string | URL to the merchant's logo |

## Timestamps

| Field | Type | Description |
| - | - | - |
| `updated_at` | string | ISO timestamp of when the product data was last refreshed from the merchant feed |
| `started_at` | string | ISO timestamp of when this product first appeared in the merchant's feed |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.

---

# Merchants: retailers and brands within affiliate networks

Source: https://guides.affiliate.com/concepts/merchants.md

> ## 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.

# Merchants: retailers and brands within affiliate networks

> Merchants are individual retailers within a network, like Levi's or Walmart. Use merchant IDs to scope product searches to specific sellers.

A merchant is an individual retailer or brand that sells products through an affiliate network. For example, Levi's listed on FlexOffers US and Walmart Canada listed on Rakuten US are both merchants. A single real-world company can appear as multiple merchants if it participates in more than one network or region. Additionally, some merchants organize their catalogs in multiple instances on the same network (e.g. Walmart).

The Affiliate.com platform normalizes merchant data across networks, giving you a consistent set of fields regardless of which network the merchant belongs to.

## Merchants endpoint

List all merchants:

```
GET /v1/merchants?extended=1
```

Look up a merchant by ID:

```
GET /v1/merchants/{id}?extended=1
```

<Note>
  **Pass `extended=1` on every request.** Whether the extended fields come back by default depends on your account, so don't assume they will. `extended=1` is what returns `providers`, `canonical`, `categories`, `countries`, `currencies`, `feed_languages`, `supports`, `supports_deeplinking`, `cookie_duration`, `home_url`, `object_id`, and `slug` — and it's harmless if your account already returns them. The merchant object below is the extended response.
</Note>

## Merchant object

```json theme={null}
{
  "id": 57131,
  "object_id": "nmer_01khfmrf8ch48c9r6at188r4rf",
  "slug": "nmer_t188r4rf",
  "origin_id": "1433375654",
  "name": "Levi's",
  "description": "Levi's is synonymous with denim jeans.",
  "domains": ["https://www.levi.com/us/en_us"],
  "home_url": "https://www.levi.com",
  "icon_url": "https://img.affiliate.com/logos/merchants/57131/icon.png",
  "logo_url": "https://img.affiliate.com/logos/canonical_merchants/01kkkkr948r2tq0pev510ch57j/logo.png",
  "product_count": 28391,
  "cookie_duration": "P7D",
  "supports_deeplinking": true,
  "categories": [
    {
      "id": "cat_01kkgcmxh8frckhytad1jz15xt",
      "breadcrumb": "Apparel & Accessories",
      "name": "Apparel & Accessories",
      "shopify_id": "aa",
      "google_id": "166"
    }
  ],
  "countries": ["US"],
  "currencies": ["USD"],
  "supports": { "products": true, "services": false, "promotions": false },
  "providers": [
    {
      "provider": "network",
      "status": "approved",
      "status_changed_at": "2025-01-15T10:00:00+00:00",
      "credential_id": "01kkgc7xxw8gg7y7f6wrnpgepv",
      "url": "https://track.flexoffers.com/click?mid=57131&id=12345",
      "template": "https://track.flexoffers.com/click?mid=57131&id={AFF_ID}",
      "outclick": "https://outclick.co/a/2.NetworkOpaqueToken?affiliate_id={AFF_ID}&sub_id={SUB_ID}",
      "supports_deeplinking": true,
      "deeplink": null,
      "approval": {
        "commission_data": {
          "action_name": "Default Sale",
          "action_type": "advanced sale",
          "commission_default": "8.00%"
        },
        "epc_data": {
          "currency": "USD",
          "seven_day": "5.10",
          "three_month": "13.70"
        },
        "cookie_duration": "P1M2D",
        "start_date": "2025-06-24",
        "end_date": null,
        "terms_and_conditions": "<h2>Terms and Conditions</h2><p>Program terms as reported by the network — HTML, and often long.</p>"
      }
    },
    {
      "provider": "shopnomix",
      "status": "approved",
      "status_changed_at": "2026-03-18T14:02:55+00:00",
      "credential_id": "01j8z3example000credential",
      "url": "https://r.v2i8b.com/api/v1/bid/redirect?url=https%3A%2F%2Fwww.levi.com&campaign_id=01J8Z3K9QW7RT2VN5XB6MC4FDH&source={SUB_ID}",
      "template": "https://r.v2i8b.com/api/v1/bid/redirect?url=https%3A%2F%2Fwww.levi.com&campaign_id={AFF_ID}&source={SUB_ID}",
      "outclick": "https://outclick.co/a/2.ShopnomixOpaqueToken?affiliate_id={AFF_ID}&sub_id={SUB_ID}",
      "supports_deeplinking": true,
      "deeplink": {
        "domain": "levi.com",
        "template": "https://r.v2i8b.com/api/v1/bid/redirect?url={target_url}&campaign_id=01J8Z3K9QW7RT2VN5XB6MC4FDH&source={SUB_ID}"
      },
      "approval": null
    }
  ],
  "network": {
    "id": 600,
    "slug": "rnet_wet1d3wp",
    "name": "FlexOffers US",
    "region": "US",
    "url": "https://www.flexoffers.com",
    "logo_url": "https://img.affiliate.com/logos/groups/10018/64x64.png",
    "icon_url": "https://img.affiliate.com/logos/groups/10018/64x64.png",
    "canonical_id": "net_01kkgbymywvbf5qjdcdwchxdhk",
    "links": {
      "self": "https://api.affiliate.com/v1/networks/rnet_01kkgbyq5vgd49n19twet1d3wp",
      "canonical": "https://api.affiliate.com/v1/networks/net_01kkgbymywvbf5qjdcdwchxdhk"
    }
  },
  "canonical": {
    "id": "mer_01kkkkr948r2tq0pev510ch57j",
    "slug": "mer_510ch57j",
    "name": "Levi's",
    "site_url": "https://www.levi.com",
    "logo_url": "https://img.affiliate.com/logos/canonical_merchants/01kkkkr948r2tq0pev510ch57j/logo.png",
    "icon_url": null,
    "domains": { "levi.com": "mer_01kkkkr948r2tq0pev510ch57j" },
    "domain_canonical_id": null,
    "links": {
      "self": "https://api.affiliate.com/v1/merchants/mer_01kkkkr948r2tq0pev510ch57j",
      "domain_canonical": null
    }
  }
}
```

## Key fields

| Field | Type | Description |
| - | - | - |
| `id` | integer | Legacy numeric merchant ID |
| `object_id` | string | Unique identifier in `nmer_ULID` format. Use for new integrations. |
| `slug` | string | Short URL-friendly identifier. |
| `origin_id` | string | Merchant's ID in the originating network. |
| `name` | string | Display name of the merchant |
| `description` | string\|null | Merchant description |
| `domains` | array | Canonical domain(s) for the merchant's website |
| `home_url` | string\|null | Merchant homepage URL. |
| `icon_url` | string | Merchant icon URL |
| `logo_url` | string | Merchant logo URL (sourced from canonical when available) |
| `product_count` | integer | Products currently available from this merchant |
| `cookie_duration` | string\|null | Cookie window as ISO 8601 duration (e.g. `P7D` = 7 days). |
| `supports_deeplinking` | boolean\|null | Whether deep link tracking is supported. |
| `categories` | array | Taxonomy categories. Each has `id`, `breadcrumb`, `name`, `shopify_id`, `google_id`. |
| `countries` | array | ISO 3166-1 alpha-2 codes where the merchant operates. |
| `currencies` | array | ISO 4217 currency codes accepted. |
| `feed_languages` | array | ISO 639-1 codes the product feed is written in. |
| `supports` | object | What the merchant monetizes: `products`, `services`, `promotions` (booleans). |
| `providers` | array | Ways to earn commission on this merchant — one entry per network/subnetwork, each with `status`, `url`, `template`, `outclick`, `deeplink`, `approval`. See [Provider status values](#provider-status-values) and the [merchant reference](/api-reference/merchants/list-merchants#outclick-links) for how `outclick` works. |
| `network` | object | The affiliate network this merchant belongs to |
| `canonical` | object\|null | The deduplicated canonical merchant record. |

## Provider status values

Each provider's `status` reflects your account's standing on that channel.

| Value | Description |
| - | - |
| `approved` | Active approved relationship |
| `pending` | Application submitted, not yet approved |
| `rejected` | Application was declined, disapproved, or denied |
| `terminated` | Previously approved relationship has ended |
| `available` | Programme is open — you have not yet applied |
| `unavailable` | Programme is closed to new applicants |
| `unknown` | Status could not be determined |
| `null` | No relationship, or request made without an API key |

## How merchants relate to networks

Every merchant belongs to exactly one network. The `network` object embedded in each merchant tells you which network it operates through. If the same retailer participates in multiple networks or regions, it appears as a separate merchant record for each one.

## Filtering merchants

The merchants endpoint supports several query parameters to narrow results:

| Parameter | Description |
| - | - |
| `search` | Search by merchant name (e.g., `?search=best+buy`) or domain (e.g., `bestbuy.com`) |
| `network_ids` | Comma-separated list of network IDs to filter by |
| `has_icon` | `1` to return only merchants with an icon URL |
| `has_logo` | `1` to return only merchants with a logo URL |
| `has_domains` | `1` to return only merchants with at least one domain |
| `has_description` | `1` to return only merchants with a description |
| `product_count_min` | Minimum number of products the merchant must have |
| `product_count_max` | Maximum number of products the merchant can have |
| `type[]` | Filter by record type: `products`, `service`, `promotions` (alias `coupons`), plus `all`, `both`, `none`. |
| `has_commissionable_url` | `1` to return only merchants that have a commissionable link template. |

## Using merchant IDs in product search

To search for products from a specific merchant, use the `merchant.id` field in your search criteria:

```json theme={null}
{
  "search": [
    {
      "field": "any",
      "value": "denim jeans",
      "operator": "LIKE"
    },
    {
      "field": "merchant.id",
      "value": "57131",
      "operator": "="
    }
  ],
  "networks": {
    "600": {
      "affiliate_id": "your_affiliate_id",
      "sub_id": "your_sub_id"
    }
  }
}
```

To include products from multiple merchants, separate their IDs with `||`:

```json theme={null}
{
  "field": "merchant.id",
  "value": "57131||37590",
  "operator": "="
}
```

To exclude a specific merchant from results:

```json theme={null}
{
  "field": "merchant.id",
  "value": "37590",
  "operator": "!="
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.

---

# Networks and network groups in the Affiliate.com API

Source: https://guides.affiliate.com/concepts/networks.md

> ## 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.

# Networks and network groups in the Affiliate.com API

> Networks are affiliate platforms like Rakuten or Awin. Each network hosts merchants and their products. Use network IDs to scope product searches.

A network is an affiliate platform that connects publishers (you) with merchants and their products. Examples include Impact US, Rakuten US, Awin UK, and FlexOffers. Each network operates independently — it has its own set of merchants, products, and affiliate link formats.

## Network groups

Related regional networks are organized into **network groups**. For example, Impact Sweden, Impact UK, and Impact US all belong to the "Impact" group. Network groups let you find and filter across all regional variants of a network without needing to know every individual network ID.

You can list all network groups from:

```
GET /v1/network-groups
```

And list all networks from:

```
GET /v1/networks
```

## Network object

```json theme={null}
{
  "id": 211,
  "slug": "rnet_wet1d3wp",
  "name": "ClixGalore Australia",
  "region": "AU",
  "url": "https://www.clixgalore.com",
  "logo_url": "https://img.affiliate.com/logos/groups/10011/64x64.png",
  "icon_url": "https://img.affiliate.com/logos/groups/10011/64x64.png",
  "canonical_id": "net_01kkgbymywvbf5qjdcdwchxdhk",
  "merchant_count": 398,
  "merchant_count_active": 13,
  "product_count": 61972,
  "group": {
    "id": 10011,
    "name": "ClixGalore"
  },
  "country": {
    "id": "AU",
    "iso3": "AUS",
    "name": "Australia"
  },
  "links": {
    "self": "https://api.affiliate.com/v1/networks/rnet_01kkgbyq5vgd49n19twet1d3wp",
    "canonical": "https://api.affiliate.com/v1/networks/net_01kkgbymywvbf5qjdcdwchxdhk"
  }
}
```

## Key fields

| Field | Type | Description |
| - | - | - |
| `id` | integer | Unique identifier for the network. Use this in product search requests |
| `slug` | string | Unique network slug in `rnet_` format. |
| `name` | string | Display name of the network (e.g., "Awin UK", "Impact US") |
| `region` | string | ISO 3166-1 alpha-2 region code (e.g., `"US"`, `"GB"`). |
| `url` | string | Network homepage URL. |
| `logo_url` | string | URL to the network's logo image |
| `icon_url` | string | URL to the network's icon. |
| `canonical_id` | string | Canonical network ID in `net_ULID` format — groups all regional variants. |
| `merchant_count` | integer | Total number of merchants registered in this network |
| `merchant_count_active` | integer | Number of merchants with active product feeds |
| `product_count` | integer | Total number of products available through this network |
| `group.id` | integer | ID of the network group this network belongs to |
| `group.name` | string | Name of the network group (e.g., "Impact", "Awin", "ClixGalore") |
| `country.id` | string | ISO 3166-1 alpha-2 country code (e.g., `"US"`, `"GB"`) |
| `country.iso3` | string | ISO 3166-1 alpha-3 country code (e.g., `"USA"`, `"GBR"`) |
| `country.name` | string | Full country name (e.g., "United States", "United Kingdom") |
| `links.self` | string | API link to this regional network record. |
| `links.canonical` | string | API link to the canonical (cross-region) network. |

## How networks relate to merchants

Each merchant belongs to exactly one network. When you look up a merchant, its `network` object tells you which network it operates through. When you search for products, each product includes a `network` object so you know which network is providing the listing.

## Using network IDs in product search

To scope a product search to one or more networks, include the network ID in your search criteria:

```json theme={null}
{
  "search": [
    {
      "field": "any",
      "value": "running shoes",
      "operator": "LIKE"
    },
    {
      "field": "network.id",
      "value": "314",
      "operator": "="
    }
  ],
  "networks": {
    "314": {
      "affiliate_id": "your_affiliate_id",
      "sub_id": "your_sub_id"
    }
  }
}
```

To search across multiple networks at once, separate the IDs with `||`:

```json theme={null}
{
  "field": "network.id",
  "value": "314||329||600",
  "operator": "="
}
```

You can also filter by network name if you don't have the ID:

```json theme={null}
{
  "field": "network.name",
  "value": "impact",
  "operator": "LIKE"
}
```

To find the correct network ID for a given network, use the networks endpoint with a name search:

```
GET /v1/networks?search=impact
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.

---

## Product Search

---

# POST /v1/products — search affiliate products

Source: https://guides.affiliate.com/api-reference/products/search.md

> ## 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 /v1/products — search affiliate products

> Search 1B+ affiliate products refreshed daily using filters, sorting, pagination, and faceted search across 40+ fields and multiple networks.

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](https://app.affiliate.com/tools/product-search) to build and test queries in your browser.

## Request

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

### 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="search" type="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:**

  ```json theme={null}
  "search": "JBL Speaker"
  ```

  **Array of objects:**

  ```json theme={null}
  "search": [
    { "field": "name", "value": "laptop", "operator": "like" }
  ]
  ```

  See [Search criteria](#search-criteria) below for all supported fields and operators.
</ParamField>

<ParamField body="query" type="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.

  ```json theme={null}
  {
    "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](#supported-search-fields). |
  | `rules[].conditions[].value` | mixed | Yes | Value to match. |
  | `rules[].conditions[].operator` | string | Yes | Comparison operator. Case-insensitive. See [Search criteria](#search-criteria). |

  See [Query builder examples](#query-builder-examples) below.
</ParamField>

<ParamField body="fields" type="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.

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

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

<ParamField body="page" type="integer">
  Page number for pagination. Minimum is `1`; maximum depends on your subscription plan.
</ParamField>

<ParamField body="after" type="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.
</ParamField>

<ParamField body="exact_total" type="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.
</ParamField>

<ParamField body="sort_by" type="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.
</ParamField>

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

<Note>
  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.
</Note>

<ParamField body="networks" type="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` |

  ```json theme={null}
  {
    "networks": {
      "329": {
        "affiliate_id": "your_affiliate_id",
        "sub_id": "your_sub_id"
      }
    }
  }
  ```
</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">
  **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.
</ParamField>

<ParamField body="facets" type="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"]
  ```
</ParamField>

<ParamField body="duplicate_fields_to_exclude" type="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`.
</ParamField>

<ParamField body="balanced_mix" type="object">
  Advanced result balancing with round-robin interleaving and optional weighting. Use this to prevent high-volume merchants from dominating results.

  <Warning>
    `balanced_mix` and `duplicate_fields_to_exclude` cannot be used together. Use one or the other.
  </Warning>

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

  ```json theme={null}
  {
    "balanced_mix": {
      "field": "merchant.id",
      "max_per_value": 5,
      "interleave": true,
      "weights": {
        "54419": 2.0,
        "41357": 0.5
      }
    }
  }
  ```
</ParamField>

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

### `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`.

```json theme={null}
{
  "field": "name",
  "value": "wireless headphones",
  "operator": "LIKE"
}
```

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

```json theme={null}
{ "field": "currency", "value": "USD||GBP||EUR", "operator": "=" }
```

<Note>
  To AND values, create separate filter objects in the array — each object is combined with AND logic.
</Note>

**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. 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. |
| `barcode` | `=`, `!=` | Case-sensitive |
| `sku` | `=`, `!=`, `LIKE` | Case-sensitive |
| `network.id` | `=`, `!=` | |
| `merchant.id` | `=`, `!=` | |
| `network.name` | `=`, `!=`, `LIKE`, `NOT LIKE` | |
| `merchant.name` | `=`, `!=`, `LIKE`, `NOT LIKE` | |
| `merchant.countries` | `=`, `!=` | Requires `extended=true`. Any country stored for the merchant, origin **or** market. ISO 3166-1 alpha-2, joined with `||`. |
| `merchant.countries_origin` | `=`, `!=` | Requires `extended=true`. Where the merchant sells from. |
| `merchant.countries_market` | `=`, `!=` | Requires `extended=true`. Where the merchant sells to. |
| `merchant.feed_languages` | `=`, `!=` | Requires `extended=true`. The language the merchant's product feed is written in, read off its own products. ISO 639-1, joined with `||`. |
| `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. 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 |
| `after` | string | Cursor for deep pagination (null if not applicable) |
| `sort_by` | string | Active sort field. Returned in normalized form, which can differ from the value you sent (e.g. `final_price` → `finalprice`) — treat it as informational rather than parsing it. |
| `sort_order` | string | Active sort direction |
| `trace_id` | string | Request trace ID for support use |

### `facets` object

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

<Expandable title="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 |
</Expandable>

<Expandable title="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 |
</Expandable>

### 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 | **Recommended.** 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) |

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:**

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

Omitting `?format=` follows your pool's **outclick priority** setting (`outclick_provider_order` — see [Pool Settings](/api-reference/pools/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

| 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

<CodeGroup>
  ```json 1. Simple search for "iPhone 14" theme={null}
  {
    "search": [
      {
        "field": "any",
        "value": "iPhone 14",
        "operator": "LIKE"
      }
    ],
    "per_page": 20,
    "sort_by": "final_price",
    "sort_order": "asc"
  }
  ```

  ```json 2. Barcode and SKU lookup theme={null}
  {
    "search": [
      {
        "field": "barcode",
        "value": "1234567890123",
        "operator": "="
      }
    ],
    "fields": ["id", "name", "brand", "final_price", "availability", "urls"]
  }
  ```

  ```json 3. Network and merchant specific search theme={null}
  {
    "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"
      }
    }
  }
  ```

  ```json 4. Advanced pet products search theme={null}
  {
    "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": "="
      }
    ]
  }
  ```

  ```json 5. Electronics with brand filtering and price range theme={null}
  {
    "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"
      }
    }
  }
  ```
</CodeGroup>

## Query builder examples

### Multiple brands with exclusion

```json theme={null}
{
  "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)

```json theme={null}
{
  "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 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.

---

# POST /products/omni — unified product search

Source: https://guides.affiliate.com/api-reference/products/omni.md

> ## 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="exact_total" type="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.
</ParamField>

<ParamField body="sort_by" type="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.
</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">
  **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.
</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. 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. |

<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` | |
| `merchant.countries` | `=`, `!=` | Requires `extended=true`. Any country stored for the merchant, origin **or** market. ISO 3166-1 alpha-2, joined with `||`. |
| `merchant.countries_origin` | `=`, `!=` | Requires `extended=true`. Where the merchant sells from. |
| `merchant.countries_market` | `=`, `!=` | Requires `extended=true`. Where the merchant sells to. |
| `merchant.feed_languages` | `=`, `!=` | Requires `extended=true`. The language the merchant's product feed is written in, read off its own products. ISO 639-1, joined with `||`. |
| `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 |

### `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 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.

---

## Networks

---

# Networks API: browse affiliate network data

Source: https://guides.affiliate.com/api-reference/networks/overview.md

> ## 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.

# Networks API: browse affiliate network data

> Explore affiliate network groups and individual regional networks, including merchant counts, product counts, logos, and country associations.

The Networks API gives you two levels of detail about the affiliate networks available on Affiliate.com: high-level **network groups** and granular **individual networks**. Use network groups to see the full roster of affiliate platforms, and use individual networks when you need region-specific data like merchant counts or product totals.

## Network groups vs. networks

**Network groups** represent a single affiliate platform brand — for example, Impact, Awin, or Rakuten. A network group bundles together all the regional instances of that platform.

**Networks** are the individual regional instances within a group. For example, the Impact network group contains separate networks for Impact US, Impact UK, Impact France, and so on. Each network carries its own merchant count, active merchant count, product count, logo URL, and country association.

Use network groups when you want to present a deduplicated list of platforms. Use individual networks when you need to filter merchants or products by a specific region or platform instance.

## Available endpoints

| Endpoint | Description |
| - | - |
| `GET /v1/network-groups` | List all network groups with pagination support. |
| `GET /v1/networks` | List all networks, with optional search and pagination. |
| `GET /v1/networks/{id}` | Retrieve a single network by its ID. |

## Query parameters

Both list endpoints support the following parameters:

| Parameter | Type | Description |
| - | - | - |
| `fields` | string | Comma-separated list of fields to include in the response (e.g. `id,name`). |
| `page` | integer | The page number to retrieve. Defaults to `1`. |
| `per_page` | integer | The number of results per page. Defaults to `100`. |

The `GET /v1/networks` endpoint additionally supports:

| Parameter | Type | Description |
| - | - | - |
| `search` | string | Filter networks by name (e.g. `?search=impact`). |

## Response structure

All list endpoints return a paginated envelope with two top-level keys: `meta` and `data`.

### `meta` object

| Field | Type | Description |
| - | - | - |
| `total` | integer | Total number of records matching your query. |
| `from` | integer | Index of the first record on the current page. |
| `to` | integer | Index of the last record on the current page. |
| `current_page` | integer | The current page number. |
| `last_page` | integer | The total number of pages. |
| `per_page` | integer \| string | The number of records per page. |
| `fields` | array | The fields included in each record of the response. |

### Network group object

| Field | Type | Description |
| - | - | - |
| `id` | integer | The unique identifier for the network group. |
| `name` | string | The display name of the network group (e.g. `"Impact"`). |

### Network object

| Field | Type | Description |
| - | - | - |
| `id` | integer | The unique identifier for the network. |
| `name` | string | The display name of the network (e.g. `"Impact US"`). |
| `logo_url` | string | URL to the network's 128×128 logo image. |
| `merchant_count` | integer | Total number of merchants on this network. |
| `merchant_count_active` | integer | Number of currently active merchants on this network. |
| `product_count` | integer | Total number of products indexed for this network. |
| `group` | object | The network group this network belongs to. |
| `group.id` | integer | The unique identifier of the parent network group. |
| `group.name` | string | The name of the parent network group. |
| `country` | object | The country associated with this network. |
| `country.id` | string | ISO 3166-1 alpha-2 country code (e.g. `"US"`). |
| `country.iso3` | string | ISO 3166-1 alpha-3 country code (e.g. `"USA"`). |
| `country.name` | string | The full country name (e.g. `"United States"`). |

## Next steps

* [List all network groups](/api-reference/networks/list-network-groups)
* [List all networks](/api-reference/networks/list-networks)
* [Get a specific network](/api-reference/networks/get-network)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.

---

# GET /v1/network-groups — list all network groups

Source: https://guides.affiliate.com/api-reference/networks/list-network-groups.md

> ## 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.

# GET /v1/network-groups — list all network groups

> Retrieve a paginated list of affiliate network groups such as Impact, Awin, and Rakuten. Each record returns the group's unique integer ID and display name.

Use this endpoint to fetch the full list of affiliate network groups available on Affiliate.com. Network groups represent top-level platform brands — each group contains one or more regional networks. This endpoint is useful when you want to display or filter by platform brand rather than a specific regional instance.

## Endpoint

```
GET /v1/network-groups
```

## Request

### Headers

<ParamField header="Authorization" type="string" required>
  Your bearer token in the format `Bearer <token>`.
</ParamField>

### Query parameters

<ParamField query="fields" type="string">
  Comma-separated list of fields to return in each network group object. For example, `fields=id,name`. When omitted, all available fields are returned.
</ParamField>

<ParamField query="page" type="integer">
  The page number to retrieve. Defaults to `1`.
</ParamField>

<ParamField query="per_page" type="integer">
  The number of network groups to return per page. Defaults to `100`.
</ParamField>

### Example request

```bash theme={null}
curl --location --request GET 'https://api.affiliate.com/v1/network-groups?page=1&fields=id,name&per_page=10' \
--header 'Authorization: Bearer {{token}}'
```

## Responses

### 200 — Success

Returns a paginated JSON object. The `meta` key contains pagination details and the `data` array contains the network group records.

<ResponseField name="meta" type="object">
  Pagination metadata for the response.

  <Expandable title="meta">
    <ResponseField name="total" type="integer">
      The total number of network groups matching your query.
    </ResponseField>

    <ResponseField name="from" type="integer">
      The index of the first record on the current page.
    </ResponseField>

    <ResponseField name="to" type="integer">
      The index of the last record on the current page.
    </ResponseField>

    <ResponseField name="current_page" type="integer">
      The current page number.
    </ResponseField>

    <ResponseField name="last_page" type="integer">
      The total number of pages available.
    </ResponseField>

    <ResponseField name="per_page" type="string | integer">
      The number of records per page.
    </ResponseField>

    <ResponseField name="fields" type="array">
      The fields included in each record of the `data` array.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="data" type="array">
  An array of network group objects.

  <Expandable title="data[]">
    <ResponseField name="id" type="integer">
      The unique identifier for the network group.
    </ResponseField>

    <ResponseField name="name" type="string">
      The display name of the network group (e.g. `"Impact"`, `"Awin"`, `"Rakuten"`).
    </ResponseField>
  </Expandable>
</ResponseField>

#### Example response

```json theme={null}
{
    "meta": {
        "total": 34,
        "from": 4,
        "to": 6,
        "current_page": 2,
        "last_page": 12,
        "per_page": "3",
        "fields": [
            "id",
            "name"
        ]
    },
    "data": [
        { "id": 10001, "name": "Adrecord" },
        { "id": 10002, "name": "Adtraction" },
        { "id": 10004, "name": "Avangate" },
        { "id": 10005, "name": "AvantLink" },
        { "id": 10006, "name": "Awin" },
        { "id": 10007, "name": "Belboon" },
        { "id": 10009, "name": "bol.com" },
        { "id": 10011, "name": "ClixGalore" },
        { "id": 10012, "name": "Commission Factory" },
        { "id": 10013, "name": "Commission Junction" },
        { "id": 10015, "name": "Daisycon" },
        { "id": 10017, "name": "Effiliation" },
        { "id": 10018, "name": "FlexOffers" },
        { "id": 10020, "name": "Impact" },
        { "id": 10021, "name": "LinkConnector" },
        { "id": 10022, "name": "Rakuten" },
        { "id": 10025, "name": "Paid on Results" },
        { "id": 10026, "name": "Partner-ads" },
        { "id": 10027, "name": "Partnerize" },
        { "id": 10028, "name": "PepperJam" },
        { "id": 10030, "name": "ShareASale" },
        { "id": 10031, "name": "Shopello" },
        { "id": 10033, "name": "The Affiliate Gateway" },
        { "id": 10034, "name": "TradeDoubler" },
        { "id": 10035, "name": "TradeTracker" },
        { "id": 10036, "name": "Webgains" },
        { "id": 10038, "name": "ADCELL" },
        { "id": 10039, "name": "2Performant" },
        { "id": 10040, "name": "Admitad" },
        { "id": 10041, "name": "Profitshare" },
        { "id": 10043, "name": "GoAffPro" },
        { "id": 10045, "name": "Adservice" },
        { "id": 10046, "name": "Addrevenue" },
        { "id": 10051, "name": "TimeOne" }
    ]
}
```

### 401 — Unauthenticated

Your bearer token is missing, expired, or invalid.

### 429 — Rate Limit Exceeded

You have exceeded your team's request rate limit. Wait before retrying.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.

---

# GET /v1/networks — list all affiliate networks

Source: https://guides.affiliate.com/api-reference/networks/list-networks.md

> ## 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.

# GET /v1/networks — list all affiliate networks

> Retrieve a paginated list of affiliate networks with merchant counts, product totals, logos, country data, and parent network group associations.

Use this endpoint to retrieve the full list of affiliate networks available on Affiliate.com. Unlike network groups, each network represents a specific regional instance of a platform — for example, ClixGalore Australia or Webgains UK. You can filter by name using the `search` parameter and control pagination with `page` and `per_page`.

## Endpoint

```
GET /v1/networks
```

## Request

### Headers

<ParamField header="Authorization" type="string" required>
  Your bearer token in the format `Bearer <token>`.
</ParamField>

### Query parameters

<ParamField query="fields" type="string">
  Comma-separated list of fields to return for each network (e.g. `fields=name,logo_url`). When omitted, all fields are returned.
</ParamField>

<ParamField query="page" type="integer">
  The page number to retrieve. Defaults to `1`.
</ParamField>

<ParamField query="per_page" type="integer">
  The number of networks to return per page. Defaults to `100`.
</ParamField>

<ParamField query="search" type="string">
  Filter networks by name. For example, `?search=impact` returns all networks whose name contains "impact".
</ParamField>

### Example request

```bash theme={null}
curl --location --request GET 'https://api.affiliate.com/v1/networks?page=1&fields=name,logo_url&per_page=10&search=impact' \
--header 'Authorization: Bearer {{token}}'
```

## Responses

### 200 — OK

Returns a paginated JSON object. The `meta` key contains pagination details and the `data` array contains the network records.

<ResponseField name="meta" type="object">
  Pagination metadata for the response.

  <Expandable title="meta">
    <ResponseField name="total" type="integer">
      The total number of networks matching your query.
    </ResponseField>

    <ResponseField name="from" type="integer">
      The index of the first record on the current page.
    </ResponseField>

    <ResponseField name="to" type="integer">
      The index of the last record on the current page.
    </ResponseField>

    <ResponseField name="current_page" type="integer">
      The current page number.
    </ResponseField>

    <ResponseField name="last_page" type="integer">
      The total number of pages available.
    </ResponseField>

    <ResponseField name="per_page" type="integer">
      The number of records per page.
    </ResponseField>

    <ResponseField name="fields" type="array">
      The fields included in each network object within `data`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="data" type="array">
  An array of network objects.

  <Expandable title="data[]">
    <ResponseField name="id" type="integer">
      The unique identifier for the network.
    </ResponseField>

    <ResponseField name="name" type="string">
      The display name of the network (e.g. `"ClixGalore Australia"`).
    </ResponseField>

    <ResponseField name="logo_url" type="string">
      URL pointing to the network's 128×128 logo image.
    </ResponseField>

    <ResponseField name="merchant_count" type="integer">
      The total number of merchants on this network.
    </ResponseField>

    <ResponseField name="merchant_count_active" type="integer">
      The number of currently active merchants on this network.
    </ResponseField>

    <ResponseField name="product_count" type="integer">
      The total number of products indexed for this network.
    </ResponseField>

    <ResponseField name="group" type="object">
      The parent network group this network belongs to.

      <Expandable title="group">
        <ResponseField name="id" type="integer">
          The unique identifier of the parent network group.
        </ResponseField>

        <ResponseField name="name" type="string">
          The name of the parent network group.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="country" type="object">
      The country associated with this network.

      <Expandable title="country">
        <ResponseField name="id" type="string">
          ISO 3166-1 alpha-2 country code (e.g. `"AU"`).
        </ResponseField>

        <ResponseField name="iso3" type="string">
          ISO 3166-1 alpha-3 country code (e.g. `"AUS"`).
        </ResponseField>

        <ResponseField name="name" type="string">
          The full country name (e.g. `"Australia"`).
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

#### Example response

```json theme={null}
{
    "meta": {
        "total": 0,
        "from": 1,
        "to": 0,
        "current_page": 1,
        "last_page": 0,
        "per_page": 100,
        "fields": [
            "id",
            "name",
            "logo_url",
            "merchant_count",
            "merchant_count_active",
            "product_count",
            "group",
            "country"
        ]
    },
    "data": [
        {
            "id": 211,
            "name": "ClixGalore Australia",
            "logo_url": "https://api.affiliate.com/img/logos/groups/10011/128x128.png",
            "merchant_count": 398,
            "merchant_count_active": 13,
            "product_count": 61972,
            "group": {
                "id": 10011,
                "name": "ClixGalore"
            },
            "country": {
                "id": "AU",
                "iso3": "AUS",
                "name": "Australia"
            }
        },
        {
            "id": 212,
            "name": "ClixGalore New Zealand",
            "logo_url": "https://api.affiliate.com/img/logos/groups/10011/128x128.png",
            "merchant_count": 39,
            "merchant_count_active": 2,
            "product_count": 652,
            "group": {
                "id": 10011,
                "name": "ClixGalore"
            },
            "country": {
                "id": "NZ",
                "iso3": "NZL",
                "name": "New Zealand"
            }
        },
        {
            "id": 213,
            "name": "ClixGalore UK",
            "logo_url": "https://api.affiliate.com/img/logos/groups/10011/128x128.png",
            "merchant_count": 139,
            "merchant_count_active": 3,
            "product_count": 742,
            "group": {
                "id": 10011,
                "name": "ClixGalore"
            },
            "country": {
                "id": "GB",
                "iso3": "GBR",
                "name": "United Kingdom"
            }
        },
        {
            "id": 221,
            "name": "Webgains UK Coupons/Deals",
            "logo_url": "https://api.affiliate.com/img/logos/groups/10036/128x128.png",
            "merchant_count": 1933,
            "merchant_count_active": 0,
            "product_count": 0,
            "group": {
                "id": 10036,
                "name": "Webgains"
            },
            "country": {
                "id": "GB",
                "iso3": "GBR",
                "name": "United Kingdom"
            }
        }
    ]
}
```

### 400 — Invalid input

One or more query parameters have invalid values. Check your `fields`, `page`, or `per_page` values.

### 401 — Unauthenticated

Your bearer token is missing, expired, or invalid.

### 429 — Rate Limit Exceeded

You have exceeded your team's request rate limit. Wait before retrying.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.

---

# GET /v1/networks/{id} — get a specific network

Source: https://guides.affiliate.com/api-reference/networks/get-network.md

> ## 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.

# GET /v1/networks/{id} — get a specific network

> Fetch a single affiliate network by its ID, returning its name, logo, merchant counts, product count, group, and country association.

Use this endpoint when you already know the ID of the network you want and need its full details — including merchant counts, product count, parent group, and country. The response wraps the single network record in the same paginated envelope as the list endpoint, with `meta.total` set to `1`.

## Endpoint

```
GET /v1/networks/{id}
```

## Request

### Path parameters

<ParamField path="id" type="integer" required>
  The unique identifier of the network to retrieve. You can find network IDs in the response from [GET /v1/networks](/api-reference/networks/list-networks).
</ParamField>

### Headers

<ParamField header="Authorization" type="string" required>
  Your bearer token in the format `Bearer <token>`.
</ParamField>

### Query parameters

<ParamField query="fields" type="string">
  Comma-separated list of fields to return (e.g. `fields=name,logo_url`). When omitted, all fields are returned.
</ParamField>

### Example request

```bash theme={null}
curl --location --request GET 'https://api.affiliate.com/v1/networks/110?fields=name,logo_url' \
--header 'Authorization: Bearer {{token}}'
```

## Responses

### 200 — Success

Returns the network wrapped in a paginated envelope. The `data` array contains exactly one network object.

<ResponseField name="meta" type="object">
  Pagination metadata. For a single-record response, `total`, `from`, `to`, `current_page`, and `last_page` are all `1`.

  <Expandable title="meta">
    <ResponseField name="total" type="integer">
      Always `1` for a single-network response.
    </ResponseField>

    <ResponseField name="from" type="integer">
      The index of the first (and only) record returned.
    </ResponseField>

    <ResponseField name="to" type="integer">
      The index of the last (and only) record returned.
    </ResponseField>

    <ResponseField name="current_page" type="integer">
      The current page number.
    </ResponseField>

    <ResponseField name="last_page" type="integer">
      The total number of pages (always `1` here).
    </ResponseField>

    <ResponseField name="per_page" type="integer">
      The number of records per page.
    </ResponseField>

    <ResponseField name="fields" type="array">
      The fields included in the network object.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="data" type="array">
  An array containing exactly one network object.

  <Expandable title="data[]">
    <ResponseField name="id" type="integer">
      The unique identifier for the network.
    </ResponseField>

    <ResponseField name="name" type="string">
      The display name of the network (e.g. `"Tradedoubler Finland"`).
    </ResponseField>

    <ResponseField name="logo_url" type="string">
      URL pointing to the network's 128×128 logo image.
    </ResponseField>

    <ResponseField name="merchant_count" type="integer">
      The total number of merchants on this network.
    </ResponseField>

    <ResponseField name="merchant_count_active" type="integer">
      The number of currently active merchants on this network.
    </ResponseField>

    <ResponseField name="product_count" type="integer">
      The total number of products indexed for this network.
    </ResponseField>

    <ResponseField name="group" type="object">
      The parent network group this network belongs to.

      <Expandable title="group">
        <ResponseField name="id" type="integer">
          The unique identifier of the parent network group.
        </ResponseField>

        <ResponseField name="name" type="string">
          The name of the parent network group.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="country" type="object">
      The country associated with this network.

      <Expandable title="country">
        <ResponseField name="id" type="string">
          ISO 3166-1 alpha-2 country code (e.g. `"FI"`).
        </ResponseField>

        <ResponseField name="iso3" type="string">
          ISO 3166-1 alpha-3 country code (e.g. `"FIN"`).
        </ResponseField>

        <ResponseField name="name" type="string">
          The full country name (e.g. `"Finland"`).
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

#### Example response

```json theme={null}
{
    "meta": {
        "total": 1,
        "from": 1,
        "to": 1,
        "current_page": 1,
        "last_page": 1,
        "per_page": 100,
        "fields": [
            "id",
            "name",
            "logo_url",
            "merchant_count",
            "merchant_count_active",
            "product_count",
            "group",
            "country"
        ]
    },
    "data": [
        {
            "id": 110,
            "name": "Tradedoubler Finland",
            "logo_url": "https://api.affiliate.com/img/logos/groups/10034/128x128.png",
            "merchant_count": 49,
            "merchant_count_active": 11,
            "product_count": 635130,
            "group": {
                "id": 10034,
                "name": "TradeDoubler"
            },
            "country": {
                "id": "FI",
                "iso3": "FIN",
                "name": "Finland"
            }
        }
    ]
}
```

### 400 — Invalid input

The `id` path parameter is not a valid network ID format.

### 401 — Unauthenticated

Your bearer token is missing, expired, or invalid.

### 404 — Record not found

No network exists with the specified `id`. Verify the ID using [GET /v1/networks](/api-reference/networks/list-networks).

### 429 — Rate Limit Exceeded

You have exceeded your team's request rate limit. Wait before retrying.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.

---

## Merchants

---

# Merchants API: find sellers across networks

Source: https://guides.affiliate.com/api-reference/merchants/overview.md

> ## 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.

# Merchants API: find sellers across networks

> The Merchants API returns full merchant profiles for every seller across all affiliate networks, including per-provider links and your standing, canonical records, categories, and more.

The Merchants API gives you access to detailed information about individual sellers affiliated with the networks on Affiliate.com. A merchant is a single seller or company within one network — for example, Levi's on FlexOffers or WalMart Canada on Rakuten US. The same real-world brand may appear as separate merchant records on different networks.

## Endpoints

| Method | Path | Description |
| - | - | - |
| `GET` | `/v1/merchants` | List and search all merchants |
| `GET` | `/v1/merchants/{id}` | Get a single merchant by numeric ID, `nmer_` ULID, `mer_` canonical ID, or slug |

## Query parameters

<Note>
  **Pass `extended=1` on every request.** Whether the extended fields come back by default depends on your account, so don't assume they will. `extended=1` is what returns `providers`, `canonical`, `categories`, `countries`, `currencies`, `feed_languages`, `supports`, `supports_deeplinking`, `cookie_duration`, `home_url`, `object_id`, and `slug` — and it's harmless if your account already returns them. If a response is missing `providers` or commissionable links, add the flag.
</Note>

### Base parameters

| Parameter | Type | Description |
| - | - | - |
| `extended` | integer | `1` returns the extended merchant object (`providers`, `canonical`, `categories`, `supports`, and more). Use the integer `1`, not `true` |
| `fields` | string | Comma-separated list of fields to return |
| `page` | integer | Page number to retrieve. Defaults to `1` |
| `per_page` | integer | Results per page. Defaults to `100` |
| `search` | string | Search by merchant name (e.g. `best+buy`) or domain (e.g. `bestbuy.com`) |
| `network_ids` | string | Comma-separated network IDs to filter by |
| `origin_ids` | string | Comma-separated origin IDs to filter by |
| `has_icon` | integer | `1` returns only merchants with an icon URL |
| `has_logo` | integer | `1` returns only merchants with a logo URL |
| `has_domains` | integer | `1` returns only merchants that have at least one domain |
| `has_description` | integer | `1` returns only merchants with a description |
| `product_count_min` | integer | Minimum product count filter |
| `product_count_max` | integer | Maximum product count filter |

### Filter parameters

| Parameter | Type | Description |
| - | - | - |
| `relationship_status` | string | Filter by relationship status: `approved`, `pending`, `rejected`, `terminated`, `available`, `unavailable`, `unknown` |
| `credential_id` | string | Filter to merchants accessible under a specific credential |
| `canonical_ids` | string | Comma-separated canonical merchant IDs (`mer_` ULID format) |
| `category_ids` | string | Comma-separated category IDs (`cat_` ULID format) |
| `category_name` | string | Filter by category name |
| `countries` | string | Comma-separated ISO 3166-1 alpha-2 country codes |
| `countries_origin` | string | Comma-separated country codes the merchant sells from |
| `countries_market` | string | Comma-separated country codes the merchant sells to |
| `currencies` | string | Comma-separated ISO 4217 currency codes |
| `feed_languages` | string | Comma-separated ISO 639-1 codes the product feed is written in |
| `has_commissionable_url` | integer | `1` returns only merchants with a stored `commissionable_url` template — **not** the same as "merchants I can link" (see caveat below) |
| `promotion_count_min` | integer | Minimum number of active promotions |
| `promotion_count_max` | integer | Maximum number of active promotions |
| `merchant_types` | string | Comma-separated types: `standard`, `asn` |
| `link_services[shopnomix]` | string | Filter by Shopnomix availability: `direct`, `indirect`, `verified`, `any`, `none` |

## Response structure

A successful response returns a `meta` object with pagination details and a `data` array of merchant objects.

```json theme={null}
{
  "meta": {
    "total": 112599,
    "from": 1,
    "to": 100,
    "current_page": 1,
    "last_page": 1126,
    "per_page": 100,
    "fields": ["id", "name", "network", "product_count"],
    "trace_id": "019ea511-fe66-713a-bb38-1ade42bbaf44"
  },
  "data": [...]
}
```

### Merchant object

| Field | Type | Description |
| - | - | - |
| `object_id` | string | Unique identifier in `nmer_ULID` format |
| `slug` | string | Short-form identifier (e.g. `nmer_rrmg0vg2`) |
| `origin_id` | string | Merchant's ID in the originating network |
| `home_url` | string\|null | Merchant homepage URL |
| `cookie_duration` | string\|null | Cookie window as ISO 8601 duration (e.g. `P7D`) |
| `supports_deeplinking` | boolean\|null | Whether the merchant supports deep link tracking |
| `categories` | array | Taxonomy categories (`id`, `breadcrumb`, `name`, `shopify_id`, `google_id`) |
| `countries` | array | ISO 3166-1 alpha-2 codes where the merchant operates |
| `currencies` | array | ISO 4217 currency codes accepted |
| `feed_languages` | array | ISO 639-1 codes the product feed is written in |
| `providers` | array | Ways to earn commission on this merchant — one entry per network/subnetwork. See [Provider entry](#provider-entry) |
| `canonical` | object\|null | The deduplicated canonical merchant record |
| `supports` | object | What the merchant monetizes: `products`, `services`, `promotions` (booleans) |
| `network.slug` | string | Network identifier in `rnet_` format |
| `network.region` | string | ISO 3166-1 alpha-2 region code |
| `network.icon_url` | string | Network icon URL |
| `network.canonical_id` | string | Canonical network ID in `net_` format |
| `network.links` | object | API links for this network (`self`, `canonical`) |

### Provider entry

Each object in `providers` is one way to earn commission on this merchant — one network or subnetwork (e.g. `network`, `shopnomix`).

| Field | Type | Description |
| - | - | - |
| `provider` | string | The channel — `network` or `shopnomix` |
| `status` | string\|null | Your standing on this channel. See [status values](#status-values) |
| `status_changed_at` | string\|null | ISO 8601 timestamp of the last status change |
| `credential_id` | string\|null | Network credential your standing/link is tied to |
| `url` | string\|null | Ready-to-use link with your credentials (straight to the provider). `null` when there's no built link for you — read the field itself rather than inferring it from `status` |
| `template` | string\|null | Shareable placeholder link (`{AFF_ID}` = affiliate/campaign ID, `{SUB_ID}` = sub-ID) |
| `outclick` | string\|null | Tracked link via `outclick.co`. See [Outclick links](#outclick-links) |
| `supports_deeplinking` | boolean\|null | Whether this provider can deep-link |
| `deeplink` | object\|null | Deep-link builder (`domain`, `template` with a `{target_url}` token); `null` for networks |
| `approval` | object\|null | The program's terms as reported by the network (`commission_data`, `epc_data`, `cookie_duration`, `start_date`, `end_date`, `terms_and_conditions`). Shapes of `commission_data`/`epc_data` vary by network. Present for `approved` **and** `available`; `null` when there's no approval record or no terms (Shopnomix is always `null`). |

### Outclick links

Each provider's `outclick` routes through Affiliate.com's redirector (`outclick.co`): it records the click, then forwards to the provider with your credentials — so it appears in `GET /v1/reports/outclick?offer_type=merchant`. `url` and `template` go straight to the network and are not recorded by us. Fill the `?affiliate_id={AFF_ID}&sub_id={SUB_ID}` slots with your own IDs.

These `{AFF_ID}`/`{SUB_ID}` tokens are specific to the merchants response — the Products and Promotions endpoints still use `@@@`/`###`, and the stored `commissionable_url` keeps `@@@`.

### Status values

| Value | Description |
| - | - |
| `approved` | Active approved relationship |
| `pending` | Application submitted, not yet approved |
| `rejected` | Application declined |
| `terminated` | Previously approved relationship has ended |
| `available` | Programme is open — you have not yet applied |
| `unavailable` | Programme is closed to new applicants |
| `unknown` | Status could not be determined |
| `null` | No relationship, or request made without an API key |

## Example response

```json theme={null}
{
  "data": [
    {
      "id": 142666,
      "object_id": "nmer_01khfn7dzc2a1w09d2rrmg0vg2",
      "slug": "nmer_rrmg0vg2",
      "origin_id": "37229",
      "name": "100% PURE",
      "description": "100% PURE creates natural, high-performance skincare and makeup with safe, pure ingredients.",
      "domains": ["https://100percentpure.com", "https://www.100percentpure.com"],
      "home_url": "https://100percentpure.com",
      "icon_url": "https://img.affiliate.com/logos/canonical_merchants/01kkjwnhgctjrmh5mqkcpdhq84/icon.png",
      "logo_url": "https://img.affiliate.com/logos/canonical_merchants/01kkjwnhgctjrmh5mqkcpdhq84/logo.png",
      "product_count": 689,
      "promotion_count": 0,
      "cookie_duration": null,
      "supports_deeplinking": true,
      "categories": [],
      "countries": ["US"],
      "currencies": [],
      "supports": { "products": true, "services": false, "promotions": false },
      "providers": [
        {
          "provider": "network",
          "status": "approved",
          "status_changed_at": "2026-03-12T07:13:10+00:00",
          "credential_id": "01kkgc7y12s1r29nkhrxavxbs8",
          "url": "https://100pure.sjv.io/c/21786/3053058/37229",
          "template": "https://100pure.sjv.io/c/{AFF_ID}/3053058/37229",
          "outclick": "https://outclick.co/a/2.NetworkOpaqueToken?affiliate_id={AFF_ID}&sub_id={SUB_ID}",
          "supports_deeplinking": true,
          "deeplink": null,
          "approval": {
            "commission_data": {
              "action_name": "Default Sale",
              "action_type": "advanced sale",
              "commission_default": "8.00%"
            },
            "epc_data": {
              "currency": "USD",
              "seven_day": "5.10",
              "three_month": "13.70"
            },
            "cookie_duration": "P1M2D",
            "start_date": "2025-06-24",
            "end_date": null,
            "terms_and_conditions": "<h2>Terms and Conditions</h2><p>Program terms as reported by the network — HTML, and often long.</p>"
          }
        },
        {
          "provider": "shopnomix",
          "status": "approved",
          "status_changed_at": "2026-03-18T14:02:55+00:00",
          "credential_id": "01j8z3example000credential",
          "url": "https://r.v2i8b.com/api/v1/bid/redirect?url=https%3A%2F%2F100percentpure.com&campaign_id=01J8Z3K9QW7RT2VN5XB6MC4FDH&source={SUB_ID}",
          "template": "https://r.v2i8b.com/api/v1/bid/redirect?url=https%3A%2F%2F100percentpure.com&campaign_id={AFF_ID}&source={SUB_ID}",
          "outclick": "https://outclick.co/a/2.ShopnomixOpaqueToken?affiliate_id={AFF_ID}&sub_id={SUB_ID}",
          "supports_deeplinking": true,
          "deeplink": {
            "domain": "100percentpure.com",
            "template": "https://r.v2i8b.com/api/v1/bid/redirect?url={target_url}&campaign_id=01J8Z3K9QW7RT2VN5XB6MC4FDH&source={SUB_ID}"
          },
          "approval": null
        }
      ],
      "network": {
        "id": 335,
        "slug": "rnet_hm7pn95t",
        "name": "Impact",
        "region": "US",
        "url": "https://www.impact.com",
        "logo_url": "https://img.affiliate.com/logos/groups/10020/64x64.png",
        "icon_url": "https://img.affiliate.com/logos/groups/10020/64x64.png",
        "canonical_id": "net_01kkgbymywvbf5qjdcdwchxdhm",
        "links": {
          "self": "https://api.affiliate.com/v1/networks/rnet_01kkgbyq82ve56ywbmhm7pn95t",
          "canonical": "https://api.affiliate.com/v1/networks/net_01kkgbymywvbf5qjdcdwchxdhm"
        }
      },
      "canonical": {
        "id": "mer_01kkjwnhgctjrmh5mqkcpdhq84",
        "slug": "mer_kcpdhq84",
        "name": "100% PURE",
        "site_url": "https://100percentpure.com",
        "logo_url": "https://img.affiliate.com/logos/canonical_merchants/01kkjwnhgctjrmh5mqkcpdhq84/logo.png",
        "icon_url": "https://img.affiliate.com/logos/canonical_merchants/01kkjwnhgctjrmh5mqkcpdhq84/icon.png",
        "domains": { "100percentpure.com": "mer_01kkjwnhgctjrmh5mqkcpdhq84" },
        "domain_canonical_id": null,
        "links": {
          "self": "https://api.affiliate.com/v1/merchants/mer_01kkjwnhgctjrmh5mqkcpdhq84",
          "domain_canonical": null
        }
      },
      "merchant_types": ["standard"],
      "link_services": null
    }
  ]
}
```

## Using merchant IDs in product search

Once you have a merchant's `id`, pass it to the Products API to scope your search to that merchant's catalog.

<Tip>
  Use the `search` parameter to find a merchant by name or domain, then copy their `id` to use as a filter in product search requests.
</Tip>

<Tip>
  Use `has_commissionable_url=1` to retrieve merchants where a commissionable link **template** is available, then replace the `{AFF_ID}` placeholder with your affiliate ID to build the link.
</Tip>

<Warning>
  **`has_commissionable_url=1` is not "everything I can monetize."** It matches only merchants with a stored `commissionable_url` template. A link built from a synced approval's tracking URL needs no template, so the filter excludes merchants that return a ready-to-use `url`.

  On a synced network this filter can match well under half a pool's merchants, while **every** merchant it excludes still returns a populated `providers[].url` — publisher id already baked in, `template: null`. To find every merchant you can link, page the unfiltered list and read `providers[].url`.
</Warning>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.

---

# GET /v1/merchants — list and search merchants

Source: https://guides.affiliate.com/api-reference/merchants/list-merchants.md

> ## 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.

# GET /v1/merchants — list and search merchants

> Retrieve a paginated list of merchants across affiliate networks. Each merchant object includes per-provider links and your standing, canonical records, categories, and more.

The `GET /v1/merchants` endpoint returns a paginated list of merchants from across all affiliate networks. A single brand may appear on multiple rows when it is carried by more than one network — each row represents that merchant through a specific network.

<Warning>
  Five networks require additional credentials before their products will sync: **Adservice**, **Belboon**, **Effiliation**, **Partnerize**, and **The Affiliate Gateway**. Without these credentials, the API returns `422` and products remain unavailable. Configure them under Pools → Sources on the relevant pool.
</Warning>

## Endpoint

```
GET /v1/merchants
```

## Query parameters

<Note>
  **Pass `extended=1` on every request.** Whether the extended fields come back by default depends on your account, so don't assume they will. `extended=1` is what returns `providers`, `canonical`, `categories`, `countries`, `currencies`, `feed_languages`, `supports`, `supports_deeplinking`, `cookie_duration`, `home_url`, `object_id`, and `slug` — and it's harmless if your account already returns them. If a response is missing `providers` or commissionable links, add the flag.
</Note>

### Base parameters

<ParamField query="extended" type="integer">
  Set to `1` to return the extended merchant object — `providers`, `canonical`, `categories`, `countries`, `currencies`, `feed_languages`, `supports`, `supports_deeplinking`, `cookie_duration`, `home_url`, `object_id`, and `slug`. Use the integer `1`, not `true`. Some accounts return these fields by default; passing the flag guarantees it. Several filters (`relationship_status`, `credential_id`) require it, and the set of values accepted by `fields` differs between the standard and extended responses.
</ParamField>

<ParamField query="fields" type="string">
  Comma-separated list of fields to include in each merchant object. Omit to return all fields.
</ParamField>

<ParamField query="page" type="integer">
  Page number. Defaults to `1`.
</ParamField>

<ParamField query="per_page" type="integer">
  Results per page. Defaults to `100`.
</ParamField>

<ParamField query="search" type="string">
  Partial, case-insensitive match on merchant name or website URL (`home_url`), e.g. `Walmart` or `walmart.com`. Does not match `nmer_`/`mer_` object IDs, the internal numeric `id`, or `origin_id` — use `origin_ids` for an exact origin-ID match.
</ParamField>

<ParamField query="network_ids" type="string">
  Comma-separated numeric network IDs to filter results.
</ParamField>

<ParamField query="origin_ids" type="string">
  Comma-separated origin IDs from the source network.
</ParamField>

<ParamField query="type" type="string">
  Record types to filter by (array form, e.g. `type[]=service&type[]=products`). Values: `products`, `service`, `promotions` (alias `coupons`), plus special values `all`, `none`. A merchant matches if it has **any** of them.
</ParamField>

<ParamField query="country_ids" type="string">
  Comma-separated country codes to filter by.
</ParamField>

<ParamField query="product_count_min" type="integer">
  Return only merchants with at least this many products.
</ParamField>

<ParamField query="product_count_max" type="integer">
  Return only merchants with at most this many products.
</ParamField>

### Filter parameters

<ParamField query="relationship_status" type="string">
  Filter by the workspace's relationship status with the merchant. Values: `approved`, `pending`, `rejected`, `terminated`, `available`, `unavailable`, `unknown`. Requires `extended=1` and a valid API key.
</ParamField>

<Note>
  `relationship_status` reads from **merchant sync** — the process that refreshes your approval records from your connected network credentials. With sync enabled, results reflect an update from within the last 24 hours. Without it, the filter returns an empty set rather than an error — including on an account with no network credential at all (e.g. Shopnomix-only): verified live, every status value returned `0` merchants despite 14+ merchants showing `providers[].shopnomix.status: "approved"`. There is no equivalent filter for Shopnomix (or other non-network provider) standing today.
</Note>

<ParamField query="credential_id" type="string">
  Network credential ULID. When combined with `relationship_status`, restricts the approval lookup to that specific credential. Requires `extended=1`.
</ParamField>

<ParamField query="pool_id" type="string">
  **Bare** ULID of a pool belonging to your team — the `pool_`-prefixed `object_id` form returns `422` ("The selected pool id is invalid."), so strip the prefix. Restricts the merchant list to **only** the merchants collected into that pool, and resolves `providers[]` approvals/links against that pool's own network credentials (**Pools → Sources**) instead of your account's default pool. Requires `extended=1`. Returns `422` if the pool doesn't exist or belongs to another team. Omit it and the list is unscoped, with links resolved against your account's default pool.
</ParamField>

<Note>
  This is a different merge than `pool_id` on `/v1/products`, `/v1/products/omni`, or `/v1/promotions` — there, the pool's `network_ids`/`merchant_ids` are **combined** with whatever you pass. Here, `pool_id` is a hard scope: only merchants collected into that pool come back, and there's no separate `merchant_ids` filter for it to merge with. See [Pools](/api-reference/pools/overview#using-a-pool-with-get-v1-merchants).
</Note>

<ParamField query="canonical_ids" type="string">
  Comma-separated canonical merchant IDs (`mer_` ULID format).
</ParamField>

<ParamField query="category_ids" type="string">
  Comma-separated category IDs (`cat_` ULID format).
</ParamField>

<ParamField query="category_name" type="string">
  Filter by category name. Max 255 characters.
</ParamField>

<ParamField query="countries" type="string">
  Comma-separated ISO 3166-1 alpha-2 country codes the merchant operates in.
</ParamField>

<ParamField query="countries_origin" type="string">
  Comma-separated country codes for the merchant's origin country.
</ParamField>

<ParamField query="countries_market" type="string">
  Comma-separated country codes for the merchant's market countries.
</ParamField>

<ParamField query="currencies" type="string">
  Comma-separated ISO 4217 currency codes (3-character).
</ParamField>

<ParamField query="feed_languages" type="string">
  Comma-separated ISO 639-1 language codes (2-character).
</ParamField>

<ParamField query="merchant_types" type="string">
  Comma-separated merchant types. Values: `standard`, `asn`.
</ParamField>

<ParamField query="link_services[shopnomix]" type="string">
  Filter by Shopnomix availability. Values: `direct`, `indirect`, `verified`, `any`, `none`.
</ParamField>

<ParamField query="promotion_count_min" type="integer">
  Return only merchants with at least this many promotions.
</ParamField>

<ParamField query="promotion_count_max" type="integer">
  Return only merchants with at most this many promotions.
</ParamField>

<ParamField query="has_commissionable_url" type="integer">
  Set to `1` to return only merchants with a stored `commissionable_url` **template**.

  This is **not** a "merchants I can link" filter. A link built from a synced approval's tracking URL needs no template, so this excludes merchants that do return a populated `providers[].url`. On a synced network this filter can match well under half a pool's merchants, while every merchant it excludes still returns a usable `url`. To test for a usable link, read `providers[].url`.
</ParamField>

## Example request

```bash cURL theme={null}
curl --request GET \
  'https://api.affiliate.com/v1/merchants?extended=1&relationship_status=approved&countries=US&per_page=10' \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

## Response

```json theme={null}
{
  "data": [
    {
      "id": 96521,
      "object_id": "nmer_01khfmzfac2zqmar3mas46gj2g",
      "slug": "nmer_as46gj2g",
      "origin_id": "21291",
      "name": "&Keep",
      "description": "At &Keep, we only have forever in mind - eco-friendly, sustainable, reusable.",
      "domains": ["https://andkeep.com"],
      "home_url": "https://andkeep.com",
      "icon_url": "https://img.affiliate.com/logos/canonical_merchants/01kkkm539pyetxf1f8ab5f8w7n/icon.png",
      "logo_url": "https://img.affiliate.com/logos/canonical_merchants/01kkkm539pyetxf1f8ab5f8w7n/logo.png",
      "product_count": 927,
      "promotion_count": 0,
      "has_content": true,
      "cookie_duration": null,
      "supports_deeplinking": null,
      "categories": [
        {
          "id": "cat_01kkgcmxh2b6me7vfp027sm323",
          "breadcrumb": "Uncategorized",
          "name": "Uncategorized",
          "shopify_id": "na",
          "google_id": null
        }
      ],
      "countries": ["GB"],
      "currencies": ["GBP"],
      "supports": { "products": true, "services": false, "promotions": false },
      "providers": [
        {
          "provider": "network",
          "status": "available",
          "status_changed_at": "2026-03-12T07:21:16+00:00",
          "credential_id": "01kkgc7xxw8gg7y7f6wrnpgepv",
          "url": null,
          "template": "https://www.awin1.com/awclick.php?mid=21291&id={AFF_ID}",
          "outclick": "https://outclick.co/a/2.NetworkOpaqueToken?affiliate_id={AFF_ID}&sub_id={SUB_ID}",
          "supports_deeplinking": null,
          "deeplink": null,
          "approval": null
        },
        {
          "provider": "shopnomix",
          "status": "approved",
          "status_changed_at": "2026-03-18T14:02:55+00:00",
          "credential_id": "01j8z3example000credential",
          "url": "https://r.v2i8b.com/api/v1/bid/redirect?url=https%3A%2F%2Fandkeep.com&campaign_id=01J8Z3K9QW7RT2VN5XB6MC4FDH&source={SUB_ID}",
          "template": "https://r.v2i8b.com/api/v1/bid/redirect?url=https%3A%2F%2Fandkeep.com&campaign_id={AFF_ID}&source={SUB_ID}",
          "outclick": "https://outclick.co/a/2.ShopnomixOpaqueToken?affiliate_id={AFF_ID}&sub_id={SUB_ID}",
          "supports_deeplinking": true,
          "deeplink": {
            "domain": "andkeep.com",
            "template": "https://r.v2i8b.com/api/v1/bid/redirect?url={target_url}&campaign_id=01J8Z3K9QW7RT2VN5XB6MC4FDH&source={SUB_ID}"
          },
          "approval": null
        }
      ],
      "network": {
        "id": 10,
        "slug": "rnet_mm87vz0t",
        "name": "Awin",
        "region": "GB",
        "url": "https://www.awin.com",
        "logo_url": "https://img.affiliate.com/logos/groups/10006/64x64.png",
        "icon_url": "https://img.affiliate.com/logos/groups/10006/64x64.png",
        "canonical_id": "net_01kkgbymywvbf5qjdcdwchxdh2",
        "links": {
          "self": "https://api.affiliate.com/v1/networks/rnet_01kkgbyn1qwj89esa7mm87vz0t",
          "canonical": "https://api.affiliate.com/v1/networks/net_01kkgbymywvbf5qjdcdwchxdh2"
        }
      },
      "canonical": {
        "id": "mer_01kkkm539pyetxf1f8ab5f8w7n",
        "slug": "mer_ab5f8w7n",
        "name": "&Keep",
        "site_url": "https://andkeep.com",
        "logo_url": "https://img.affiliate.com/logos/canonical_merchants/01kkkm539pyetxf1f8ab5f8w7n/logo.png",
        "icon_url": "https://img.affiliate.com/logos/canonical_merchants/01kkkm539pyetxf1f8ab5f8w7n/icon.png",
        "domains": { "andkeep.com": "mer_01kkkm539pyetxf1f8ab5f8w7n" },
        "domain_canonical_id": null,
        "links": {
          "self": "https://api.affiliate.com/v1/merchants/mer_01kkkm539pyetxf1f8ab5f8w7n",
          "domain_canonical": null
        }
      },
      "merchant_types": ["standard"],
      "link_services": { "shopnomix": "indirect" }
    }
  ]
}
```

## Response fields

### `meta` object

<ResponseField name="total" type="integer">Total matching merchants.</ResponseField>
<ResponseField name="from" type="integer">Index of the first result on this page.</ResponseField>
<ResponseField name="to" type="integer">Index of the last result on this page.</ResponseField>
<ResponseField name="current_page" type="integer">Current page number.</ResponseField>
<ResponseField name="last_page" type="integer">Total pages available.</ResponseField>
<ResponseField name="per_page" type="integer">Results per page.</ResponseField>
<ResponseField name="fields" type="array">Fields included in each merchant object.</ResponseField>
<ResponseField name="trace_id" type="string">Request trace ID for support use.</ResponseField>

### Merchant object

<ResponseField name="id" type="integer">
  Numeric merchant ID (legacy). Use `object_id` for new integrations.
</ResponseField>

<ResponseField name="object_id" type="string">
  Unique identifier in `nmer_ULID` format. Represents this merchant on a specific network.
</ResponseField>

<ResponseField name="slug" type="string">
  Short-form identifier (e.g. `nmer_as46gj2g`).
</ResponseField>

<ResponseField name="origin_id" type="string">
  The merchant's ID in the originating network. May be `null`.
</ResponseField>

<ResponseField name="name" type="string">Merchant display name.</ResponseField>
<ResponseField name="description" type="string">Merchant description. May be `null`.</ResponseField>
<ResponseField name="domains" type="array">Canonical domain(s) for the merchant.</ResponseField>

<ResponseField name="home_url" type="string">
  Merchant homepage URL.
</ResponseField>

<ResponseField name="icon_url" type="string">Merchant icon URL.</ResponseField>
<ResponseField name="logo_url" type="string">Merchant logo URL.</ResponseField>
<ResponseField name="product_count" type="integer">Products available from this merchant.</ResponseField>

<ResponseField name="promotion_count" type="integer">
  Promotions available from this merchant.
</ResponseField>

<ResponseField name="has_content" type="boolean">
  Whether the merchant has any associated content.
</ResponseField>

<ResponseField name="cookie_duration" type="string">
  Cookie window as ISO 8601 duration (e.g. `P1M2D`). `null` if not reported.
</ResponseField>

<ResponseField name="supports_deeplinking" type="boolean">
  Whether the merchant supports deep linking. `null` if unknown.
</ResponseField>

<ResponseField name="categories" type="array">
  Product categories. Each item has `id`, `breadcrumb`, `name`, `shopify_id`, `google_id`.
</ResponseField>

<ResponseField name="countries" type="array">
  ISO 3166-1 alpha-2 country codes where this merchant operates.
</ResponseField>

<ResponseField name="currencies" type="array">
  ISO 4217 currency codes supported.
</ResponseField>

<ResponseField name="feed_languages" type="array">
  ISO 639-1 codes the merchant's product feed is written in, read off its own products. Empty when
  no language could be read.
</ResponseField>

<ResponseField name="supports" type="object">
  What the merchant monetizes: `products`, `services`, `promotions` (booleans).
</ResponseField>

<ResponseField name="providers" type="array">
  The ways you can earn commission on this merchant — one entry per network/subnetwork. May be empty. See [Outclick links](#outclick-links) for how the tracked `outclick` link works.

  <Expandable title="provider fields">
    <ResponseField name="provider" type="string">The channel — `network` (the affiliate network the merchant belongs to) or `shopnomix` (the Shopnomix link subnetwork).</ResponseField>
    <ResponseField name="status" type="string">Your standing on this channel: `approved`, `pending`, `rejected`, `terminated`, `available`, `unavailable`, `unknown`, or `null` when you have no approval record.</ResponseField>
    <ResponseField name="status_changed_at" type="string">ISO 8601 timestamp of the last status change.</ResponseField>
    <ResponseField name="credential_id" type="string">Network credential your standing/link is tied to.</ResponseField>
    <ResponseField name="url" type="string">Ready-to-use link built with your credentials — goes **straight to the provider** (not recorded by Affiliate.com). Not gated on `status` — a provider showing `available` can still return a usable `url`. `null` when there's no built link for you yet.</ResponseField>
    <ResponseField name="template" type="string">Shareable placeholder link (`{AFF_ID}` = affiliate/campaign ID, `{SUB_ID}` = sub-ID). Replace the tokens to build your own link. `null` when there's no shareable form.</ResponseField>
    <ResponseField name="outclick" type="string">**Recommended.** A **tracked** link through Affiliate.com's redirector (`outclick.co`). See [Outclick links](#outclick-links). `null` when there's nothing to link.</ResponseField>
    <ResponseField name="supports_deeplinking" type="boolean">Whether this provider can deep-link to any page. `null` if unknown.</ResponseField>
    <ResponseField name="deeplink" type="object">Deep-link builder — `domain` plus a `template` carrying a `{target_url}` token — or `null` if the provider can't deep-link (networks are always `null`).</ResponseField>
    <ResponseField name="approval" type="object">The program's terms as reported by the network (`commission_data`, `epc_data`, `cookie_duration`, `start_date`, `end_date`, `terms_and_conditions`). The `commission_data`/`epc_data` shapes vary by network. Present for `approved` **and** `available` standings (so you can see the offer before applying); `null` when there's no approval record or no terms (Shopnomix is always `null`). An entire network can report no terms at all, in which case every row comes back `approved` with an empty `approval` — so treat terms as advisory, not as something an `approved` standing guarantees.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="network" type="object">
  The affiliate network for this merchant.

  <Expandable title="network fields">
    <ResponseField name="id" type="integer">Numeric network ID.</ResponseField>
    <ResponseField name="slug" type="string">`rnet_` format identifier.</ResponseField>
    <ResponseField name="name" type="string">Network display name.</ResponseField>
    <ResponseField name="region" type="string">ISO 3166-1 alpha-2 region code.</ResponseField>
    <ResponseField name="url" type="string">Network homepage URL.</ResponseField>
    <ResponseField name="logo_url" type="string">Network logo URL.</ResponseField>
    <ResponseField name="icon_url" type="string">Network icon URL.</ResponseField>
    <ResponseField name="canonical_id" type="string">`net_ULID` canonical network ID.</ResponseField>
    <ResponseField name="links" type="object">API links for this network record.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="canonical" type="object">
  The deduplicated canonical merchant record. `null` if none exists.

  <Expandable title="canonical fields">
    <ResponseField name="id" type="string">Canonical merchant ID in `mer_ULID` format.</ResponseField>
    <ResponseField name="slug" type="string">Short-form canonical identifier.</ResponseField>
    <ResponseField name="name" type="string">Canonical merchant name.</ResponseField>
    <ResponseField name="site_url" type="string">Canonical merchant website.</ResponseField>
    <ResponseField name="logo_url" type="string">Canonical logo URL.</ResponseField>
    <ResponseField name="icon_url" type="string">Canonical icon URL.</ResponseField>
    <ResponseField name="domains" type="object">Map of domain strings to their canonical merchant ID.</ResponseField>
    <ResponseField name="links" type="object">API links for this canonical record.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="merchant_types" type="array">
  Merchant classification. Values: `standard`, `asn` (Amazon Seller Network).
</ResponseField>

<ResponseField name="link_services" type="object">
  Third-party services available. Keys are service identifiers; values are `direct`, `indirect`, or `verified`. `null` if none.
</ResponseField>

## Provider link states

For each merchant we work down three options and stop at the first one that yields something:

1. **A link built for you.** Some networks build a link for one named publisher and hand it to us with your ID already in it. No slots left to fill — publish it as-is. This is the common case.
2. **A shared template.** More often for some networks, we hold one link for the merchant that everyone shares, with a slot where the ID goes. You fill `{AFF_ID}` (and optionally `{SUB_ID}`) before publishing, or let the `outclick` fill it at click time.
3. **No link.** The merchant still comes back with its name, logo and everything else we know — just nothing to link with. That's an answer, not a failure: the merchant exists and isn't monetizable by you yet.

<Note>
  **The case that looks like a template but isn't.** Sometimes the link we hold already has a real ID in the slot, and it belongs to someone else. That is not a template, whatever it looks like, and we never pass it on — every click would pay the wrong publisher. Those merchants fall to option 3 and return no link, even though the database plainly holds a URL for them. This is the usual explanation when a merchant you'd expect to be linkable comes back empty.
</Note>

Which lands you in one of three states:

| State | You see | How to use it |
| - | - | - |
| **Built for you** | `url` populated, `outclick` populated | Ready to go. `url` goes straight to the network with your credential **baked in**. The `outclick` has it baked in too — its `?affiliate_id={AFF_ID}&sub_id={SUB_ID}` slots are **optional overrides** (omit them and your credential is used; pass them to override). |
| **Shareable** | `url: null`, `template` populated (`{AFF_ID}`), `outclick` populated | Linkable, but nothing is built for you yet. Build from `template` (swap `{AFF_ID}`/`{SUB_ID}`), or use `outclick` — here you **must** fill its `?affiliate_id={AFF_ID}&sub_id={SUB_ID}` slots (no credential to fall back on). |
| **Not linkable** | `url`, `template`, and `outclick` all `null` | Nothing to act on for this provider; the entry still names it. `status`/`approval` may still be present (e.g. terms you can read before applying). |

**When each field is `null`:**

* **`url`** — no built tracking link. It's populated whenever your approval record carries one (Shopnomix builds it from a resolved campaign id instead). **It is not gated on `status`** — a provider showing `available` or `pending` can still return a usable `url`, and an `approved` one can return `null` if no tracking link was stored. Read `url`, not `status`, to decide whether you have a ready-made link. Note that a populated `url` is not always a *finished* link: Shopnomix bakes in `campaign_id` but leaves `source={SUB_ID}` for you to fill.
* **`template`** — the network stored no shareable placeholder form for this merchant, **or** the only stored link has a real publisher ID baked into it and so can't be shared (see the note above). Shopnomix always has a `template` when the merchant has a home URL. For AdMedia merchants, `template` is also withheld from accounts without the AdMedia grant.
* **`outclick`** — nothing to wrap (`url` **and** `template` both `null`); or the merchant is priced per click (CPC); or the provider's link is built from your own login credentials, which a merchant-level link has nowhere to carry. That last case is **detected per merchant, not taken from a fixed list** — every link is tested before it's offered and quietly dropped if a slot comes back unfilled, since a broken link is worse than no link. Adservice, Belboon and Partnerize commonly land here.

Two account-level switches withhold links everywhere rather than per merchant:

* **Outclick disabled on your account** — every `outclick` on every merchant is withheld until it's switched back on.
* **No team context** — requests that resolve no team (queued exports, for example) mint no outclick links at all.

### Getting from "Shareable" to "Built for you"

A provider stays in the **Shareable** state until two separate things are both true. Missing either one keeps `url` at `null`:

1. **You're connected.** The provider is configured as a source on the pool your request resolves to — **Pools → Sources** — or, failing that, at the account level, which is where resolution falls back to.
2. **The network has sent us a working link for this merchant.** Check `url` itself, not `status` — the two don't always move together.

**Shopnomix has no separate approval step.** A Shopnomix source with a campaign ID is sufficient on its own — `url` builds as soon as that's configured, and `status` reads `approved` for every merchant on that credential. Neither confirms Shopnomix has approved *this specific* merchant — only that a campaign credential resolves.

**Configuration is per pool, so check the right one.** If your request carries a `pool_id`, that pool's own sources are what count first — a provider configured on a *different* pool never applies. Omit `pool_id` and the request resolves to your account's default pool instead.

**Pool scoping is not provider isolation.** Credential resolution is pool-first, then account: for a provider the pool owns no credential for, the request falls back to your **account-level** credential. So a pool set up for one network still returns links for other providers — verified live, an AdMedia-only pool returned a working Shopnomix `url` for every merchant in it, carrying the account credential's campaign rather than the pool's. The same merchant can therefore come back with a different `campaign_id` under two different pools.

## Outclick links

Each provider carries an `outclick` — a link routed through Affiliate.com's redirector (`outclick.co`) rather than sent straight to the network. When a visitor follows it, Affiliate.com **records the click**, then forwards them to the provider with your credentials, so the click lands in your report. The `url` and `template` links, by contrast, go straight to the network and are **not** recorded by us — both carry your credentials to the same destination; the difference is only whether *we* record the click.

Using `outclick` isn't required — `url` and `template` work fine as standalone links — but it's strongly recommended, since it's the only one of the three that gives you click-level reporting.

Every `outclick` also carries the merchant's plain home page inside it, so you can request the ordinary uncommissioned link instead of the affiliate one without building anything yourself. AdMedia links are the exception — they're format-locked and always resolve to the AdMedia redirect.

<Note>
  **AdMedia replaces the network entry rather than adding to it.** For a merchant reaching us through AdMedia, the `url`, `template` and `outclick` on the `network` provider are AdMedia's own — there is no separate `admedia` entry in `providers`. Only accounts granted AdMedia access see them; to everyone else the merchant looks like it has no link. Shopnomix, by contrast, runs *alongside* the network provider, so a merchant can carry both.
</Note>

* **Fill the slots.** A shared outclick ends with `?affiliate_id={AFF_ID}&sub_id={SUB_ID}` — replace `{AFF_ID}` with your affiliate/campaign ID and `{SUB_ID}` with your sub-ID.
* **The outclick param is `affiliate_id` / `sub_id` for every provider except AdMedia.** Affiliate.com's redirector maps them to each provider's native parameter on the way through, so you never use the provider-specific name on an `outclick` — with that one exception. Those names otherwise appear only on the direct `url` / `template` links:

  | Link | `{AFF_ID}` goes in | `{SUB_ID}` goes in |
  | - | - | - |
  | **`outclick`** — every provider except AdMedia | `affiliate_id` | `sub_id` |
  | **`outclick`** — AdMedia | `aff_id` (+ `cid`, `ref_id`) | `sub_id` |
  | `template` / `url` — Shopnomix | `campaign_id` | `source` |
  | `template` / `url` — Awin | `id` on `awclick.php` (`awinaffid` on `cread.php` deep links) | *(network-specific)* |
  | `template` / `url` — Commission Factory | path segment (`…/{AFF_ID}/…`) | — |
* **AdMedia uses its own native names.** Its `outclick` carries `aff_id` / `sub_id` plus `cid` and `ref_id`, which have no generic equivalent. Don't "correct" it to `affiliate_id`.
* **The slots disappear as values resolve.** They're optional overrides, not requirements. An AdMedia merchant with an Affiliate ID saved on the pool returns `?sub_id={SUB_ID}` only; one with `cid`, `sub_id` and `ref_id` also saved returns **no query string at all**. A synced Awin merchant likewise arrives with the publisher id already baked into `url` and nothing left to fill.
* **Merchants-only naming.** These `{AFF_ID}`/`{SUB_ID}` tokens are how the **merchants** response spells the slots. The Products and Promotions endpoints still use `@@@`/`###`, and the merchant's stored `commissionable_url` keeps `@@@` — only the merchants response was renamed.
* **Reporting.** Merchant outclicks appear under the `merchant` offer type: `GET /v1/reports/outclick?offer_type=merchant` (the report defaults to `product`).
* **Deep links are not tracked here.** The `deeplink` builder produces a provider redirect (not an `outclick`), so deep-linked clicks don't appear in the outclick report — only the homepage-level `outclick` does.

## Error responses

| Status | Meaning |
| - | - |
| `401` | Missing or invalid API key |
| `422` | Missing network credentials for a network that requires them, or subscription usage cap reached |
| `429` | Rate limit exceeded — retry after a backoff interval |
| `503` | API temporarily overloaded — typically recovers within five minutes |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.

---

# Find merchants by name or domain on Affiliate.com

Source: https://guides.affiliate.com/api-reference/merchants/get-merchant-by-name.md

> ## 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.

# Find merchants by name or domain on Affiliate.com

> Use the search query parameter to find merchants by name fragment or domain. Combine with network_ids to narrow results to specific affiliate networks.

The `?search=` query parameter on `GET /v1/merchants` lets you find merchants by matching against their name or their `home_url`. You can use a partial name, a full name with spaces URL-encoded, or a bare domain string — the API handles both formats.

## How search matching works

* **Name search** — pass any part of the merchant's name, URL-encoded. For example, `?search=best+buy` matches "Best Buy US", "Best Buy Canada", and any other merchant whose name contains that phrase.
* **Domain search** — pass a bare domain such as `bestbuy.com`. The API matches against the merchant's `home_url` only — verified live: a domain present only in the `domains` array (not in `home_url`) does not match. It also does not match `origin_id`, the internal `id`, or `nmer_`/`mer_` object IDs.

<Note>
  Search is case-insensitive. You do not need to pass the full name or include `https://` for domain searches.
</Note>

## Endpoint

```
GET /v1/merchants?search={query}
```

## Examples

### Search by merchant name

```bash theme={null}
curl --request GET \
  'https://api.affiliate.com/v1/merchants?search=best+buy&page=1&per_page=10' \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

### Search by domain

```bash theme={null}
curl --request GET \
  'https://api.affiliate.com/v1/merchants?search=bestbuy.com&page=1&per_page=10' \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

### Find merchants with commissionable URLs

```bash theme={null}
curl --request GET \
  'https://api.affiliate.com/v1/merchants?has_commissionable_url=1&countries=US&per_page=50' \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

### Narrow results to a specific network

Combine `search` with `network_ids` to limit results to one or more networks. This is useful when the same brand is available on multiple networks and you want a specific one.

```bash theme={null}
curl --request GET \
  'https://api.affiliate.com/v1/merchants?search=food&network_ids=10&has_description=1&product_count_min=300&product_count_max=1000&page=1&per_page=10' \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

## Response

Search responses use the same structure as the standard list endpoint — a `meta` pagination object and a `data` array of matching merchant objects.

```json theme={null}
{
  "meta": {
    "total": 1,
    "from": 1,
    "to": 1,
    "current_page": 1,
    "last_page": 1,
    "per_page": 100,
    "fields": [
      "id",
      "name",
      "description",
      "domains",
      "icon_url",
      "logo_url",
      "product_count",
      "network"
    ],
    "trace_id": "0194fffe-9a3b-71aa-ada0-8686ff2715dd"
  },
  "data": [
    {
      "id": 71655,
      "name": "Real Food Hub",
      "description": "Real Food Hub is for people who love Real Good Food from farmers markets and enjoy the convenience of online ordering. We believe it has more taste, more nutrition and is more ethically produced.",
      "domains": ["https://www.realfoodhub.co.uk"],
      "icon_url": "https://img.affiliate.com/logos/merchants/71655/icon.png",
      "logo_url": "https://img.affiliate.com/logos/merchants/71655/logo.png",
      "product_count": 1301,
      "network": {
        "id": 10,
        "name": "Awin UK",
        "url": "https://www.awin.com",
        "logo_url": "https://img.affiliate.com/logos/groups/10006/128x128.png"
      }
    }
  ]
}
```

## Tips

<Tip>
  Add `network_ids` alongside `search` to filter results to merchants you're actually affiliated with. This eliminates noise when a common brand name appears across dozens of networks.
</Tip>

<Tip>
  Copy the `id` value from a search result and use it in `GET /v1/merchants/{id}` to fetch that merchant directly in future requests — no need to search again.
</Tip>

## Error responses

| Status | Meaning |
| - | - |
| `400` | Invalid input — check your parameter values |
| `401` | Unauthenticated — include a valid `Authorization: Bearer` header |
| `429` | Rate limit exceeded — slow down your request rate |

A search with no matches is not an error — it returns `200` with an empty `data` array and `meta.total: 0`, verified live.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.

---

# GET /v1/merchants/{id} — get a specific merchant

Source: https://guides.affiliate.com/api-reference/merchants/get-merchant-by-id.md

> ## 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.

# GET /v1/merchants/{id} — get a specific merchant

> Fetch a single merchant by numeric ID, nmer_ ULID, mer_ canonical ID, or slug. Returns the full merchant object including per-provider links and your standing, and the canonical record.

The `GET /v1/merchants/{id}` endpoint returns the full profile for a single merchant. The `{id}` path parameter accepts several formats:

| Format | Example | Resolves to |
| - | - | - |
| Integer | `71655` | Network merchant (legacy) |
| `nmer_` ULID | `nmer_01khfn7dzc2a1w09d2rrmg0vg2` | Network merchant |
| `mer_` ULID | `mer_01kkjwnhgctjrmh5mqkcpdhq84` | Canonical merchant |
| Slug | `nmer_rrmg0vg2` | Network merchant |
| Merchant Manager slug | `100-pure` | Canonical merchant |

## Endpoint

```
GET /v1/merchants/{id}
```

## Parameters

<ParamField path="id" type="string" required>
  Merchant identifier — accepts an integer ID, `nmer_` ULID, `mer_` canonical ULID, short slug, or a human-readable slug set in Merchant Manager.
</ParamField>

<ParamField query="extended" type="integer">
  Set to `1` to return the extended merchant object — `providers`, `canonical`, `categories`, `countries`, `currencies`, `feed_languages`, `supports`, `supports_deeplinking`, `cookie_duration`, `home_url`, `object_id`, and `slug`. Use the integer `1`, not `true`.
</ParamField>

<Note>
  **Pass `extended=1` on every request.** Whether the extended fields come back by default depends on your account, so don't assume they will. It's harmless if your account already returns them. If the response is missing `providers` or commissionable links, add the flag.
</Note>

## How to find a merchant's ID

If you don't already have a merchant's ID, use the list or search endpoint first:

1. Call `GET /v1/merchants?search=merchant+name` to find the merchant.
2. Copy the `id` or `object_id` from the matching result.
3. Use that value in `GET /v1/merchants/{id}` for direct lookups.

<Tip>
  Store `object_id` (`nmer_` format) rather than the integer `id` — it is stable across system migrations.
</Tip>

## Example requests

```bash Integer ID theme={null}
curl --request GET \
  'https://api.affiliate.com/v1/merchants/71655?extended=1' \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

```bash nmer_ ULID theme={null}
curl --request GET \
  'https://api.affiliate.com/v1/merchants/nmer_01khfn7dzc2a1w09d2rrmg0vg2?extended=1' \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

```bash Canonical ID theme={null}
curl --request GET \
  'https://api.affiliate.com/v1/merchants/mer_01kkjwnhgctjrmh5mqkcpdhq84?extended=1' \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

## Response

```json theme={null}
{
  "data": [
    {
      "id": 142666,
      "object_id": "nmer_01khfn7dzc2a1w09d2rrmg0vg2",
      "slug": "nmer_rrmg0vg2",
      "origin_id": "37229",
      "name": "100% PURE",
      "description": "100% PURE creates natural, high-performance skincare and makeup with safe, pure ingredients.",
      "domains": ["https://100percentpure.com", "https://www.100percentpure.com"],
      "home_url": "https://100percentpure.com",
      "icon_url": "https://img.affiliate.com/logos/canonical_merchants/01kkjwnhgctjrmh5mqkcpdhq84/icon.png",
      "logo_url": "https://img.affiliate.com/logos/canonical_merchants/01kkjwnhgctjrmh5mqkcpdhq84/logo.png",
      "product_count": 689,
      "promotion_count": 0,
      "cookie_duration": null,
      "supports_deeplinking": true,
      "categories": [],
      "countries": ["US"],
      "currencies": [],
      "supports": { "products": true, "services": false, "promotions": false },
      "providers": [
        {
          "provider": "network",
          "status": "approved",
          "status_changed_at": "2026-03-12T07:13:10+00:00",
          "credential_id": "01kkgc7y12s1r29nkhrxavxbs8",
          "url": "https://100pure.sjv.io/c/21786/3053058/37229",
          "template": "https://100pure.sjv.io/c/{AFF_ID}/3053058/37229",
          "outclick": "https://outclick.co/a/2.NetworkOpaqueToken?affiliate_id={AFF_ID}&sub_id={SUB_ID}",
          "supports_deeplinking": true,
          "deeplink": null,
          "approval": {
            "commission_data": {
              "action_name": "Default Sale",
              "action_type": "advanced sale",
              "commission_default": "8.00%"
            },
            "epc_data": {
              "currency": "USD",
              "seven_day": "5.10",
              "three_month": "13.70"
            },
            "cookie_duration": "P1M2D",
            "start_date": "2025-06-24",
            "end_date": null,
            "terms_and_conditions": "<h2>Terms and Conditions</h2><p>Program terms as reported by the network — HTML, and often long.</p>"
          }
        },
        {
          "provider": "shopnomix",
          "status": "approved",
          "status_changed_at": "2026-03-18T14:02:55+00:00",
          "credential_id": "01j8z3example000credential",
          "url": "https://r.v2i8b.com/api/v1/bid/redirect?url=https%3A%2F%2F100percentpure.com&campaign_id=01J8Z3K9QW7RT2VN5XB6MC4FDH&source={SUB_ID}",
          "template": "https://r.v2i8b.com/api/v1/bid/redirect?url=https%3A%2F%2F100percentpure.com&campaign_id={AFF_ID}&source={SUB_ID}",
          "outclick": "https://outclick.co/a/2.ShopnomixOpaqueToken?affiliate_id={AFF_ID}&sub_id={SUB_ID}",
          "supports_deeplinking": true,
          "deeplink": {
            "domain": "100percentpure.com",
            "template": "https://r.v2i8b.com/api/v1/bid/redirect?url={target_url}&campaign_id=01J8Z3K9QW7RT2VN5XB6MC4FDH&source={SUB_ID}"
          },
          "approval": null
        }
      ],
      "network": {
        "id": 335,
        "slug": "rnet_hm7pn95t",
        "name": "Impact",
        "region": "US",
        "url": "https://www.impact.com",
        "logo_url": "https://img.affiliate.com/logos/groups/10020/64x64.png",
        "icon_url": "https://img.affiliate.com/logos/groups/10020/64x64.png",
        "canonical_id": "net_01kkgbymywvbf5qjdcdwchxdhm",
        "links": {
          "self": "https://api.affiliate.com/v1/networks/rnet_01kkgbyq82ve56ywbmhm7pn95t",
          "canonical": "https://api.affiliate.com/v1/networks/net_01kkgbymywvbf5qjdcdwchxdhm"
        }
      },
      "canonical": {
        "id": "mer_01kkjwnhgctjrmh5mqkcpdhq84",
        "slug": "mer_kcpdhq84",
        "name": "100% PURE",
        "site_url": "https://100percentpure.com",
        "logo_url": "https://img.affiliate.com/logos/canonical_merchants/01kkjwnhgctjrmh5mqkcpdhq84/logo.png",
        "icon_url": "https://img.affiliate.com/logos/canonical_merchants/01kkjwnhgctjrmh5mqkcpdhq84/icon.png",
        "domains": { "100percentpure.com": "mer_01kkjwnhgctjrmh5mqkcpdhq84" },
        "domain_canonical_id": null,
        "links": {
          "self": "https://api.affiliate.com/v1/merchants/mer_01kkjwnhgctjrmh5mqkcpdhq84",
          "domain_canonical": null
        }
      },
      "merchant_types": ["standard"],
      "link_services": null
    }
  ]
}
```

## Response fields

See [List Merchants — Response fields](/api-reference/merchants/list-merchants#response-fields) for the full field reference. The single-merchant response uses the same object shape.

## Error responses

| Status | Meaning |
| - | - |
| `400` | Invalid input — check that `id` is a valid format |
| `401` | Unauthenticated — include a valid `Authorization: Bearer` header |
| `404` | No merchant found with the given ID |
| `429` | Rate limit exceeded — slow down your request rate |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.

---

## Identifier Conversion Tools

---

# Tools API: convert between product identifiers

Source: https://guides.affiliate.com/api-reference/tools/overview.md

> ## 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.

# Tools API: convert between product identifiers

> Convert between barcodes, SKUs, ASINs, and retailer URLs using a consistent POST format. Results map each source value to its converted target or null.

The Tools API lets you convert product identifiers from one type to another. If you have a barcode and need the Walmart SKU, an Amazon ASIN and need the matching barcode, or a retailer URL and need the UPC, this API handles the lookup.

## When to use the Tools API

Use the Tools API when you have one type of product identifier and need a different one. Supported conversions:

* Product page URLs → barcodes
* Barcodes → merchant SKUs
* Merchant SKUs → barcodes
* Amazon ASINs → barcodes
* Barcodes → Amazon ASINs

## Available endpoints

All endpoints use `POST` and accept a JSON request body.

| Endpoint | Converts |
| - | - |
| `POST /tools/convert/url-to-barcode` | Retailer product URL → barcode |
| `POST /tools/convert/barcode-to-sku` | Barcode → merchant SKU |
| `POST /tools/convert/sku-to-barcode` | Merchant SKU → barcode |
| `POST /tools/convert/ASIN-to-barcode` | Amazon ASIN → barcode |
| `POST /tools/convert/barcode-to-asin` | Barcode → Amazon ASIN |

## Request format

Every endpoint accepts the same JSON body structure: a `data` array of values to convert, and an optional `config` object for additional parameters.

```json theme={null}
{
  "data": ["value1", "value2"],
  "config": {}
}
```

### Required headers

| Header | Value |
| - | - |
| `Content-Type` | `application/json` |
| `Authorization` | `Bearer {your_api_key}` |

### Config requirements

Some conversions require a `config` object:

**ASIN conversions** — you must specify the Amazon locale:

```json theme={null}
{
  "config": {
    "asin": {
      "locale": "US"
    }
  }
}
```

**SKU conversions** — you must specify either the merchant name or merchant URL. If you supply both, only `name` is used:

```json theme={null}
{
  "config": {
    "merchant": {
      "name": "walmart"
    }
  }
}
```

```json theme={null}
{
  "config": {
    "merchant": {
      "url": "walmart.com"
    }
  }
}
```

## Response format

Every response includes a `meta` object describing the conversion and a `data` object containing the results.

```json theme={null}
{
  "meta": {
    "from": "barcode",
    "to": "sku",
    "from_total": 5,
    "to_total": 4,
    "config": { "merchant": { "name": "walmart" } },
    "trace_id": "0192e7de-ee66-72ad-9a8c-95f8055238da"
  },
  "data": {
    "9349520733755": "12987717129",
    "648093563899": "9853123116",
    "1234567890123": null
  }
}
```

### `meta` fields

| Field | Type | Description |
| - | - | - |
| `from` | string | The source identifier type. |
| `to` | string | The target identifier type. |
| `from_total` | integer | Number of source values you submitted. |
| `to_total` | integer | Number of successful conversions returned. |
| `config` | object | The config object used in the request. |
| `trace_id` | string | Unique request identifier for debugging and support. |

### `data` object

The `data` object maps each source value to its converted result. When a conversion cannot be made, the API returns `null` for that entry.

For URL-to-barcode and ASIN-to-barcode conversions, each source maps to an **array** of barcodes rather than a single string — a single product URL or ASIN can correspond to multiple barcodes. An empty array `[]` means no barcode was found.

## Conversion endpoints

<CardGroup cols={2}>
  <Card title="URL to Barcode" href="/api-reference/tools/url-to-barcode">
    Convert product page URLs from Amazon, Walmart, Target, and other major retailers to barcodes.
  </Card>

  <Card title="Barcode to SKU" href="/api-reference/tools/barcode-to-sku">
    Look up merchant-specific SKUs for a list of barcodes.
  </Card>

  <Card title="SKU to Barcode" href="/api-reference/tools/sku-to-barcode">
    Convert merchant SKUs back to their corresponding barcodes.
  </Card>

  <Card title="ASIN to Barcode" href="/api-reference/tools/asin-to-barcode">
    Retrieve barcodes for Amazon Standard Identification Numbers.
  </Card>

  <Card title="Barcode to ASIN" href="/api-reference/tools/barcode-to-asin">
    Find Amazon ASINs and locales for a given barcode.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.

---

# Convert retailer product page URLs to barcodes

Source: https://guides.affiliate.com/api-reference/tools/url-to-barcode.md

> ## 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.

# Convert retailer product page URLs to barcodes

> Submit product page URLs from major retailers and receive the corresponding barcodes. Returns an array per URL; empty array means no match was found.

The `POST /tools/convert/url-to-barcode` endpoint accepts product page URLs and returns the barcodes associated with each product. You can submit URLs from Amazon, Target, Walmart, Home Depot, Best Buy, Cabela's, and other major retailers in a single request.

## Endpoint

```
POST /v1/tools/convert/url-to-barcode
```

## Request body

Send a JSON body with a `data` array containing the product URLs you want to convert. No `config` object is required for URL conversions.

<ParamField body="data" type="array of strings" required>
  The product page URLs to convert. Each element must be a full URL string.
</ParamField>

```json theme={null}
{
  "data": [
    "https://www.cabelas.com/shop/en/jbl-by-harman-charge-5-waterproof-speaker-with-partyboost",
    "https://www.abt.com/JBL-Charge-5-Black-Portable-Waterproof-Speaker-With-Powerbank-JBLCHARGE5BLKAM/p/159497.html"
  ]
}
```

## Example request

```bash theme={null}
curl --request POST \
  --url 'https://api.affiliate.com/v1/tools/convert/url-to-barcode' \
  --header 'Authorization: Bearer {your_api_key}' \
  --header 'Content-Type: application/json' \
  --data '{
    "data": [
      "https://www.cabelas.com/shop/en/jbl-by-harman-charge-5-waterproof-speaker-with-partyboost",
      "https://www.abt.com/JBL-Charge-5-Black-Portable-Waterproof-Speaker-With-Powerbank-JBLCHARGE5BLKAM/p/159497.html"
    ]
  }'
```

## Example response

```json theme={null}
{
  "meta": {
    "from": "url",
    "to": "barcode",
    "from_total": 2,
    "to_total": 2,
    "trace_id": "0192e7dc-209a-7169-9c4f-5e9a298d3e76"
  },
  "data": {
    "https://www.cabelas.com/shop/en/jbl-by-harman-charge-5-waterproof-speaker-with-partyboost": [
      "50036380232"
    ],
    "https://www.abt.com/JBL-Charge-5-Black-Portable-Waterproof-Speaker-With-Powerbank-JBLCHARGE5BLKAM/p/159497.html": [
      "50036380218"
    ]
  }
}
```

## Response fields

### `meta` object

| Field | Type | Description |
| - | - | - |
| `from` | string | Always `"url"` for this endpoint. |
| `to` | string | Always `"barcode"` for this endpoint. |
| `from_total` | integer | Number of URLs you submitted. |
| `to_total` | integer | Number of URLs that returned at least one barcode. |
| `trace_id` | string | Unique request identifier for debugging and support. |

### `data` object

Each key is a URL from your request. Each value is an **array** of barcode strings for that product. A single product URL can match more than one barcode.

<ResponseField name="data" type="object">
  Key-value pairs where each URL maps to an array of barcodes.
</ResponseField>

<Note>
  URL conversions always return an array of barcodes for each URL, not a single string. Check for an empty array `[]` to detect URLs where no barcode was found — `to_total` only counts URLs with at least one result.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.

---

# Convert product barcodes to merchant-specific SKUs

Source: https://guides.affiliate.com/api-reference/tools/barcode-to-sku.md

> ## 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.

# Convert product barcodes to merchant-specific SKUs

> Look up the SKU a specific merchant uses for each barcode you provide. Requires a merchant name or URL in config. Returns null for unmatched barcodes.

The `POST /tools/convert/barcode-to-sku` endpoint converts barcodes to the internal SKUs used by a specific merchant. Because SKUs are merchant-specific, you must identify the merchant in the `config` object with every request.

## Endpoint

```
POST /v1/tools/convert/barcode-to-sku
```

## Request body

<ParamField body="data" type="array of strings" required>
  The barcodes to convert. Each element must be a valid numeric barcode string.
</ParamField>

<ParamField body="config" type="object" required>
  Configuration for the conversion. You must specify the target merchant.

  <Expandable title="config fields">
    <ParamField body="config.merchant.name" type="string">
      The merchant name (e.g. `"walmart"`). If you provide both `name` and `url`, only `name` is used.
    </ParamField>

    <ParamField body="config.merchant.url" type="string">
      The merchant domain (e.g. `"walmart.com"`). Used only when `name` is not provided.
    </ParamField>
  </Expandable>
</ParamField>

**Using merchant name:**

```json theme={null}
{
  "data": [
    "9349520733755",
    "648093563899",
    "1234567890123",
    "648093561147",
    "648093562182"
  ],
  "config": {
    "merchant": {
      "name": "walmart"
    }
  }
}
```

**Using merchant URL:**

```json theme={null}
{
  "data": ["9349520733755"],
  "config": {
    "merchant": {
      "url": "walmart.com"
    }
  }
}
```

## Example request

```bash theme={null}
curl --request POST \
  --url 'https://api.affiliate.com/v1/tools/convert/barcode-to-sku' \
  --header 'Authorization: Bearer {your_api_key}' \
  --header 'Content-Type: application/json' \
  --data '{
    "data": [
      "9349520733755",
      "648093563899",
      "1234567890123",
      "648093561147",
      "648093562182"
    ],
    "config": {
      "merchant": {
        "name": "walmart"
      }
    }
  }'
```

## Example response

```json theme={null}
{
  "meta": {
    "from": "barcode",
    "to": "sku",
    "from_total": 5,
    "to_total": 4,
    "config": {
      "merchant": {
        "name": "walmart"
      }
    },
    "trace_id": "0192e7de-ee66-72ad-9a8c-95f8055238da"
  },
  "data": {
    "9349520733755": "12987717129",
    "648093563899": "9853123116",
    "1234567890123": null,
    "648093561147": "9885868036",
    "648093562182": "9899956927"
  }
}
```

In this example, barcode `1234567890123` returns `null` because the merchant does not carry a product with that barcode.

## Response fields

### `meta` object

| Field | Type | Description |
| - | - | - |
| `from` | string | Always `"barcode"` for this endpoint. |
| `to` | string | Always `"sku"` for this endpoint. |
| `from_total` | integer | Number of barcodes you submitted. |
| `to_total` | integer | Number of barcodes that matched a SKU. |
| `config` | object | The merchant config used in the request. |
| `trace_id` | string | Unique request identifier for debugging and support. |

### `data` object

Each key is a barcode from your request. Each value is the merchant SKU string, or `null` if the merchant does not carry that product.

<ResponseField name="data" type="object">
  Key-value pairs where each barcode maps to a SKU string or `null`.
</ResponseField>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.

---

# Convert merchant-specific SKUs to product barcodes

Source: https://guides.affiliate.com/api-reference/tools/sku-to-barcode.md

> ## 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.

# Convert merchant-specific SKUs to product barcodes

> Resolve merchant-specific SKUs to their standard barcodes. Requires a merchant name or URL in the config object to identify the source catalog.

The `POST /tools/convert/sku-to-barcode` endpoint converts merchant SKUs to barcodes. Because SKUs are merchant-specific, you must identify the merchant in the `config` object so the API knows which catalog to look up.

## Endpoint

```
POST /v1/tools/convert/sku-to-barcode
```

## Request body

<ParamField body="data" type="array of strings" required>
  The merchant SKUs to convert.
</ParamField>

<ParamField body="config" type="object" required>
  Configuration for the conversion. You must specify the source merchant.

  <Expandable title="config fields">
    <ParamField body="config.merchant.name" type="string">
      The merchant name (e.g. `"walmart"`). If you provide both `name` and `url`, only `name` is used.
    </ParamField>

    <ParamField body="config.merchant.url" type="string">
      The merchant domain (e.g. `"walmart.com"`). Used only when `name` is not provided.
    </ParamField>
  </Expandable>
</ParamField>

```json theme={null}
{
  "data": [
    "12987717129",
    "9853123116",
    "9885868036",
    "9899956927"
  ],
  "config": {
    "merchant": {
      "name": "walmart"
    }
  }
}
```

## Example request

```bash theme={null}
curl --request POST \
  --url 'https://api.affiliate.com/v1/tools/convert/sku-to-barcode' \
  --header 'Authorization: Bearer {your_api_key}' \
  --header 'Content-Type: application/json' \
  --data '{
    "data": [
      "12987717129",
      "9853123116",
      "9885868036",
      "9899956927"
    ],
    "config": {
      "merchant": {
        "name": "walmart"
      }
    }
  }'
```

## Example response

```json theme={null}
{
  "meta": {
    "from": "sku",
    "to": "barcode",
    "from_total": 4,
    "to_total": 4,
    "config": {
      "merchant": {
        "name": "walmart"
      }
    },
    "trace_id": "0192e388-d982-720f-9f5d-172e335160fd"
  },
  "data": {
    "12987717129": "9349520733755",
    "9853123116": "648093563899",
    "9885868036": "648093561147",
    "9899956927": "648093562182"
  }
}
```

## Response fields

### `meta` object

| Field | Type | Description |
| - | - | - |
| `from` | string | Always `"sku"` for this endpoint. |
| `to` | string | Always `"barcode"` for this endpoint. |
| `from_total` | integer | Number of SKUs you submitted. |
| `to_total` | integer | Number of SKUs that resolved to a barcode. |
| `config` | object | The merchant config used in the request. |
| `trace_id` | string | Unique request identifier for debugging and support. |

### `data` object

Each key is a SKU from your request. Each value is the barcode string for that product.

<ResponseField name="data" type="object">
  Key-value pairs where each SKU maps to a barcode string.
</ResponseField>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.

---

# Convert Amazon ASINs to product barcodes

Source: https://guides.affiliate.com/api-reference/tools/asin-to-barcode.md

> ## 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.

# Convert Amazon ASINs to product barcodes

> Look up barcodes for Amazon Standard Identification Numbers. Requires an Amazon locale in config. Submit up to 10 ASINs per call; returns an array per ASIN.

The `POST /tools/convert/ASIN-to-barcode` endpoint converts Amazon Standard Identification Numbers (ASINs) to their corresponding barcodes. Each ASIN can map to multiple barcodes, so the API returns an array for each one.

## Endpoint

```
POST /v1/tools/convert/ASIN-to-barcode
```

<Warning>
  You can submit a maximum of 10 ASINs per request. Requests with more than 10 ASINs will return a validation error.
</Warning>

## Request body

<ParamField body="data" type="array of strings" required>
  The ASINs to convert. Maximum 10 per request.
</ParamField>

<ParamField body="config" type="object" required>
  Configuration for the conversion. You must specify the Amazon locale.

  <Expandable title="config fields">
    <ParamField body="config.asin.locale" type="string" required>
      The Amazon marketplace locale (e.g. `"US"`).
    </ParamField>
  </Expandable>
</ParamField>

```json theme={null}
{
  "data": [
    "B0C792QRW6",
    "B00AQUO5RI",
    "B0C792QRW9"
  ],
  "config": {
    "asin": {
      "locale": "US"
    }
  }
}
```

## Example request

```bash theme={null}
curl --request POST \
  --url 'https://api.affiliate.com/v1/tools/convert/ASIN-to-barcode' \
  --header 'Authorization: Bearer {your_api_key}' \
  --header 'Content-Type: application/json' \
  --data '{
    "data": [
      "B0C792QRW6",
      "B00AQUO5RI",
      "B0C792QRW9"
    ],
    "config": {
      "asin": {
        "locale": "US"
      }
    }
  }'
```

## Example response

```json theme={null}
{
  "meta": {
    "from": "asin",
    "to": "barcode",
    "from_total": 3,
    "to_total": 2,
    "config": {
      "asin": {
        "locale": "US"
      }
    },
    "trace_id": "0192f58a-0fde-7201-9bc7-653d0a6c4168"
  },
  "data": {
    "B0C792QRW6": [
      "0887276760049",
      "8806095074122"
    ],
    "B00AQUO5RI": [
      "0706487014362",
      "0615822003643"
    ],
    "B0C792QRW9": []
  }
}
```

In this example, `B0C792QRW6` and `B00AQUO5RI` each map to two barcodes, while `B0C792QRW9` returns an empty array because no barcode was found. `to_total` is `2` because only two ASINs produced results.

## Response fields

### `meta` object

| Field | Type | Description |
| - | - | - |
| `from` | string | Always `"asin"` for this endpoint. |
| `to` | string | Always `"barcode"` for this endpoint. |
| `from_total` | integer | Number of ASINs you submitted. |
| `to_total` | integer | Number of ASINs that returned at least one barcode. |
| `config` | object | The ASIN config used in the request. |
| `trace_id` | string | Unique request identifier for debugging and support. |

### `data` object

Each key is an ASIN from your request. Each value is an **array** of barcode strings. An ASIN can correspond to multiple barcodes (e.g. different regional packaging). An empty array `[]` means no barcode was found for that ASIN.

<ResponseField name="data" type="object">
  Key-value pairs where each ASIN maps to an array of barcode strings.
</ResponseField>

<Note>
  ASIN conversions always return an array of barcodes, not a single string. Check for an empty array `[]` to identify ASINs where no barcode was found.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.

---

# Convert product barcodes to Amazon ASINs

Source: https://guides.affiliate.com/api-reference/tools/barcode-to-asin.md

> ## 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.

# Convert product barcodes to Amazon ASINs

> Resolve barcodes to Amazon ASINs and their marketplace locales. Each barcode can map to multiple ASIN-locale pairs across Amazon marketplaces.

The `POST /tools/convert/barcode-to-asin` endpoint converts barcodes to Amazon Standard Identification Numbers (ASINs). Because the same product can appear under different ASINs in different Amazon marketplaces, each barcode maps to an array of objects — one per ASIN and locale combination found.

## Endpoint

```
POST /v1/tools/convert/barcode-to-asin
```

## Request body

<ParamField body="data" type="array of strings" required>
  The barcodes to convert. Each element must be a valid numeric barcode string.
</ParamField>

```json theme={null}
{
  "data": [
    "8806095074122",
    "0887276760049"
  ]
}
```

## Example request

```bash theme={null}
curl --request POST \
  --url 'https://api.affiliate.com/v1/tools/convert/barcode-to-asin' \
  --header 'Authorization: Bearer {your_api_key}' \
  --header 'Content-Type: application/json' \
  --data '{
    "data": [
      "8806095074122",
      "0887276760049"
    ]
  }'
```

## Example response

```json theme={null}
{
  "meta": {
    "from": "barcode",
    "to": "asin",
    "from_total": 2,
    "to_total": 1,
    "trace_id": "0196f461-079d-73c5-9c4e-aab8c4834d53"
  },
  "data": {
    "8806095074122": [
      {
        "asin": "B0C792QRW6",
        "locale": "us"
      }
    ]
  }
}
```

In this example, `8806095074122` resolves to ASIN `B0C792QRW6` in the `us` locale. Barcode `0887276760049` is absent from `data` because no matching ASIN was found — `to_total` reflects only the barcodes that produced results.

## Response fields

### `meta` object

| Field | Type | Description |
| - | - | - |
| `from` | string | Always `"barcode"` for this endpoint. |
| `to` | string | Always `"asin"` for this endpoint. |
| `from_total` | integer | Number of barcodes you submitted. |
| `to_total` | integer | Number of barcodes that returned at least one ASIN. |
| `trace_id` | string | Unique request identifier for debugging and support. |

### `data` object

Each key is a barcode from your request that produced a match. Each value is an array of objects, one per ASIN-locale pair found.

<ResponseField name="data" type="object">
  Key-value pairs where each barcode maps to an array of ASIN result objects.
</ResponseField>

<ResponseField name="data[barcode][].asin" type="string">
  The Amazon Standard Identification Number.
</ResponseField>

<ResponseField name="data[barcode][].locale" type="string">
  The Amazon marketplace locale where this ASIN was found (e.g. `"us"`).
</ResponseField>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.

---

## Product Watches

---

# Product Watch API: monitor price and availability

Source: https://guides.affiliate.com/api-reference/watches/overview.md

> ## 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.

# Product Watch API: monitor price and availability

> Monitor affiliate products for price drops, availability changes, and sale events, and receive webhook notifications when your conditions are met.

The Product Watch API lets you monitor affiliate products for price changes, availability updates, and sale events. When a condition you define is met, the API sends a notification to your webhook. You define the products to watch, the rules that trigger a notification, and how long the watch remains active.

## Watch types

Choose the watch type that matches how you identify your products.

<Tabs>
  <Tab title="Product ID">
    Use `target_type: "product"` to watch products using internal Affiliate.com product IDs. This is the most flexible watch type and supports every rule, filter, and condition.

    **Limits**

    * Up to 100 product IDs per watch
    * Up to 10 rules per watch

    **Supported filters**: `network.id`, `merchant.id`, `direct_url`, `currency`

    Use this type when you have already searched for and identified products in the Affiliate.com database.
  </Tab>

  <Tab title="ASIN">
    Use `target_type: "asin"` to monitor Amazon products directly by their ASIN, without first searching the Affiliate.com database.

    **Limits**

    * Up to 10 ASINs per watch
    * Up to 10 rules per watch
    * Only `final_price` and `regular_price` rules are supported
    * Filters are **not** allowed

    **Requirements**

    * You must include Amazon Creator API credentials in the `networks` object (`credential_id`, `credential_secret`, `partner_tag`, `locale`)
    * `start_value` is required for every rule — without it, the watch will never trigger
  </Tab>

  <Tab title="Barcode">
    Use `target_type: "barcode"` to monitor a product across all merchants using its universal product code (UPC, EAN, GTIN, or ISBN).

    **Limits**

    * Exactly 1 barcode per watch
    * Exactly 1 rule per watch

    **Supported filters**: `network.id`, `merchant.id`, `direct_url`, `currency`

    This type is ideal for cross-merchant price comparison — you track a single product code and receive alerts regardless of which retailer changes their price first.
  </Tab>
</Tabs>

## Watch behavior

Watches are checked **every 6 hours**. When a rule condition is satisfied during a check, the watch transitions to `"completed"` status and a notification is sent to your webhook.

Completed watches do **not** resume automatically. To continue monitoring after a rule triggers, call the PUT endpoint and set `status: "active"` with updated rules or a new `expire_timestamp`.

If a watched product becomes unavailable in the database, the watch is removed and you receive a final notification with `field: "__product__"` and `new_value: "unavailable"`.

## Expiration policy

Every watch expires at a configurable timestamp.

| Setting | Value |
| - | - |
| Default expiration | 90 days from creation |
| Maximum expiration | 180 days from the current time |

If you do not supply `expire_timestamp`, the watch expires 90 days from when you create it. When a watch reaches its expiration, you receive a webhook notification and the watch stops checking.

## Metadata

You can attach up to **16 key-value pairs** of custom metadata to each watch. Use metadata to tag watches with campaign names, product categories, priority levels, or any other context your application needs.

* Key maximum length: 64 characters
* Value maximum length: 512 characters

Metadata is returned in all API responses and in every webhook notification, so you can use it to route and process notifications programmatically. You can also filter watches by metadata using query parameters: `?metadata[campaign]=summer_sale`.

## Rule types and conditions

Rules define what change triggers a notification. Each rule specifies a `field` (what to watch), a `condition` (how it must change), and optionally a `threshold` (by how much).  Multiple rules all must match to trigger a notification (logical AND).

### Supported conditions by field

| Field | change | equals | not\_equals | increase | decrease | greater\_than | less\_than |
| - | - | - | - | - | - | - | - |
| `availability` | ✓ | ✓ | ✓ | — | — | — | — |
| `on_sale` | ✓ | ✓ | ✓ | — | — | — | — |
| `sale_discount` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| `final_price` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |

The `change` condition triggers on any change and does not require a threshold. All other conditions require a threshold.

### Threshold types

| Field | `value` | `percentage` |
| - | - | - |
| `availability` | ✓ | — |
| `on_sale` | ✓ | — |
| `sale_discount` | ✓ | ✓ |
| `final_price` | ✓ | ✓ |

**Allowed threshold values when `threshold.type` is `"value"`:**

| Field | Allowed values |
| - | - |
| `availability` | `"InStock"`, `"OutOfStock"`, `"Unknown"` |
| `on_sale` | `true`, `false` |
| `sale_discount` | Numeric float, 0–100 |
| `final_price` | Numeric, greater than 0 |

**When `threshold.type` is `"percentage"`**: provide a number from 1–100.

## Filters

You can optionally narrow which products trigger a watch using the `filters` array. Each filter specifies a `field`, an `operator`, and a `value`.

Supported filter fields: `network.id`, `merchant.id`, `direct_url`, `currency`

```json theme={null}
{
  "filters": [
    {
      "field": "merchant.id",
      "operator": "=",
      "value": "41357"
    },
    {
      "field": "currency",
      "operator": "=",
      "value": "USD"
    }
  ]
}
```

<Warning>
  Filters are not supported for ASIN watches. Including a `filters` array in an ASIN watch request will result in an error.
</Warning>

## Available endpoints

| Method | Endpoint | Description |
| - | - | - |
| `GET` | `/v1/products/watches` | List all your product watches. |
| `POST` | `/v1/products/watches` | Create a new product watch. |
| `GET` | `/v1/products/watches/{watch_id}` | Retrieve a specific watch by ID. |
| `PUT` | `/v1/products/watches/{watch_id}` | Update or reactivate a watch. |
| `DELETE` | `/v1/products/watches/{watch_id}` | Delete a watch. |
| `GET` | `/v1/products/watches/{watch_id}/histories` | Get notification history for a specific watch. |
| `GET` | `/v1/products/watches/histories` | Get notification history filtered by metadata. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.

---

# POST /v1/products/watches — create a product watch

Source: https://guides.affiliate.com/api-reference/watches/create-watch.md

> ## 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 /v1/products/watches — create a product watch

> Create a product watch to receive webhook notifications when price, availability, or sale conditions change on the products you specify.

The `POST /v1/products/watches` endpoint creates a new product watch. You define the products to monitor, the rules that trigger a notification, the webhook URL to notify, and optional filters and metadata. The watch starts checking immediately after creation (unless you set `status: "paused"`).

## Endpoint

```
POST /v1/products/watches
```

## Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication. Format: `Bearer {your_api_key}`.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`.
</ParamField>

## Request body

<ParamField body="name" type="string" required>
  A human-readable label for the watch. Used in webhook payloads and notification history responses.
</ParamField>

<ParamField body="target_type" type="string" required>
  The type of identifier you are using. One of `"product"`, `"asin"`, or `"barcode"`.
</ParamField>

<ParamField body="target_ids" type="string[]" required>
  The product identifiers to watch. For `"product"` watches, supply up to 100 Affiliate.com product IDs. For `"asin"` watches, supply up to 10 Amazon ASINs. For `"barcode"` watches, supply exactly 1 barcode (UPC, EAN, GTIN, or ISBN).
</ParamField>

<ParamField body="rules" type="object[]" required>
  The conditions that trigger a notification. When multiple rules are defined, **all rules must be met** (AND logic) for the watch to trigger. Maximum 10 rules for `product` and `asin` watches; exactly 1 rule for `barcode` watches.

  <Expandable title="Rule object properties">
    <ParamField body="rules[].field" type="string" required>
      The product attribute to watch. One of `"final_price"`, `"availability"`, `"on_sale"`, or `"sale_discount"`. Note: ASIN watches only support `"final_price"` and `"regular_price"`.
    </ParamField>

    <ParamField body="rules[].condition" type="string" required>
      How the field must change to trigger the rule. One of `"increase"`, `"decrease"`, `"equals"`, `"not_equals"`, `"greater_than"`, `"less_than"`, or `"change"`. Not all conditions are valid for every field — see the [overview](/api-reference/watches/overview#rule-types-and-conditions).
    </ParamField>

    <ParamField body="rules[].start_value" type="number">
      The baseline value at the time you create the watch. Required for all rules in ASIN watches. Optional for other watch types — if omitted, the API captures the current value on the first check.
    </ParamField>

    <ParamField body="rules[].threshold" type="object">
      The magnitude of change required to trigger the rule. Not required when `condition` is `"change"`.

      <Expandable title="Threshold properties">
        <ParamField body="rules[].threshold.type" type="string" required>
          Either `"value"` for an absolute value or `"percentage"` for a relative change. Availability and on\_sale fields only support `"value"`.
        </ParamField>

        <ParamField body="rules[].threshold.value" type="number | string | boolean" required>
          The threshold amount. For `"percentage"` type, supply a number from 1–100. For `"value"` type with `availability`, supply `"InStock"`, `"OutOfStock"`, or `"Unknown"`. For `on_sale`, supply `true` or `false`.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="notifications" type="object[]" required>
  Where to send alerts when a rule triggers.

  <Expandable title="Notification object properties">
    <ParamField body="notifications[].channel" type="string" required>
      The delivery channel. Currently only `"webhook"` is supported.
    </ParamField>

    <ParamField body="notifications[].target" type="string" required>
      The webhook URL to POST the notification to. Must be a valid, publicly accessible HTTPS URL. The system sends a test request to this URL when the watch is created — your endpoint must return a `2xx` status or the watch creation will fail.
    </ParamField>

    <ParamField body="notifications[].frequency" type="string" required>
      How quickly notifications are sent after a rule triggers. Currently only `"immediately"` is supported.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="status" type="string" default="active">
  The initial status of the watch. Either `"active"` (starts checking immediately) or `"paused"` (created but not checking).
</ParamField>

<ParamField body="filters" type="object[]">
  Narrow which product listings trigger the watch. Each filter has a `field`, `operator`, and `value`. Supported fields: `network.id`, `merchant.id`, `direct_url`, `currency`. Multiple filters are combined with **AND** — all conditions must match. **Not allowed for ASIN watches.**
</ParamField>

<ParamField body="metadata" type="object">
  Up to 16 custom key-value pairs to attach to the watch. Keys are max 64 characters; values are max 512 characters. Returned in all API responses and in every webhook notification.
</ParamField>

<ParamField body="expire_timestamp" type="integer">
  UNIX timestamp when the watch should expire. Defaults to 90 days from creation. Maximum is 180 days from the current time. You receive a webhook notification when the watch expires.
</ParamField>

<ParamField body="networks" type="object">
  Amazon Creator API credentials. Required for `"asin"` watches.

  <Expandable title="Networks object properties">
    <ParamField body="networks.amazon.credential_id" type="string" required>
      Your Amazon Creator API credential ID.
    </ParamField>

    <ParamField body="networks.amazon.credential_secret" type="string" required>
      Your Amazon Creator API credential secret.
    </ParamField>

    <ParamField body="networks.amazon.partner_tag" type="string" required>
      Your Amazon Associates partner tag.
    </ParamField>

    <ParamField body="networks.amazon.locale" type="string" required>
      The Amazon marketplace locale, such as `"US"`, `"GB"`, or `"DE"`.
    </ParamField>
  </Expandable>
</ParamField>

## Request examples

<Tabs>
  <Tab title="Product ID watch">
    Watch two products and trigger when the price drops by 10% or the item goes on sale.

    ```bash theme={null}
    curl --request POST \
      --url 'https://api.affiliate.com/v1/products/watches' \
      --header 'Authorization: Bearer {your_api_key}' \
      --header 'Content-Type: application/json' \
      --data '{
        "name": "Nike Shoe Price Drop Watch",
        "target_type": "product",
        "target_ids": [
          "9200-us-B01AFOIO3K",
          "8413578780281943353"
        ],
        "status": "active",
        "rules": [
          {
            "field": "final_price",
            "condition": "decrease",
            "start_value": 199.99,
            "threshold": {
              "type": "percentage",
              "value": 10
            }
          },
          {
            "field": "on_sale",
            "condition": "equals",
            "threshold": {
              "type": "value",
              "value": true
            }
          }
        ],
        "notifications": [
          {
            "channel": "webhook",
            "target": "https://example.com/webhooks/watch",
            "frequency": "immediately"
          }
        ],
        "filters": [
          {
            "field": "merchant.id",
            "operator": "=",
            "value": "41357"
          }
        ],
        "metadata": {
          "campaign": "summer_sale",
          "priority": "high"
        },
        "expire_timestamp": 1774751812
      }'
    ```
  </Tab>

  <Tab title="ASIN watch">
    Watch two Amazon ASINs and trigger when the price decreases by 50% from the provided `start_value`.

    ```bash theme={null}
    curl --request POST \
      --url 'https://api.affiliate.com/v1/products/watches' \
      --header 'Authorization: Bearer {your_api_key}' \
      --header 'Content-Type: application/json' \
      --data '{
        "name": "Amazon Product Price Watch",
        "target_type": "asin",
        "target_ids": [
          "B01AFOIO3K",
          "B09J1TB35S"
        ],
        "status": "active",
        "rules": [
          {
            "field": "final_price",
            "condition": "decrease",
            "start_value": 123.99,
            "threshold": {
              "type": "percentage",
              "value": 50
            }
          }
        ],
        "notifications": [
          {
            "channel": "webhook",
            "target": "https://example.com/webhooks/watch",
            "frequency": "immediately"
          }
        ],
        "metadata": {
          "campaign": "amazon_deals"
        },
        "expire_timestamp": 1764822840,
        "networks": {
          "amazon": {
            "credential_id": "{your_credential_id}",
            "credential_secret": "{your_credential_secret}",
            "partner_tag": "{your_partner_tag}",
            "locale": "US"
          }
        }
      }'
    ```
  </Tab>

  <Tab title="Barcode watch">
    Watch a single barcode across all merchants and trigger when the price drops by 10%.

    ```bash theme={null}
    curl --request POST \
      --url 'https://api.affiliate.com/v1/products/watches' \
      --header 'Authorization: Bearer {your_api_key}' \
      --header 'Content-Type: application/json' \
      --data '{
        "name": "Nike Shoe Barcode Price Drop Watch",
        "target_type": "barcode",
        "target_ids": [
          "6947681533400"
        ],
        "status": "active",
        "rules": [
          {
            "field": "final_price",
            "condition": "decrease",
            "threshold": {
              "type": "percentage",
              "value": 10
            }
          }
        ],
        "notifications": [
          {
            "channel": "webhook",
            "target": "https://example.com/webhooks/watch",
            "frequency": "immediately"
          }
        ],
        "filters": [
          {
            "field": "merchant.id",
            "operator": "=",
            "value": "138553"
          }
        ],
        "metadata": {
          "category": "footwear"
        },
        "expire_timestamp": 1764822840
      }'
    ```
  </Tab>
</Tabs>

## Webhook verification

When you create a watch with a `"webhook"` notification channel, the API immediately sends a test POST request to your endpoint to verify it is accessible. Your endpoint must return a `2xx` HTTP status code. If verification fails, the watch creation is rejected.

The test payload has the same structure as a real notification:

```json theme={null}
{
  "watch_history_id": "uuid-uuid-uuid-uuid",
  "watch_event_type": "product_watch_alert",
  "timestamp": "2026-01-02T19:18:50+00:00",
  "watch_id": "uuid-uuid-uuid-uuid",
  "watch_name": "Test Watch",
  "metadata": {
    "campaign": "summer_sale"
  },
  "details": [
    {
      "id": "abc-123456789",
      "network": {
        "id": 335,
        "name": "Impact US"
      },
      "merchant": {
        "id": 54419,
        "name": "Target"
      },
      "changes": [
        {
          "field": "final_price",
          "old_value": 199,
          "new_value": 149
        }
      ]
    }
  ]
}
```

## Response

A successful request returns `200 OK` with a list of all your active watches, including the one just created.

```json theme={null}
{
  "meta": {
    "total": 2,
    "from": 1,
    "to": 2,
    "current_page": 1,
    "last_page": 1,
    "per_page": 100,
    "fields": [],
    "trace_id": "0195cedc-b193-7096-8df4-e7104abf799d"
  },
  "data": [
    {
      "watch_id": "9e84ce37-63be-41cf-87ef-72465fb8ead2",
      "name": "Nike Shoe Price Drop Watch",
      "target_type": "product",
      "target_id": "9200-us-B01AFOIO3K",
      "status": "active",
      "metadata": {
        "campaign": "summer_sale",
        "priority": "high"
      },
      "rules": [
        {
          "field": "final_price",
          "start_value": 199.99,
          "condition": "decrease",
          "threshold": {
            "type": "percentage",
            "value": 10
          }
        }
      ],
      "notifications": [
        {
          "channel": "webhook",
          "channel_target": "https://example.com/webhooks/watch",
          "frequency": "immediately",
          "enabled": true
        }
      ],
      "filters": [
        {
          "field": "merchant.id",
          "operator": "=",
          "value": "41357"
        }
      ],
      "expire_timestamp": 1774751812
    }
  ]
}
```

<Warning>
  For ASIN watches, `start_value` is required for every rule. If you omit it, `start_value` will be `null` and the watch will never trigger — the API has no baseline to compare against.
</Warning>

<Warning>
  Filters are not allowed for ASIN watches. Including a `filters` array in an ASIN watch request causes an error.
</Warning>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.

---

# GET /v1/products/watches — list your product watches

Source: https://guides.affiliate.com/api-reference/watches/list-watches.md

> ## 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.

# GET /v1/products/watches — list your product watches

> Retrieve all product watches on your account, with optional metadata filtering and pagination to narrow results to a specific campaign or category.

The `GET /v1/products/watches` endpoint returns all product watches configured on your account. You can paginate through results and filter by any metadata key-value pair you attached to your watches at creation time.

## Endpoint

```
GET /v1/products/watches
```

## Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication. Format: `Bearer {your_api_key}`.
</ParamField>

## Query parameters

<ParamField query="page" type="integer" default="1">
  The page number to return.
</ParamField>

<ParamField query="per_page" type="integer" default="100">
  The number of watches to return per page.
</ParamField>

<ParamField query="metadata[{key}]" type="string">
  Filter watches by a metadata key-value pair. Replace `{key}` with your custom metadata key. You can include multiple metadata filters in a single request.

  Examples:

  * `?metadata[campaign]=summer_sale`
  * `?metadata[campaign]=summer_sale&metadata[priority]=high`
  * `?metadata[category]=electronics`
</ParamField>

## Example requests

List all watches:

```bash theme={null}
curl --request GET \
  --url 'https://api.affiliate.com/v1/products/watches' \
  --header 'Authorization: Bearer {your_api_key}'
```

Filter by metadata:

```bash theme={null}
curl --request GET \
  --url 'https://api.affiliate.com/v1/products/watches?metadata[campaign]=summer_sale&metadata[priority]=high' \
  --header 'Authorization: Bearer {your_api_key}'
```

## Response

```json theme={null}
{
  "meta": {
    "total": 2,
    "from": 1,
    "to": 2,
    "current_page": 1,
    "last_page": 1,
    "per_page": 100,
    "fields": [],
    "trace_id": "0195cedc-b193-7096-8df4-e7104abf799d"
  },
  "data": [
    {
      "watch_id": "9e84ce37-63be-41cf-87ef-72465fb8ead2",
      "name": "Smart Home Price Drop Watch",
      "target_type": "product",
      "target_id": "1301920351976391947",
      "status": "active",
      "metadata": {
        "category": "electronics",
        "campaign": "summer_sale"
      },
      "rules": [
        {
          "field": "final_price",
          "start_value": 9840,
          "condition": "decrease",
          "threshold": {
            "type": "percentage",
            "value": 15
          }
        },
        {
          "field": "on_sale",
          "start_value": null,
          "condition": "equals",
          "threshold": {
            "type": "value",
            "value": true
          }
        }
      ],
      "notifications": [
        {
          "channel": "webhook",
          "channel_target": "https://example.com/webhooks/watch",
          "frequency": "immediately",
          "enabled": true
        }
      ]
    },
    {
      "watch_id": "9e84ce38-336e-4923-aa55-d23630684e04",
      "name": "Nike Shoe Price Drop Watch",
      "target_id": "1062900034486247121",
      "status": "active",
      "metadata": {
        "category": "footwear",
        "campaign": "summer_sale"
      },
      "rules": [
        {
          "field": "final_price",
          "start_value": 8000,
          "condition": "decrease",
          "threshold": {
            "type": "percentage",
            "value": 10
          }
        }
      ],
      "notifications": [
        {
          "channel": "webhook",
          "channel_target": "https://example.com/webhooks/watch",
          "frequency": "immediately",
          "enabled": true
        }
      ],
      "filters": [],
      "expire_timestamp": 1774751812
    }
  ]
}
```

## Response fields

### `meta` object

<ResponseField name="meta.total" type="integer">
  Total number of watches matching the query.
</ResponseField>

<ResponseField name="meta.from" type="integer">
  Index of the first watch on the current page.
</ResponseField>

<ResponseField name="meta.to" type="integer">
  Index of the last watch on the current page.
</ResponseField>

<ResponseField name="meta.current_page" type="integer">
  The current page number.
</ResponseField>

<ResponseField name="meta.last_page" type="integer">
  The total number of pages.
</ResponseField>

<ResponseField name="meta.per_page" type="integer">
  The number of records per page.
</ResponseField>

<ResponseField name="meta.trace_id" type="string">
  Unique identifier for this request. Include this value when contacting support.
</ResponseField>

### Watch object (`data[]`)

<ResponseField name="watch_id" type="string">
  The unique identifier for the watch. Use this value in path parameters for GET, PUT, and DELETE requests.
</ResponseField>

<ResponseField name="name" type="string">
  The human-readable name you assigned when creating the watch.
</ResponseField>

<ResponseField name="target_type" type="string">
  The watch type: `"product"`, `"asin"`, or `"barcode"`.
</ResponseField>

<ResponseField name="target_id" type="string">
  The product identifier being watched. For multi-target watches, individual watch objects are returned per target.
</ResponseField>

<ResponseField name="status" type="string">
  Current watch status: `"active"`, `"paused"`, or `"completed"`. A watch becomes `"completed"` after its rule is met.
</ResponseField>

<ResponseField name="metadata" type="object">
  The custom key-value pairs attached to the watch.
</ResponseField>

<ResponseField name="rules" type="object[]">
  The rules that trigger a notification. See the [overview](/api-reference/watches/overview#rule-types-and-conditions) for field and condition details.
</ResponseField>

<ResponseField name="notifications" type="object[]">
  The configured notification channels.

  <Expandable title="Notification object">
    <ResponseField name="channel" type="string">
      The notification channel. Currently always `"webhook"`.
    </ResponseField>

    <ResponseField name="channel_target" type="string">
      The webhook URL configured for this watch.
    </ResponseField>

    <ResponseField name="frequency" type="string">
      Notification frequency. Currently always `"immediately"`.
    </ResponseField>

    <ResponseField name="enabled" type="boolean">
      Whether the notification channel is currently active.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="filters" type="object[]">
  Any filters limiting which product listings can trigger the watch. Absent if no filters were set.
</ResponseField>

<ResponseField name="expire_timestamp" type="integer">
  UNIX timestamp of when the watch expires. Absent if the watch uses the default 90-day expiration.
</ResponseField>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.

---

# GET /v1/products/watches/{watch_id} — get a watch

Source: https://guides.affiliate.com/api-reference/watches/get-watch.md

> ## 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.

# GET /v1/products/watches/{watch_id} — get a watch

> Retrieve a single product watch by its ID, including its rules, filters, notification settings, expiration timestamp, and last check time.

The `GET /v1/products/watches/{watch_id}` endpoint returns the full details of a single product watch. You can also retrieve watches by metadata without knowing the watch ID — see [query by metadata](#query-by-metadata) below.

## Endpoint

```
GET /v1/products/watches/{watch_id}
```

## Path parameters

<ParamField path="watch_id" type="string" required>
  The unique identifier of the watch to retrieve. You can find this value in the `watch_id` field returned by list, create, or update responses.
</ParamField>

## Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication. Format: `Bearer {your_api_key}`.
</ParamField>

## Example request

```bash theme={null}
curl --request GET \
  --url 'https://api.affiliate.com/v1/products/watches/a0b49c91-2eef-4aa1-9b30-4816147680f0' \
  --header 'Authorization: Bearer {your_api_key}'
```

## Response

```json theme={null}
{
  "data": {
    "watch_id": "a0b49c91-2eef-4aa1-9b30-4816147680f0",
    "name": "Nike Shoe Price Drop Watch",
    "target_type": "product",
    "target_id": "8099987467386791069",
    "status": "active",
    "metadata": {
      "key1": "value1",
      "campaign": "summer_sale"
    },
    "rules": [
      {
        "field": "final_price",
        "start_value": 199.99,
        "condition": "decrease",
        "threshold": {
          "type": "percentage",
          "value": 50
        }
      }
    ],
    "notifications": [
      {
        "channel": "webhook",
        "channel_target": "https://example.com/webhooks/watch",
        "frequency": "immediately",
        "enabled": true
      }
    ],
    "filters": [
      {
        "field": "merchant.id",
        "operator": "=",
        "value": "41357"
      }
    ],
    "expire_timestamp": 1774751812,
    "created_at": "2025-12-29 02:36:53",
    "last_checked_at": null
  },
  "meta": {
    "trace_id": "019b74ed-15fe-72f5-a0c8-26727cbc0285"
  }
}
```

## Response fields

### `data` object

<ResponseField name="watch_id" type="string">
  The unique identifier for this watch.
</ResponseField>

<ResponseField name="name" type="string">
  The human-readable name assigned at creation.
</ResponseField>

<ResponseField name="target_type" type="string">
  The watch type: `"product"`, `"asin"`, or `"barcode"`.
</ResponseField>

<ResponseField name="target_id" type="string">
  The product identifier being watched.
</ResponseField>

<ResponseField name="status" type="string">
  Current watch status: `"active"`, `"paused"`, or `"completed"`. A watch becomes `"completed"` when a rule condition is met.
</ResponseField>

<ResponseField name="metadata" type="object">
  Custom key-value pairs attached to the watch.
</ResponseField>

<ResponseField name="rules" type="object[]">
  The conditions that trigger a notification.

  <Expandable title="Rule object">
    <ResponseField name="field" type="string">
      The product attribute being monitored.
    </ResponseField>

    <ResponseField name="start_value" type="number | null">
      The baseline value at the time the watch was created. `null` if no baseline was captured yet.
    </ResponseField>

    <ResponseField name="condition" type="string">
      The comparison condition, such as `"decrease"`, `"equals"`, or `"change"`.
    </ResponseField>

    <ResponseField name="threshold" type="object">
      The magnitude of change required. `type` is `"value"` or `"percentage"`; `value` is the numeric or string threshold.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="notifications" type="object[]">
  The configured notification channels.

  <Expandable title="Notification object">
    <ResponseField name="channel" type="string">
      The notification channel. Currently always `"webhook"`.
    </ResponseField>

    <ResponseField name="channel_target" type="string">
      The webhook URL.
    </ResponseField>

    <ResponseField name="frequency" type="string">
      Notification frequency. Currently always `"immediately"`.
    </ResponseField>

    <ResponseField name="enabled" type="boolean">
      Whether the notification channel is active.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="filters" type="object[]">
  Filters limiting which product listings can trigger the watch. Each object has `field`, `operator`, and `value` properties.
</ResponseField>

<ResponseField name="expire_timestamp" type="integer">
  UNIX timestamp of when the watch expires.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 datetime when the watch was created.
</ResponseField>

<ResponseField name="last_checked_at" type="string | null">
  ISO 8601 datetime of the most recent check. `null` if the watch has not been checked yet.
</ResponseField>

### `meta` object

<ResponseField name="meta.trace_id" type="string">
  Unique identifier for this request. Include this value when contacting support.
</ResponseField>

## Query by metadata

If you tagged your watches with metadata at creation, you can retrieve them without knowing the watch ID. Use the same `GET /v1/products/watches` endpoint with `metadata[key]=value` query parameters.

```
GET /v1/products/watches?metadata[campaign]=summer_sale
```

You can combine multiple metadata filters:

```
GET /v1/products/watches?metadata[campaign]=summer_sale&metadata[priority]=high
```

### Example

```bash theme={null}
curl --request GET \
  --url 'https://api.affiliate.com/v1/products/watches?metadata[campaign]=summer_sale' \
  --header 'Authorization: Bearer {your_api_key}'
```

The response uses the same paginated format as [list watches](/api-reference/watches/list-watches).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.

---

# PUT /v1/products/watches/{id} — update a watch

Source: https://guides.affiliate.com/api-reference/watches/update-watch.md

> ## 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.

# PUT /v1/products/watches/{id} — update a watch

> Update an existing product watch to change its rules, webhook target, filters, or status — including reactivating a completed or expired watch.

The `PUT /v1/products/watches/{watch_id}` endpoint replaces the configuration of an existing watch with the values you provide. The request body format is identical to `POST /v1/products/watches`. Use this endpoint to change rules, update your webhook URL, add filters, or renew a watch that has expired or completed.

## Endpoint

```
PUT /v1/products/watches/{watch_id}
```

## Path parameters

<ParamField path="watch_id" type="string" required>
  The unique identifier of the watch to update.
</ParamField>

## Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication. Format: `Bearer {your_api_key}`.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`.
</ParamField>

## Request body

The request body follows the same structure as [Create Watch](/api-reference/watches/create-watch#request-body). All fields you include replace the existing values; omitted optional fields revert to defaults.

## Example request

Reactivate a completed watch with a new price rule and extended expiration:

```bash theme={null}
curl --request PUT \
  --url 'https://api.affiliate.com/v1/products/watches/9e84ce37-63be-41cf-87ef-72465fb8ead2' \
  --header 'Authorization: Bearer {your_api_key}' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Smart Home Price Alert",
    "target_type": "product",
    "target_ids": [
      "1301920351976391947"
    ],
    "status": "active",
    "rules": [
      {
        "field": "final_price",
        "condition": "decrease",
        "threshold": {
          "type": "percentage",
          "value": 20
        }
      },
      {
        "field": "on_sale",
        "condition": "equals",
        "threshold": {
          "type": "value",
          "value": true
        }
      }
    ],
    "notifications": [
      {
        "channel": "webhook",
        "target": "https://example.com/api/callback",
        "frequency": "immediately"
      }
    ],
    "metadata": {
      "category": "electronics",
      "priority": "high"
    },
    "expire_timestamp": 1806288000
  }'
```

## Response

A successful update returns `200 OK` with the updated watch list in the same paginated format as [list watches](/api-reference/watches/list-watches).

```json theme={null}
{
  "meta": {
    "total": 1,
    "from": 1,
    "to": 1,
    "current_page": 1,
    "last_page": 1,
    "per_page": 100,
    "fields": [],
    "trace_id": "f12a3d45-6b78-90c1-2d3e-4f5678901234"
  },
  "data": [
    {
      "watch_id": "9e84ce37-63be-41cf-87ef-72465fb8ead2",
      "name": "Smart Home Price Alert",
      "target_type": "product",
      "target_id": "1301920351976391947",
      "status": "active",
      "metadata": {
        "category": "electronics",
        "priority": "high"
      },
      "rules": [
        {
          "field": "final_price",
          "start_value": null,
          "condition": "decrease",
          "threshold": {
            "type": "percentage",
            "value": 20
          }
        },
        {
          "field": "on_sale",
          "start_value": null,
          "condition": "equals",
          "threshold": {
            "type": "value",
            "value": true
          }
        }
      ],
      "notifications": [
        {
          "channel": "webhook",
          "channel_target": "https://example.com/api/callback",
          "frequency": "immediately",
          "enabled": true
        }
      ]
    }
  ]
}
```

<Note>
  To renew a watch that has expired or completed, set `status: "active"` and supply a new `expire_timestamp` no more than 180 days from the current time. The watch resumes checking on the next 6-hour cycle.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.

---

# DELETE /v1/products/watches/{id} — delete a watch

Source: https://guides.affiliate.com/api-reference/watches/delete-watch.md

> ## 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.

# DELETE /v1/products/watches/{id} — delete a watch

> Permanently delete a product watch by its ID. The watch stops checking immediately and you will no longer receive notifications for it.

The `DELETE /v1/products/watches/{watch_id}` endpoint permanently removes a product watch. Once deleted, the watch stops checking immediately and no further notifications are sent. This action cannot be undone — to stop monitoring temporarily, update the watch status to `"paused"` instead.

## Endpoint

```
DELETE /v1/products/watches/{watch_id}
```

## Path parameters

<ParamField path="watch_id" type="string" required>
  The unique identifier of the watch to delete.
</ParamField>

## Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication. Format: `Bearer {your_api_key}`.
</ParamField>

## Example request

```bash theme={null}
curl --request DELETE \
  --url 'https://api.affiliate.com/v1/products/watches/a0b49c91-2eef-4aa1-9b30-4816147680f0' \
  --header 'Authorization: Bearer {your_api_key}'
```

## Response

A successful deletion returns `200 OK` with confirmation of the deleted watch ID.

```json theme={null}
{
  "status": "deleted",
  "watch_id": "a0b49c91-2eef-4aa1-9b30-4816147680f0",
  "meta": {
    "trace_id": "d1e2f3g4-5h6i-7j8k-9l0m-1n2o3p4q5r6"
  }
}
```

## Response fields

<ResponseField name="status" type="string">
  Confirmation string. Always `"deleted"` on a successful request.
</ResponseField>

<ResponseField name="watch_id" type="string">
  The ID of the watch that was deleted.
</ResponseField>

<ResponseField name="meta.trace_id" type="string">
  Unique identifier for this request. Include this value when contacting support.
</ResponseField>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.

---

# Product watch notification history and webhooks

Source: https://guides.affiliate.com/api-reference/watches/notification-history.md

> ## 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.

# Product watch notification history and webhooks

> Retrieve the notification history for your product watches and understand the webhook payload formats for price changes, unavailability, and expiration.

The Product Watch API provides two endpoints for retrieving notification history, plus details on the webhook payloads your server receives when rules trigger. Use the history endpoints to audit past notifications or replay missed events.

## History endpoints

### Get history for a specific watch

Retrieve all notifications sent for a single watch by its ID.

```
GET /v1/products/watches/{watch_id}/histories
```

<ParamField path="watch_id" type="string" required>
  The unique identifier of the watch.
</ParamField>

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication. Format: `Bearer {your_api_key}`.
</ParamField>

```bash theme={null}
curl --request GET \
  --url 'https://api.affiliate.com/v1/products/watches/9e838778-c642-4461-b8d8-bcab87889a91/histories' \
  --header 'Authorization: Bearer {your_api_key}'
```

**Response**

```json theme={null}
{
  "watch_id": "9e838778-c642-4461-b8d8-bcab87889a91",
  "name": "Nike Shoe Price Drop Watch",
  "target_id": "8099982740095203709",
  "histories": [
    {
      "watch_id": "9e838778-c642-4461-b8d8-bcab87889a91",
      "id": "a123b456-c789-4d0e-f123-456789abwxyz",
      "changes": [
        {
          "field": "final_price",
          "old_value": 199,
          "new_value": 149
        }
      ],
      "notified_at": "2025-02-19T15:30:45Z"
    }
  ],
  "meta": {
    "total_events": 1,
    "page_size": 15,
    "page": 1,
    "trace_id": "0195ce1a-6899-70ab-b213-738733bb8b08"
  }
}
```

### Get history filtered by metadata

Retrieve notifications across watches that share a metadata key-value pair. At least one `metadata` parameter is required for this endpoint.

```
GET /v1/products/watches/histories?metadata[{key}]={value}
```

<ParamField query="metadata[{key}]" type="string" required>
  Filter by metadata key-value pair. At least one metadata parameter is required. You can combine multiple pairs in a single request.

  Examples:

  * `?metadata[campaign]=summer_sale`
  * `?metadata[campaign]=summer_sale&metadata[priority]=high`
</ParamField>

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication. Format: `Bearer {your_api_key}`.
</ParamField>

```bash theme={null}
curl --request GET \
  --url 'https://api.affiliate.com/v1/products/watches/histories?metadata[campaign]=summer_sale' \
  --header 'Authorization: Bearer {your_api_key}'
```

**Response**

```json theme={null}
{
  "meta": {
    "total": 1,
    "from": 1,
    "to": 1,
    "current_page": 1,
    "last_page": 1,
    "per_page": 20,
    "trace_id": "f12a3d45-6b78-90c1-2d3e-4f5678901234"
  },
  "data": [
    {
      "watch_id": "a123b456-c789-4d0e-f123-456789abcdef",
      "id": "a123b456-c789-4d0e-f123-456789abwxyz",
      "changes": [
        {
          "field": "final_price",
          "old_value": 199.00,
          "new_value": 149.00
        }
      ],
      "notified_at": "2025-02-19T15:30:45Z"
    }
  ]
}
```

## Webhook notification formats

When a rule triggers, the API sends an HTTP POST request to the webhook URL you configured. Your endpoint should respond with a `2xx` status code.

### Standard product change notification

Sent when a watch rule is triggered by a product field change such as a price drop or sale status update.

```json theme={null}
{
  "watch_history_id": "a0c88d4d-8c49-4257-be33-e7fe8e3b019c",
  "watch_event_type": "product_watch_alert",
  "timestamp": "2026-01-08T00:30:45+00:00",
  "watch_id": "a0c88cfc-7f54-4384-8bde-3f588d703a57",
  "watch_name": "Price Drop Alert Watch",
  "metadata": {
    "key1": "test-campaign"
  },
  "details": [
    {
      "id": "9200-us-B08HC1N3K1",
      "name": "DIFF Reading glasses for Women, Lightweight Oversized Readers",
      "network": {
        "id": 9200,
        "name": "Example Network"
      },
      "merchant": {
        "id": 921239,
        "name": "DIFF Eyewear"
      },
      "changes": [
        {
          "field": "final_price",
          "old_value": "999",
          "new_value": 31.99
        }
      ]
    }
  ]
}
```

### Product unavailable notification

Sent when a watched product is removed from the Affiliate.com database. The watch is automatically deleted after this notification. The `field` value `"__product__"` indicates a watch-level event rather than a product field change.

```json theme={null}
{
  "watch_history_id": "a0c8850f-a945-461e-8cb4-8b022bb6858f",
  "watch_event_type": "product_watch_alert",
  "timestamp": "2026-01-08T00:07:43+00:00",
  "watch_id": "a0c884a5-48e1-48cc-9eb1-ea767df2eb79",
  "watch_name": "Price Drop Alert Watch",
  "metadata": {
    "key1": "test-campaign"
  },
  "details": [
    {
      "id": "9200-us-B0CGKLGRPT",
      "name": "Unknown",
      "network": {
        "id": null,
        "name": "Unknown"
      },
      "merchant": {
        "id": null,
        "name": "Unknown"
      },
      "changes": [
        {
          "field": "__product__",
          "old_value": "available",
          "new_value": "unavailable"
        }
      ]
    }
  ]
}
```

### Watch expiration notification

Sent when a watch reaches its `expire_timestamp`. The `field` value `"__watch__"` indicates a watch status change. After receiving this notification, create a new watch or use the PUT endpoint to update `expire_timestamp` if you want to continue monitoring.

```json theme={null}
{
  "watch_history_id": "a0bea68c-f6ae-4b0a-a980-e6a7cab53c93",
  "watch_event_type": "product_watch_alert",
  "timestamp": "2026-01-03T02:23:06.000000Z",
  "watch_id": "a0bdafe6-1ce0-48a0-9085-b2efc2178a98",
  "watch_name": "Nike Shoe Price Drop Watch",
  "target_id": "39800028808",
  "changes": [
    {
      "field": "__watch__",
      "new_value": "expired",
      "old_value": "active"
    }
  ],
  "metadata": {
    "key1": "value1",
    "campaign": "summer_sale"
  }
}
```

## Metadata in webhooks

Every webhook notification includes the `metadata` object from the watch. This lets you route and process notifications programmatically using the tags you applied at watch creation — for example, dispatch notifications by `campaign`, `priority`, or any other dimension you track.

<Note>
  After you receive an expiration notification, the watch stops checking. To continue monitoring, call the PUT endpoint with `status: "active"` and a new `expire_timestamp`, or create a new watch.
</Note>

## Response fields

### Single-watch history response

<ResponseField name="watch_id" type="string">
  The ID of the watch these histories belong to.
</ResponseField>

<ResponseField name="name" type="string">
  The name of the watch.
</ResponseField>

<ResponseField name="target_id" type="string">
  The product identifier being watched.
</ResponseField>

<ResponseField name="histories" type="object[]">
  Array of notification history records.

  <Expandable title="History record">
    <ResponseField name="id" type="string">
      Unique identifier for this history record.
    </ResponseField>

    <ResponseField name="watch_id" type="string">
      The watch this record belongs to.
    </ResponseField>

    <ResponseField name="changes" type="object[]">
      The field changes that triggered the notification. Each object has `field`, `old_value`, and `new_value`.
    </ResponseField>

    <ResponseField name="notified_at" type="string">
      ISO 8601 datetime when the notification was sent.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.total_events" type="integer">
  Total number of notification events for this watch.
</ResponseField>

<ResponseField name="meta.page_size" type="integer">
  Number of history records per page.
</ResponseField>

<ResponseField name="meta.page" type="integer">
  Current page number.
</ResponseField>

<ResponseField name="meta.trace_id" type="string">
  Unique identifier for this request.
</ResponseField>

### Metadata-filtered history response

The metadata-filtered history endpoint returns a paginated list where each `data` item is a history record. The `meta` object includes `total`, `from`, `to`, `current_page`, `last_page`, `per_page`, and `trace_id` fields following the standard paginated envelope.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.

---

## Product Lists

---

# Product Lists API: save and manage product sets

Source: https://guides.affiliate.com/api-reference/lists/overview.md

> ## 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.

# Product Lists API: save and manage product sets

> Store named product collections in Affiliate.com without managing your own database. Tag lists with metadata and retrieve full product data on demand.

The Product Lists API lets you persist curated sets of product IDs in Affiliate.com's infrastructure and retrieve them — along with live product data — at any time. You don't need to run your own database to save, label, or share product collections.

## What you can do with Product Lists

* **Save search results** — run a product search, then persist the result IDs to a named list for later use.
* **Curate editorial collections** — build hand-picked sets for landing pages, gift guides, or seasonal promotions.
* **Power recommendation widgets** — store personalised or algorithmic product sets and fetch fresh product data on each page load.
* **Share product sets** — create lists scoped to a campaign or category and retrieve them by metadata key:value pairs.

## Metadata

Every list supports up to **16 key:value pairs** of metadata that you define. You can use metadata to label lists by campaign, category, author, season, or any other dimension that matters to your application.

* Key maximum length: **64 characters**
* Value maximum length: **512 characters**
* Filter by metadata at query time using `?metadata[key]=value`

```
GET /v1/products/lists?metadata[category]=tech_products&metadata[campaign]=summer
```

Metadata values are returned in every list response so you can use them programmatically.

## How list contents work

A list stores **product IDs**. Retrieving a list with `GET /v1/products/lists/{list_id}` returns the current full product objects for each stored ID — prices, availability, images, affiliate URLs, and all other fields — reflecting the latest data from the merchant feed.

<Note>
  `GET /v1/products/lists` returns list summaries only: name, `products_count`, and metadata. It does **not** return product details. Use `GET /v1/products/lists/{list_id}` to retrieve the full product data for a specific list.
</Note>

## Available endpoints

| Method | Endpoint | Description |
| - | - | - |
| `POST` | `/v1/products/lists` | Create a new list with products |
| `GET` | `/v1/products/lists` | Get all your lists (summaries only) |
| `GET` | `/v1/products/lists/{list_id}` | Get a single list with full product data |
| `GET` | `/v1/products/lists?metadata[key]=value` | Filter lists by metadata |
| `POST` | `/v1/products/lists/{list_id}/items` | Add products to an existing list |
| `DELETE` | `/v1/products/lists/{list_id}/products` | Remove products from a list |
| `DELETE` | `/v1/products/lists/{list_id}` | Permanently delete a list |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.

---

# POST /v1/products/lists — create a product list

Source: https://guides.affiliate.com/api-reference/lists/create-list.md

> ## 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 /v1/products/lists — create a product list

> Create a named product list with one or more product IDs and optional metadata. Returns the new list ID and full product objects for every product added.

Use `POST /v1/products/lists` to create a new product list. Provide a name, one or more product IDs, and any metadata key:value pairs you want to associate with the list. The response returns the new list ID together with full product objects for every product you included.

## Request

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

### Headers

<ParamField header="Authorization" type="string" required>
  Your API key as a Bearer token: `Bearer {your_api_key}`.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`.
</ParamField>

### Body parameters

<ParamField body="name" type="string" required>
  A display name for the list. Use something meaningful to your application — for example, `"Smart Home Devices"` or `"Summer Campaign Q3"`.
</ParamField>

<ParamField body="product_ids" type="string[]" required>
  An array of product ID strings to include in the list. Product IDs come from the Products API search results.
</ParamField>

<ParamField body="metadata" type="object">
  Up to 16 key:value string pairs you can use to label and query this list. Keys are max 64 characters; values are max 512 characters.

  ```json theme={null}
  {
    "metadata": {
      "category": "tech_products",
      "campaign": "summer"
    }
  }
  ```
</ParamField>

<ParamField body="pool_id" type="integer">
  Optional pool identifier to scope the list within a specific product pool.
</ParamField>

## Example request

```bash cURL theme={null}
curl --request POST \
  --url https://api.affiliate.com/v1/products/lists \
  --header 'Authorization: Bearer {your_api_key}' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Smart Home Devices",
    "product_ids": [
      "1234567890123456789",
      "2345678901234567890"
    ],
    "metadata": {
      "category": "tech_products"
    },
    "pool_id": 456
  }'
```

## Response

A `201 Created` response contains a `data` object with the new list and full product details, plus a `meta` object with a trace ID.

```json theme={null}
{
  "data": {
    "id": "d345e67f-89g0-1h2i-3j45-6k7891lm2345",
    "name": "Smart Home Devices",
    "metadata": {
      "category": "tech_products"
    },
    "products_count": 2,
    "products": [
      {
        "id": "1234567890123456789",
        "barcode": 123456,
        "name": "Smart Thermostat Pro",
        "description": "Wi-Fi enabled thermostat with voice control",
        "commission_url": "https://www.example-affiliate.net/click-123-456789?url=https%3A%2F%2Fwww.example-store.com%2Fproducts%2Fsmart-thermostat-pro",
        "direct_url": "https://www.example-store.com/products/smart-thermostat-pro",
        "image_url": "https://assets.example-store.com/images/products/thermostat-pro.jpg",
        "currency": "USD",
        "regular_price": 129.99,
        "final_price": 99.99,
        "on_sale": true,
        "sale_discount": 23,
        "availability": "In Stock",
        "sku": 123456,
        "brand": "SmartHome",
        "category": "Home & Garden > Smart Home > Climate Control",
        "network": {
          "id": 5,
          "name": "AffiliateNetwork",
          "logo_url": "https://img.affiliate.com/logos/networks/5/logo.png"
        },
        "merchant": {
          "id": 1234,
          "name": "Example Store",
          "logo_url": "https://img.affiliate.com/logos/merchants/1234/logo.png"
        }
      },
      {
        "id": "2345678901234567890",
        "barcode": 123456,
        "name": "Smart Security Camera",
        "description": "1080p HD security camera with night vision",
        "commission_url": "https://www.example-affiliate.net/click-123-456789?url=https%3A%2F%2Fwww.example-store.com%2Fproducts%2Fsmart-security-camera",
        "direct_url": "https://www.example-store.com/products/smart-security-camera",
        "image_url": "https://assets.example-store.com/images/products/security-camera.jpg",
        "currency": "USD",
        "regular_price": 89.99,
        "final_price": 89.99,
        "on_sale": false,
        "sale_discount": 0,
        "availability": "In Stock",
        "sku": 123456,
        "brand": "SecureTech",
        "category": "Home & Garden > Smart Home > Security",
        "network": {
          "id": 5,
          "name": "AffiliateNetwork",
          "logo_url": "https://img.affiliate.com/logos/networks/5/logo.png"
        },
        "merchant": {
          "id": 1234,
          "name": "Example Store",
          "logo_url": "https://img.affiliate.com/logos/merchants/1234/logo.png"
        }
      }
    ]
  },
  "meta": {
    "trace_id": "a98b7c65-4d32-1e0f-9g87-6h5432i10j9k"
  }
}
```

### Response fields

<ResponseField name="data" type="object">
  The newly created list object.

  <Expandable title="data properties">
    <ResponseField name="data.id" type="string">
      Unique identifier for the list. Use this ID to retrieve, update, or delete the list.
    </ResponseField>

    <ResponseField name="data.name" type="string">
      The display name you provided when creating the list.
    </ResponseField>

    <ResponseField name="data.metadata" type="object">
      The key:value metadata pairs you provided, returned as a JSON object.
    </ResponseField>

    <ResponseField name="data.products_count" type="integer">
      Total number of products currently in the list.
    </ResponseField>

    <ResponseField name="data.products" type="array">
      Full product objects for each product in the list. See the product fields table below.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  <Expandable title="meta properties">
    <ResponseField name="meta.trace_id" type="string">
      A unique identifier for this request. Include this value when contacting support.
    </ResponseField>
  </Expandable>
</ResponseField>

### Product object fields

Each item in `data.products` contains the following fields.

| Field | Type | Description |
| - | - | - |
| `id` | string | Unique product identifier |
| `barcode` | integer | UPC, EAN, or GTIN barcode |
| `name` | string | Product title |
| `description` | string | Full product description |
| `commission_url` | string | Affiliate URL — earn commission when customers purchase through this link |
| `direct_url` | string | Direct merchant URL (no commission) |
| `image_url` | string | Primary product image URL |
| `currency` | string | ISO 4217 currency code (e.g., `USD`) |
| `regular_price` | number | Original retail price |
| `final_price` | number | Current price after any discounts |
| `on_sale` | boolean | `true` when a sale discount is active |
| `sale_discount` | integer | Discount percentage |
| `availability` | string | Stock status (e.g., `In Stock`) |
| `sku` | integer | Merchant stock-keeping unit |
| `brand` | string | Brand name |
| `category` | string | Hierarchical category path |
| `network.id` | integer | Affiliate network ID |
| `network.name` | string | Affiliate network 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 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.

---

# GET /v1/products/lists — retrieve your product lists

Source: https://guides.affiliate.com/api-reference/lists/get-lists.md

> ## 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.

# GET /v1/products/lists — retrieve your product lists

> Retrieve all product lists for your API key. Filter by metadata key:value pairs to find specific lists. Returns list summaries, not full product data.

Use `GET /v1/products/lists` to retrieve all product lists associated with your API key. You can optionally filter the results by one or more metadata key:value pairs. The response includes list summaries — name, `products_count`, and metadata — but not the individual product details.

<Note>
  This endpoint returns list summaries only. It does **not** return the products inside each list. To retrieve full product data for a specific list, use [GET /v1/products/lists/{list_id}](/api-reference/lists/get-list).
</Note>

## Request

**Endpoint:** `GET /v1/products/lists`

### Headers

<ParamField header="Authorization" type="string" required>
  Your API key as a Bearer token: `Bearer {your_api_key}`.
</ParamField>

### Query parameters

<ParamField query="page" type="integer" default="1">
  Page number for paginating through results.
</ParamField>

<ParamField query="per_page" type="integer" default="100">
  Number of lists to return per page.
</ParamField>

<ParamField query="metadata[{key}]" type="string">
  Filter lists by a metadata key:value pair. Repeat for multiple filters. Only lists that match **all** specified pairs are returned.

  ```
  ?metadata[category]=tech_products&metadata[campaign]=summer
  ```
</ParamField>

## Example requests

<CodeGroup>
  ```bash All lists theme={null}
  curl --request GET \
    --url 'https://api.affiliate.com/v1/products/lists' \
    --header 'Authorization: Bearer {your_api_key}'
  ```

  ```bash Filter by metadata theme={null}
  curl --request GET \
    --url 'https://api.affiliate.com/v1/products/lists?metadata[category]=tech_products&metadata[campaign]=summer' \
    --header 'Authorization: Bearer {your_api_key}'
  ```
</CodeGroup>

## Response

A `200 OK` response contains a paginated `data` array of list summary objects and a `meta` object with pagination details.

```json theme={null}
{
  "meta": {
    "total": 3,
    "from": 1,
    "to": 3,
    "current_page": 1,
    "last_page": 1,
    "per_page": 100,
    "fields": [],
    "trace_id": "019643ea-b78c-704e-b616-d67cfdbcbc2f"
  },
  "data": [
    {
      "id": "9ea4894b-8491-4a79-9419-902b69f70bed",
      "name": "listnamehere",
      "metadata": {
        "key1": "metavalueiwantreturned"
      },
      "products_count": 2,
      "product_ids": [
        "8099982740095203709",
        "8099987467386791069"
      ],
      "products": [
        {
          "id": "8099982740095203709",
          "name": "Acrylic Bubblegum Tupac by N Perez Print",
          "image_url": "https://assets.wfcdn.com/im/96908466/resize-h400-w400%5Ecompr-r85/7745/77458008/.jpg"
        },
        {
          "id": "8099987467386791069",
          "name": "Bubblegum Tupac by N Perez - Round Photograph",
          "image_url": "https://assets.wfcdn.com/im/08259379/resize-h400-w400%5Ecompr-r85/7745/77458009/.jpg"
        }
      ]
    }
  ]
}
```

### Response fields

<ResponseField name="meta" type="object">
  Pagination and request metadata.

  <Expandable title="meta properties">
    <ResponseField name="meta.total" type="integer">
      Total number of lists matching the query.
    </ResponseField>

    <ResponseField name="meta.from" type="integer">
      Index of the first result on this page.
    </ResponseField>

    <ResponseField name="meta.to" type="integer">
      Index of the last result on this page.
    </ResponseField>

    <ResponseField name="meta.current_page" type="integer">
      Current page number.
    </ResponseField>

    <ResponseField name="meta.last_page" type="integer">
      Last available page number.
    </ResponseField>

    <ResponseField name="meta.per_page" type="integer">
      Number of results per page.
    </ResponseField>

    <ResponseField name="meta.fields" type="array">
      Fields included in the response. Empty array means all fields are returned.
    </ResponseField>

    <ResponseField name="meta.trace_id" type="string">
      Unique request identifier. Include this when contacting support.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="data" type="array">
  Array of list summary objects.

  <Expandable title="data item properties">
    <ResponseField name="data[].id" type="string">
      Unique list identifier.
    </ResponseField>

    <ResponseField name="data[].name" type="string">
      List display name.
    </ResponseField>

    <ResponseField name="data[].metadata" type="object">
      Key:value metadata pairs associated with this list.
    </ResponseField>

    <ResponseField name="data[].products_count" type="integer">
      Number of products in the list.
    </ResponseField>

    <ResponseField name="data[].product_ids" type="string[]">
      Array of product ID strings stored in the list.
    </ResponseField>

    <ResponseField name="data[].products" type="array">
      Lightweight product previews — each contains `id`, `name`, and `image_url` only. To get full product details, use [GET /v1/products/lists/{list_id}](/api-reference/lists/get-list).
    </ResponseField>
  </Expandable>
</ResponseField>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.

---

# GET /v1/products/lists/{id} — get list with products

Source: https://guides.affiliate.com/api-reference/lists/get-list.md

> ## 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.

# GET /v1/products/lists/{id} — get list with products

> Retrieve a single product list by ID, including full product objects with prices, affiliate URLs, images, availability, and all other product fields.

Use `GET /v1/products/lists/{list_id}` to retrieve a specific product list and the complete product data for every item it contains. This is the endpoint to call when you need current pricing, affiliate URLs, availability status, or any other product field for the items in a list.

## Request

**Endpoint:** `GET /v1/products/lists/{list_id}`

### Headers

<ParamField header="Authorization" type="string" required>
  Your API key as a Bearer token: `Bearer {your_api_key}`.
</ParamField>

### Path parameters

<ParamField path="list_id" type="string" required>
  The unique identifier of the list to retrieve. You receive a `list_id` when you [create a list](/api-reference/lists/create-list) or from the `id` field in [GET /v1/products/lists](/api-reference/lists/get-lists) responses.
</ParamField>

## Example request

```bash cURL theme={null}
curl --request GET \
  --url 'https://api.affiliate.com/v1/products/lists/{list_id}' \
  --header 'Authorization: Bearer {your_api_key}'
```

## Response

A `200 OK` response contains a `data` object with the list details and an array of full product objects.

```json theme={null}
{
  "data": {
    "id": "9ea4894b-8491-4a79-9419-902b69f70bed",
    "name": "listnamehere",
    "metadata": {
      "key1": "metavalueiwantreturned"
    },
    "products_count": 2,
    "products": [
      {
        "id": "8099982740095203709",
        "barcode": null,
        "name": "Acrylic Bubblegum Tupac by N Perez Print",
        "description": "This exclusive offering was created by N Perez, a local Miami-based artist best known for his college digital works and positive upbeat pop art.",
        "commission_url": "https://www.tkqlhce.com/click-@@@-13730087?url=https%3A%2F%2Fwww.wayfair.com%2F...&sid=###",
        "direct_url": "https://www.wayfair.com/DecorumBY--Acrylic-Bubblegum-Tupac-by-N-Perez-Print-Graphic-Art-Bubblegum-Tupac--L1318-K~DCBY1240.html",
        "image_url": "https://assets.wfcdn.com/im/96908466/resize-h400-w400%5Ecompr-r85/7745/77458008/.jpg",
        "currency": "USD",
        "regular_price": 679.99,
        "final_price": 679.99,
        "on_sale": false,
        "sale_discount": 0,
        "availability": "InStock",
        "sku": null,
        "brand": "DecorumBY",
        "category": "Home & Garden > Decor > Artwork; Home & Garden > Home Decor > Wall Art",
        "network": {
          "id": 3,
          "name": "CJ US",
          "logo_url": "https://img.affiliate.com/logos/groups/10013/128x128.png"
        },
        "merchant": {
          "id": 9998,
          "name": "Wayfair",
          "logo_url": "https://img.affiliate.com/logos/merchants/9998/logo.png"
        },
        "updated_at": "2025-04-17 04:46:36"
      },
      {
        "id": "8099987467386791069",
        "barcode": null,
        "name": "Bubblegum Tupac by N Perez - Round Photograph",
        "description": "Museum-quality art piece printed in ultra-high resolution on metallic photo paper.",
        "commission_url": "https://www.kqzyfj.com/click-@@@-13730087?url=https%3A%2F%2Fwww.wayfair.com%2F...&sid=###",
        "direct_url": "https://www.wayfair.com/DecorumBY--Bubblegum-Tupac-by-N-Perez-Round-Photograph-Graphic-Art-Bubblegum-Tupac-AD-L1318-K~DCBY1239.html",
        "image_url": "https://assets.wfcdn.com/im/08259379/resize-h400-w400%5Ecompr-r85/7745/77458009/.jpg",
        "currency": "USD",
        "regular_price": 769.99,
        "final_price": 769.99,
        "on_sale": false,
        "sale_discount": 0,
        "availability": "InStock",
        "sku": null,
        "brand": "DecorumBY",
        "category": "Home & Garden > Decor > Artwork; Home & Garden > Home Decor > Wall Art",
        "network": {
          "id": 3,
          "name": "CJ US",
          "logo_url": "https://img.affiliate.com/logos/groups/10013/128x128.png"
        },
        "merchant": {
          "id": 9998,
          "name": "Wayfair",
          "logo_url": "https://img.affiliate.com/logos/merchants/9998/logo.png"
        },
        "updated_at": "2025-04-17 04:46:36"
      }
    ]
  },
  "meta": {
    "trace_id": "019643f2-b64c-71a4-8bfd-092af3e318f7"
  }
}
```

### Response fields

<ResponseField name="data" type="object">
  The list and its products.

  <Expandable title="data properties">
    <ResponseField name="data.id" type="string">
      Unique list identifier.
    </ResponseField>

    <ResponseField name="data.name" type="string">
      List display name.
    </ResponseField>

    <ResponseField name="data.metadata" type="object">
      Key:value metadata pairs associated with this list.
    </ResponseField>

    <ResponseField name="data.products_count" type="integer">
      Number of products in the list.
    </ResponseField>

    <ResponseField name="data.products" type="array">
      Full product objects. See the product fields table below.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  <Expandable title="meta properties">
    <ResponseField name="meta.trace_id" type="string">
      Unique request identifier. Include this when contacting support.
    </ResponseField>
  </Expandable>
</ResponseField>

### Product object fields

Each item in `data.products` contains the following fields.

| Field | Type | Description |
| - | - | - |
| `id` | string | Unique product identifier |
| `barcode` | integer \| null | UPC, EAN, or GTIN barcode |
| `name` | string | Product title |
| `description` | string | Full product description |
| `commission_url` | string | Affiliate URL — replace `@@@` with your affiliate ID and `###` with your sub-ID |
| `direct_url` | string | Direct merchant URL (no commission) |
| `image_url` | string | Primary product image URL |
| `currency` | string | ISO 4217 currency code (e.g., `USD`) |
| `regular_price` | number | Original retail price |
| `final_price` | number | Current price after any discounts |
| `on_sale` | boolean | `true` when a sale discount is active |
| `sale_discount` | integer | Discount percentage |
| `availability` | string | Stock status (e.g., `InStock`, `OutOfStock`) |
| `sku` | integer \| null | Merchant stock-keeping unit |
| `brand` | string | Brand name |
| `category` | string | Hierarchical category path |
| `network.id` | integer | Affiliate network ID |
| `network.name` | string | Affiliate network 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 |
| `updated_at` | string | Timestamp when the product was last refreshed from the merchant feed |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.

---

# Add products to an existing product list

Source: https://guides.affiliate.com/api-reference/lists/add-products.md

> ## 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.

# Add products to an existing product list

> Append one or more product IDs to an existing list. Duplicate IDs are silently ignored and returned in ignored_product_ids so you can detect them.

Use `POST /v1/products/lists/{list_id}/items` to append products to an existing list. Pass an array of product IDs in the request body. The response tells you which IDs were successfully added and which were skipped because they were already in the list.

<Note>
  If you submit product IDs that already exist in the list, the API does not return an error. Instead, those IDs appear in `ignored_product_ids` in the response. Only new IDs are added and appear in `added_product_ids`.
</Note>

## Request

**Endpoint:** `POST /v1/products/lists/{list_id}/items`

### Headers

<ParamField header="Authorization" type="string" required>
  Your API key as a Bearer token: `Bearer {your_api_key}`.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`.
</ParamField>

### Path parameters

<ParamField path="list_id" type="string" required>
  The unique identifier of the list to add products to.
</ParamField>

### Body parameters

<ParamField body="product_ids" type="string[]" required>
  An array of product ID strings to add to the list.

  ```json theme={null}
  {
    "product_ids": [
      "3456789012345678901",
      "4567890123456789012"
    ]
  }
  ```
</ParamField>

## Example request

```bash cURL theme={null}
curl --request POST \
  --url 'https://api.affiliate.com/v1/products/lists/{list_id}/items' \
  --header 'Authorization: Bearer {your_api_key}' \
  --header 'Content-Type: application/json' \
  --data '{
    "product_ids": [
      "3456789012345678901",
      "4567890123456789012"
    ]
  }'
```

## Response

A `200 OK` response confirms which product IDs were added and which were ignored.

```json theme={null}
{
  "list_id": "d345e67f-89g0-1h2i-3j45-6k7891lm2345",
  "added_product_ids": [
    "3456789012345678901"
  ],
  "ignored_product_ids": [
    "4567890123456789012"
  ],
  "meta": {
    "trace_id": "d1e2f3g4-5h6i-7j8k-9l10-m1n2o3p4q5r6"
  }
}
```

### Response fields

<ResponseField name="list_id" type="string">
  The ID of the list that was modified.
</ResponseField>

<ResponseField name="added_product_ids" type="string[]">
  Product IDs that were successfully added to the list.
</ResponseField>

<ResponseField name="ignored_product_ids" type="string[]">
  Product IDs that were not added because they were already present in the list. No error is thrown for these IDs.
</ResponseField>

<ResponseField name="meta" type="object">
  <Expandable title="meta properties">
    <ResponseField name="meta.trace_id" type="string">
      Unique request identifier. Include this when contacting support.
    </ResponseField>
  </Expandable>
</ResponseField>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.

---

# Remove products from an existing product list

Source: https://guides.affiliate.com/api-reference/lists/remove-products.md

> ## 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.

# Remove products from an existing product list

> Delete one or more product IDs from an existing list. IDs not found in the list are returned in ignored_product_ids rather than causing an error.

Use `DELETE /v1/products/lists/{list_id}/products` to remove specific products from an existing list. Pass an array of product IDs to remove in the request body. The response confirms which IDs were removed and which were skipped because they were not found in the list.

<Note>
  If you submit product IDs that are not in the list, the API does not return an error. Those IDs appear in `ignored_product_ids` in the response. Only IDs that were present in the list are removed and appear in `removed_product_ids`.
</Note>

## Request

**Endpoint:** `DELETE /v1/products/lists/{list_id}/products`

### Headers

<ParamField header="Authorization" type="string" required>
  Your API key as a Bearer token: `Bearer {your_api_key}`.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`.
</ParamField>

### Path parameters

<ParamField path="list_id" type="string" required>
  The unique identifier of the list to remove products from.
</ParamField>

### Body parameters

<ParamField body="product_ids" type="string[]" required>
  An array of product ID strings to remove from the list.

  ```json theme={null}
  {
    "product_ids": [
      "1234567890123456789",
      "9876543210987654321"
    ]
  }
  ```
</ParamField>

## Example request

```bash cURL theme={null}
curl --request DELETE \
  --url 'https://api.affiliate.com/v1/products/lists/{list_id}/products' \
  --header 'Authorization: Bearer {your_api_key}' \
  --header 'Content-Type: application/json' \
  --data '{
    "product_ids": [
      "1234567890123456789",
      "9876543210987654321"
    ]
  }'
```

## Response

A `200 OK` response confirms which product IDs were removed and which were not found in the list.

```json theme={null}
{
  "list_id": "d345e67f-89g0-1h2i-3j45-6k7891lm2345",
  "removed_product_ids": [
    "1234567890123456789"
  ],
  "ignored_product_ids": [
    "9876543210987654321"
  ],
  "meta": {
    "trace_id": "e1f2g3h4-5i6j-7k8l-9m10-n1o2p3q4r5s6"
  }
}
```

### Response fields

<ResponseField name="list_id" type="string">
  The ID of the list that was modified.
</ResponseField>

<ResponseField name="removed_product_ids" type="string[]">
  Product IDs that were successfully removed from the list.
</ResponseField>

<ResponseField name="ignored_product_ids" type="string[]">
  Product IDs that were not removed because they were not found in the list. No error is thrown for these IDs.
</ResponseField>

<ResponseField name="meta" type="object">
  <Expandable title="meta properties">
    <ResponseField name="meta.trace_id" type="string">
      Unique request identifier. Include this when contacting support.
    </ResponseField>
  </Expandable>
</ResponseField>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.

---

# DELETE /v1/products/lists/{id} — delete a list

Source: https://guides.affiliate.com/api-reference/lists/delete-list.md

> ## 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.

# DELETE /v1/products/lists/{id} — delete a list

> Permanently delete a product list by ID. The list and all its stored product IDs are removed immediately and cannot be recovered afterwards.

Use `DELETE /v1/products/lists/{list_id}` to permanently delete a product list. The response confirms deletion with the list ID and a `"deleted"` status.

<Warning>
  Deleting a list is permanent and cannot be undone. The list and all its stored product IDs are removed immediately. If you need the list later, recreate it using [POST /v1/products/lists](/api-reference/lists/create-list).
</Warning>

## Request

**Endpoint:** `DELETE /v1/products/lists/{list_id}`

### Headers

<ParamField header="Authorization" type="string" required>
  Your API key as a Bearer token: `Bearer {your_api_key}`.
</ParamField>

### Path parameters

<ParamField path="list_id" type="string" required>
  The unique identifier of the list to delete.
</ParamField>

## Example request

```bash cURL theme={null}
curl --request DELETE \
  --url 'https://api.affiliate.com/v1/products/lists/{list_id}' \
  --header 'Authorization: Bearer {your_api_key}'
```

## Response

A `200 OK` response confirms the list has been deleted.

```json theme={null}
{
  "id": "d345e67f-89g0-1h2i-3j45-6k7891lm2345",
  "status": "deleted",
  "meta": {
    "trace_id": "c1d2e3f4-5g6h-7i8j-9k10-l1m2n3o4p5q6"
  }
}
```

### Response fields

<ResponseField name="id" type="string">
  The ID of the list that was deleted.
</ResponseField>

<ResponseField name="status" type="string">
  Confirmation of the deletion. Always `"deleted"` on a successful request.
</ResponseField>

<ResponseField name="meta" type="object">
  <Expandable title="meta properties">
    <ResponseField name="meta.trace_id" type="string">
      Unique request identifier. Include this when contacting support.
    </ResponseField>
  </Expandable>
</ResponseField>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.

---

## Pools

---

# Pools API: manage reusable network and merchant sets

Source: https://guides.affiliate.com/api-reference/pools/overview.md

> ## 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.

# Pools API: manage reusable network and merchant sets

> Create named sets of networks and merchants. Pass a pool_id to search endpoints to automatically scope results without repeating filter lists on every request.

The Pools API lets you define a reusable set of networks and merchants once, then reference it by ID across search endpoints. Instead of passing the same `network_ids` and `merchant_ids` on every request, you attach a `pool_id` and the API resolves the filters automatically.

## How pools work

A pool stores:

* **Networks** — affiliate networks to include
* **Merchants** — merchants to include in results

When you pass `pool_id` to a supported search endpoint, the pool's networks and merchants are combined with any explicitly passed filter values — not replaced.

<Warning>
  Pools are team-scoped. Passing a `pool_id` that belongs to a different team returns a `422` error.
</Warning>

## Using a pool in search

Pass `pool_id` as a top-level parameter to any of these endpoints:

| Endpoint | Description |
| - | - |
| `POST /v1/products` | Search affiliate products |
| `POST /v1/products/omni` | Unified product search |
| `POST /v1/promotions` | Search promotions |
| `GET /v1/merchants?extended=1` | List merchants — different semantics, see [below](#using-a-pool-with-get-v1-merchants) |

```json theme={null}
{
  "pool_id": "01JPSEEDP1ATA11P0010000100",
  "search": "shoes"
}
```

Pass the **bare** ULID — the `pool_`-prefixed `object_id` form returns `422`. Only one `pool_id` may be passed per request. Returns `422` if the id is prefixed, the pool does not exist, or it belongs to another team.

### Using a pool with `GET /v1/merchants`

`pool_id` behaves differently here than on products/omni/promotions — it's a hard scope rather than a filter merge, and it also decides whose credentials build `providers[]` links. Requires `extended=1`.

```bash cURL theme={null}
curl --request GET \
  'https://api.affiliate.com/v1/merchants?extended=1&pool_id=01JPSEEDP1ATA11P0010000100' \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

| | Products / Omni / Promotions | Merchants (`extended=1`) |
| - | - | - |
| What `pool_id` does | Combines the pool's `networks`/`merchants` with any `network_ids`/`merchant_ids` you also pass | Restricts the results to **only** the merchants collected into that pool — there's no separate `merchant_ids` param here to merge with |
| Effect on links | N/A | Also decides whose network credentials (**Pools → Sources**) resolve `providers[].url`/`template`/`outclick` and approval status **first** — account-level credentials remain a fallback |
| Omitted | No scoping applied | No scoping applied; link/approval resolution falls back to your account's **default pool** |

<Tip>
  Running more than one pool — separate credentials per site or brand, say? Pass the `pool_id` that matches the request; a Source configured on one pool never applies to a different pool's request. This is **not** provider isolation, though — for a provider the pool owns no credential for, resolution falls back to your account-level credential, so links can still come back with a different campaign than a pool that owns its own. See [Monetizing with the Merchants API](/guides/monetize-with-merchants#7-pools) for a full worked example.
</Tip>

## Available endpoints

| Method | Endpoint | Description |
| - | - | - |
| `GET` | `/v1/pools` | List all pools |
| `POST` | `/v1/pools` | Create a pool |
| `GET` | `/v1/pools/{id}` | Get a pool |
| `PUT` | `/v1/pools/{id}` | Update a pool |
| `DELETE` | `/v1/pools/{id}` | Delete a pool |
| `GET` | `/v1/pools/{id}/settings` | Get pool settings |
| `PATCH` | `/v1/pools/{id}/settings` | Update pool settings |
| `POST` | `/v1/pools/{id}/networks` | Add networks to a pool |
| `DELETE` | `/v1/pools/{id}/networks` | Remove networks from a pool |
| `PUT` | `/v1/pools/{id}/networks/{network}` | Update network affiliate config |
| `POST` | `/v1/pools/{id}/merchants` | Add merchants to a pool |
| `DELETE` | `/v1/pools/{id}/merchants` | Remove merchants from a pool |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.

---

# Manage pools — create, get, update, delete

Source: https://guides.affiliate.com/api-reference/pools/manage-pools.md

> ## 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.

# Manage pools — create, get, update, delete

> CRUD operations for pools: create a named set of networks and merchants, retrieve it by ID, update its contents, or delete it.

## List pools

Returns all pools for the authenticated team.

**`GET /v1/pools`**

### Query parameters

<ParamField query="page" type="integer" default="1">
  Page number.
</ParamField>

<ParamField query="per_page" type="integer" default="25">
  Results per page.
</ParamField>

***

## Create pool

Creates a new pool.

**`POST /v1/pools`**

### Headers

<ParamField header="Authorization" type="string" required>
  Your API key as a Bearer token: `Bearer {your_api_key}`.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`.
</ParamField>

### Body parameters

<ParamField body="name" type="string" required>
  Pool name. Min 2, max 255 characters. Must be unique per team.
</ParamField>

<ParamField body="description" type="string">
  Optional description of the pool.
</ParamField>

<ParamField body="url" type="string">
  Optional URL associated with the pool.
</ParamField>

<ParamField body="is_default" type="boolean">
  Whether this pool is the team's default pool.
</ParamField>

<ParamField body="networks" type="string[]">
  Array of network IDs to include in the pool.
</ParamField>

<ParamField body="merchants" type="string[]">
  Array of merchant IDs to add to the pool — bare ID, no `nmer_`/`mer_` prefix (see note below).
</ParamField>

### Example request

```json theme={null}
{
  "name": "My Product Pool",
  "description": "Pool for outdoor products",
  "url": "https://example.com",
  "is_default": false,
  "networks": ["NETWORK_ID_1", "NETWORK_ID_2"],
  "merchants": ["MERCHANT_ID_1", "MERCHANT_ID_2"]
}
```

### Response `201`

```json theme={null}
{
  "id": "01JPSEEDP1ATA11P0010000100",
  "team_id": 1,
  "user_id": 1,
  "name": "My Product Pool",
  "description": "Pool for outdoor products",
  "url": "https://example.com",
  "is_default": false,
  "status": "active",
  "networks": [
    { "id": "NETWORK_ID_1", "name": "ShareASale" }
  ],
  "included_merchants": [
    { "id": "MERCHANT_ID_1", "name": "Acme Co" }
  ],
  "excluded_merchants": []
}
```

<Note>
  `included_merchants[].id` / `excluded_merchants[].id` are the merchant's **bare** ID — no
  `nmer_`/`mer_` prefix, unlike the IDs `GET /v1/merchants` returns. To look one up directly,
  prepend `nmer_` (e.g. `id: "01khfmw45fc139x9w8fsb133yb"` →
  `GET /v1/merchants/nmer_01khfmw45fc139x9w8fsb133yb?extended=1`). The `merchants` request
  parameter (here, in Update, and in [Pool merchants](/api-reference/pools/pool-merchants)) takes
  this same bare form.
</Note>

***

## Get pool

Retrieves a single pool by its ULID.

**`GET /v1/pools/{id}`**

Returns the same shape as the create response.

***

## Update pool

Updates an existing pool. `networks` and `merchants` are diffed — IDs in the request replace the current set (new IDs are added, missing IDs are removed).

**`PUT /v1/pools/{id}`**

### Body parameters

Same shape as create pool.

```json theme={null}
{
  "name": "Updated Pool Name",
  "description": "Updated description",
  "url": "https://example.com",
  "is_default": true,
  "networks": ["NETWORK_ID_1"],
  "merchants": ["MERCHANT_ID_1"]
}
```

Returns `200` with the same shape as the create response — `included_merchants` /
`excluded_merchants`, not `merchants`.

***

## Delete pool

Deletes a pool by its ULID.

**`DELETE /v1/pools/{id}`**


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.

---

# Pool settings — get and update

Source: https://guides.affiliate.com/api-reference/pools/pool-settings.md

> ## 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.

# Pool settings — get and update

> Retrieve or update the service and sync configuration for a pool.

## Get pool settings

**`GET /v1/pools/{id}/settings`**

### Path parameters

<ParamField path="id" type="string" required>
  ULID of the pool.
</ParamField>

### Response

`data.outclick_provider_order` is the pool's **outclick priority** list — the order a plain `outclick` link (no explicit `?format=`) tries its link providers, first to last; the first provider able to carry the click wins. Always the full candidate set (`network` plus every available link service, currently just `shopnomix`) — a provider never explicitly saved is appended in built-in order. The network link can always carry the click, so a provider ranked below it never gets a turn. Default order is `["network", "shopnomix"]`, meaning a plain outclick never routes through Shopnomix until a pool moves it above `network`.

***

## Update pool settings

**`PATCH /v1/pools/{id}/settings`**

### Path parameters

<ParamField path="id" type="string" required>
  ULID of the pool.
</ParamField>

### Body parameters

<ParamField body="offer_link_service" type="string">
  Link service to use for offer URLs.
</ParamField>

<ParamField body="link_service_key" type="string">
  API key for the configured link service.
</ParamField>

<ParamField body="default_url_format" type="string">
  Default URL format for product links (e.g. `"affiliate"`).
</ParamField>

<ParamField body="outclick_provider_order" type="string[]">
  The order a plain `outclick` link tries providers, first to last — `"network"` and `"shopnomix"` are the only values today. The first provider in the list able to carry the click wins; the network link always can, so ranking it first (the default) means a plain outclick never routes through Shopnomix. A provider left out of the list is appended after the ones you named, in built-in order; passing `[]` restores the built-in default order. Applies to new links immediately, and retroactively to `outclick` links already handed out (re-evaluated at click time).
</ParamField>

### Example request

```json theme={null}
{
  "offer_link_service": "skimlinks",
  "link_service_key": "your_link_service_key",
  "default_url_format": "affiliate",
  "outclick_provider_order": ["shopnomix", "network"]
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.

---

# Pool networks — add, remove, update

Source: https://guides.affiliate.com/api-reference/pools/pool-networks.md

> ## 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.

# Pool networks — add, remove, update

> Add or remove networks from a pool, and configure affiliate credentials per network.

## Add networks to pool

**`POST /v1/pools/{id}/networks`**

<ParamField body="network_ids" type="string[]" required>
  Array of network IDs to add.
</ParamField>

```json theme={null}
{
  "network_ids": ["NETWORK_ID_1", "NETWORK_ID_2"]
}
```

***

## Remove networks from pool

**`DELETE /v1/pools/{id}/networks`**

<ParamField body="network_ids" type="string[]" required>
  Array of network IDs to remove.
</ParamField>

```json theme={null}
{
  "network_ids": ["NETWORK_ID_1"]
}
```

***

## Update network affiliate config

Updates affiliate credentials for a specific network within a pool.

**`PUT /v1/pools/{id}/networks/{network}`**

<ParamField body="affiliate_id" type="string">
  Your affiliate ID for this network.
</ParamField>

<ParamField body="sub_affiliate_id" type="string">
  Your sub-affiliate / sub ID for this network.
</ParamField>

<ParamField body="sync_merchants" type="boolean">
  Whether to sync merchants from this network to the pool.
</ParamField>

```json theme={null}
{
  "affiliate_id": "your_affiliate_id",
  "sub_affiliate_id": "your_sub_id",
  "sync_merchants": true
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.

---

# Pool merchants — add and remove

Source: https://guides.affiliate.com/api-reference/pools/pool-merchants.md

> ## 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.

# Pool merchants — add and remove

> Add or remove merchants from a pool.

<Note>
  Merchant IDs here are the **bare** ID — no `nmer_`/`mer_` prefix, matching the form pool
  responses return in `included_merchants[].id`/`excluded_merchants[].id`. This differs from the
  prefixed IDs `GET /v1/merchants` returns.
</Note>

## Add merchants to pool

**`POST /v1/pools/{id}/merchants`**

<ParamField body="merchant_ids" type="string[]" required>
  Array of merchant IDs to add.
</ParamField>

```json theme={null}
{
  "merchant_ids": ["MERCHANT_ID_1", "MERCHANT_ID_2"]
}
```

***

## Remove merchants from pool

**`DELETE /v1/pools/{id}/merchants`**

<ParamField body="merchant_ids" type="string[]" required>
  Array of merchant IDs to remove.
</ParamField>

```json theme={null}
{
  "merchant_ids": ["MERCHANT_ID_1"]
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.

---

## Account & Reporting

---

# Account API: team info, rate limits, and usage stats

Source: https://guides.affiliate.com/api-reference/account/overview.md

> ## 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.

# Account API: team info, rate limits, and usage stats

> Retrieve your team's identity, API rate limits, total request counts, and per-product billing cycle details in a single authenticated call.

The Account API gives you a snapshot of your team configuration and API consumption. Use it to check your current rate limit, monitor how many requests you've made this billing cycle, and inspect which products your bearer token has access to.

## What the Account API returns

A successful call to `GET /v1/account` returns a single JSON object. The top-level fields describe your team and overall usage, while the `products` array breaks down request counts and billing windows for each product associated with your token.

### Response fields

| Field | Type | Description |
| - | - | - |
| `team_id` | integer | The unique identifier for your team. |
| `team_name` | string | The display name of your team. |
| `api_request_rate_limit` | integer | The maximum number of API requests your team can make per minute. |
| `can_toggle_short_url` | boolean | Whether your team has permission to toggle short URL generation. |
| `product_search_results_max` | integer | The maximum number of product search results that can be returned per query. |
| `requests_total_so_far` | integer | The cumulative number of API requests your team has made. |
| `requests_made_since_last_payment` | integer | The number of API requests made since your last payment. |
| `products` | array | The list of products your bearer token has active, including request counts and billing cycle information. |
| `products[].product` | string | The product identifier (e.g. `"API"` or `"PLATFORM"`). |
| `products[].count` | integer | The number of requests made against this product in the current billing cycle. |
| `products[].billing_cycle` | object \| null | The billing window for this product, or `null` if not applicable. |
| `products[].billing_cycle.start` | string | ISO 8601 timestamp for the start of the billing cycle. |
| `products[].billing_cycle.end` | string | ISO 8601 timestamp for the end of the billing cycle. |
| `products[].billing_cycle.days_remaining` | integer | Number of days remaining in the current billing cycle. |
| `meta.trace_id` | string | A unique trace identifier for this request, useful for support and debugging. |

## Example response

```json theme={null}
{
    "team_id": 1,
    "team_name": "Test Team",
    "api_request_rate_limit": 60,
    "can_toggle_short_url": false,
    "product_search_results_max": 10000,
    "requests_total_so_far": 5,
    "requests_made_since_last_payment": 5,
    "products": [
        {
            "product": "API",
            "count": 1234,
            "billing_cycle": {
                "start": "2025-06-15T15:22:35+00:00",
                "end": "2025-07-15T15:22:35+00:00",
                "days_remaining": 0
            }
        }
    ],
    "meta": {
        "trace_id": "01980eae-de82-72de-8402-cd5ad0588cee"
    }
}
```

## Next steps

To make the request, see [GET /v1/account](/api-reference/account/get-account).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.

---

# GET /v1/account — retrieve account information

Source: https://guides.affiliate.com/api-reference/account/get-account.md

> ## 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.

# GET /v1/account — retrieve account information

> Fetch your team's name, API rate limit, request counters, and per-product billing cycle data using your Bearer token. Returns team ID and product list.

Use this endpoint to retrieve account details for the team associated with your bearer token. The response includes your team identity, rate limit configuration, and a breakdown of request usage per product.

## Endpoint

```
GET /v1/account
```

## Request

This endpoint takes no query parameters or request body. You only need to supply your `Authorization` header.

### Headers

<ParamField header="Authorization" type="string" required>
  Your bearer token in the format `Bearer <token>`. All requests to the Affiliate.com API require this header.
</ParamField>

### Example request

```bash theme={null}
curl --location --request GET 'https://api.affiliate.com/v1/account' \
--header 'Authorization: Bearer {{token}}'
```

## Responses

### 200 — Success

Returns a JSON object with your team details, usage statistics, and product billing information.

<ResponseField name="team_id" type="integer">
  The unique identifier for your team.
</ResponseField>

<ResponseField name="team_name" type="string">
  The display name of your team.
</ResponseField>

<ResponseField name="api_request_rate_limit" type="integer">
  The maximum number of API requests your team can make per minute.
</ResponseField>

<ResponseField name="can_toggle_short_url" type="boolean">
  Whether your team has permission to toggle short URL generation.
</ResponseField>

<ResponseField name="product_search_results_max" type="integer">
  The maximum number of product search results returnable per query.
</ResponseField>

<ResponseField name="requests_total_so_far" type="integer">
  The total number of API requests your team has made.
</ResponseField>

<ResponseField name="requests_made_since_last_payment" type="integer">
  The number of API requests made since your most recent payment.
</ResponseField>

<ResponseField name="products" type="array">
  The products your bearer token has active. Each entry includes a request count and optional billing cycle.

  <Expandable title="products[]">
    <ResponseField name="product" type="string">
      The product identifier. Currently `"API"`.
    </ResponseField>

    <ResponseField name="count" type="integer">
      The number of requests made against this product in the current billing cycle.
    </ResponseField>

    <ResponseField name="billing_cycle" type="object | null">
      The billing window for this product. Returns `null` if billing does not apply to this product.

      <Expandable title="billing_cycle">
        <ResponseField name="start" type="string">
          ISO 8601 timestamp marking the start of the billing cycle.
        </ResponseField>

        <ResponseField name="end" type="string">
          ISO 8601 timestamp marking the end of the billing cycle.
        </ResponseField>

        <ResponseField name="days_remaining" type="integer">
          The number of days remaining in the current billing cycle.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  Metadata about the response.

  <Expandable title="meta">
    <ResponseField name="trace_id" type="string">
      A unique trace identifier for this request, useful when contacting support.
    </ResponseField>
  </Expandable>
</ResponseField>

#### Example response

```json theme={null}
{
    "team_id": 10,
    "team_name": "Test Team",
    "api_request_rate_limit": 60,
    "can_toggle_short_url": false,
    "product_search_results_max": 10000,
    "requests_total_so_far": 5,
    "requests_made_since_last_payment": 5,
    "products": [
        {
            "product": "API",
            "count": 1234,
            "billing_cycle": {
                "start": "2025-06-15T15:22:35+00:00",
                "end": "2025-07-15T15:22:35+00:00",
                "days_remaining": 0
            }
        }
    ],
    "meta": {
        "trace_id": "01980eae-de82-72de-8402-cd5ad0588cee"
    }
}
```

### 401 — Unauthenticated

Your bearer token is missing, expired, or invalid. Verify that you are passing the correct token in the `Authorization` header.

### 429 — Rate Limit Exceeded

You have exceeded your team's `api_request_rate_limit`. Wait until the next minute window before retrying.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.

---

# GET /v1/reports/outclick — your account's outclick events

Source: https://guides.affiliate.com/api-reference/reports/outclick.md

> ## 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.

# GET /v1/reports/outclick — your account's outclick events

> Retrieve the API click (outclick) events recorded for your account, enriched with the product, merchant, network, and client data captured at click time.

The `GET /v1/reports/outclick` endpoint returns the outclick events recorded
for your account — **product** clicks by default, or **merchant** clicks with `offer_type=merchant`.
A product event includes the click metadata, the price and provider data captured at click time,
the product name and direct URL from the stored offer snapshot, and the client details; a merchant
event carries the merchant/network identity but no product snapshot (see [Merchant outclicks](#merchant-outclicks)).

Requires a token with **API** product access.

## Endpoint

```
GET /v1/reports/outclick
```

## Key behavior

* Each query is limited to a **24-hour** window and excludes the most recent **5 minutes**.
* Returns **product** and **merchant** outclicks — pick with `offer_type` (defaults to `product`). Promotion outclicks are intentionally excluded.
* All filters are **exact** matches.
* Robot clicks are excluded unless `include_robots=true`.
* Results are ordered newest first (`created_at` descending).
* Prices are returned as floats (e.g. `131.25`).
* Each request bills **one API unit**, regardless of how many rows are returned.

## Merchant outclicks

Pass `offer_type=merchant` to return clicks on **merchant** outclick links — the `outclick` field of a `providers[]` entry (e.g. a homepage link to a service merchant such as HelloFresh or Avis), including AdMedia merchant links. A merchant click carries the merchant identity but **no product snapshot**:

* `offer_type` is `merchant`, and the top-level `merchant` (`id`, `object_id`, `name`) and `network` (`id`, `object_id`, `name`) objects are populated.
* `product` is `null` — a merchant has no offer/feed row, so there is nothing to snapshot.
* `sub_id`, `client.*`, `country`, and `origin_query_parameters` are populated as usual.

Narrow merchant clicks with `merchant_object_id` (`nmer_…`), `network_object_id` (`rnet_…`), or `sub_id`.

## Troubleshooting — a click isn't showing

<Note>
  The most common cause of an empty result right after a test click is the **5-minute window**, not missing data.
</Note>

* **Wait 5 minutes.** `end_at` must be at least 5 minutes in the past, so a click isn't queryable until \~5 minutes after it happens. A window whose `end_at` is older than the click returns nothing.
* **Match the account.** A click is owned by the account whose API key **minted the outclick** (baked in at link-build time), not the one that clicks it. Query with that same key — a different account won't see it.
* **`sub_id` is exact, and stored verbatim.** If you leave the `{AFF_ID}`/`{SUB_ID}` (or `@@@`/`###`) placeholders in the link unreplaced, they're recorded literally (e.g. `sub_id` becomes `{SUB_ID}`), so a tag filter won't match. Replace the slots with real values before clicking.
* **Robots are excluded by default.** Add `include_robots=true` if you're testing with a tool or headless browser.
* **Product-snapshot timing.** The click row is written synchronously, but the `product` snapshot is enriched by a background job — so on a **product** click the row can appear a moment before its `product` block is fully populated under load. Merchant clicks have no snapshot, so nothing lags.

## Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication. Format: `Bearer {your_api_key}`.
</ParamField>

## Query parameters

<ParamField query="start_at" type="string" required>
  Inclusive start of the window. Accepts an RFC 3339 timestamp (e.g. `2026-07-23T00:00:00Z`) or a UTC date (`2026-07-23`). A bare date resolves to midnight UTC. Maximum 64 characters.
</ParamField>

<ParamField query="end_at" type="string" required>
  Exclusive end of the window. Accepts an RFC 3339 timestamp or a UTC date. A bare date resolves to midnight UTC of the next day, so passing the same bare date as `start_at` requests the full UTC day. Must be after `start_at`, no more than 24 hours after `start_at`, and at least 5 minutes in the past. Maximum 64 characters.
</ParamField>

<ParamField query="page" type="integer" default="1">
  The page number to return. Integer, at least 1.
</ParamField>

<ParamField query="per_page" type="integer" default="100">
  The number of events to return per page. Integer from 1 through 1000.
</ParamField>

<ParamField query="offer_type" type="string" default="product">
  `product` or `merchant`. Selects which kind of outclick to return. See [Merchant outclicks](#merchant-outclicks).
</ParamField>

<ParamField query="sub_id" type="string">
  Exact sub ID match. Maximum 1,024 characters.
</ParamField>

<ParamField query="product_id" type="string">
  Exact product ID match. Maximum 1,024 characters.
</ParamField>

<ParamField query="merchant_id" type="string">
  Exact provider (network merchant) ID match. Maximum 255 characters.
</ParamField>

<ParamField query="merchant_object_id" type="string">
  Exact Affiliate.com merchant object ID. Requires the `nmer_` prefix (e.g. `nmer_01khfmtj1vpvy6345xfhwepz9t`).
</ParamField>

<ParamField query="network_id" type="string">
  Exact provider (network) ID match. Maximum 255 characters.
</ParamField>

<ParamField query="network_object_id" type="string">
  Exact Affiliate.com network object ID. Requires the `rnet_` prefix (e.g. `rnet_01kkgbyq466tn06cgev3b1dnaa`).
</ParamField>

<ParamField query="country" type="string">
  Two-letter client country code. Normalized to uppercase.
</ParamField>

<ParamField query="include_robots" type="boolean" default="false">
  When `true`, includes both robot and non-robot clicks. Defaults to `false` (non-robot clicks only).
</ParamField>

<ParamField query="fields" type="string">
  Comma-separated string or `fields[]` array selecting which fields to return. Between 1 and 50 fields. Omitting it returns all fields. Accepts any leaf field path listed under [Response fields](#response-fields), plus the parent paths `product`, `product.urls`, `product.merchant`, `product.network`, and `client` (which select the whole sub-object).
</ParamField>

## Example requests

Retrieve one day of outclicks:

```bash theme={null}
curl --request GET \
  --url 'https://api.affiliate.com/v1/reports/outclick?start_at=2026-07-23T00:00:00Z&end_at=2026-07-23T16:35:00Z&page=1&per_page=100' \
  --header 'Authorization: Bearer {your_api_key}'
```

Select a subset of fields for the full UTC day:

```bash theme={null}
curl --request GET \
  --url 'https://api.affiliate.com/v1/reports/outclick?start_at=2026-07-23&end_at=2026-07-23&fields=id,created_at,product.id,product.final_price,client.country' \
  --header 'Authorization: Bearer {your_api_key}'
```

## Response

```json theme={null}
{
  "meta": {
    "total": 8,
    "from": 1,
    "to": 8,
    "current_page": 1,
    "last_page": 1,
    "per_page": 100,
    "fields": [
      "id",
      "created_at",
      "event_type",
      "offer_type",
      "account_id",
      "team_id",
      "request_url",
      "origin_url",
      "origin_query_parameters",
      "sub_id",
      "trace_id",
      "click_tracking",
      "product.id",
      "product.name",
      "product.urls.direct",
      "product.regular_price",
      "product.final_price",
      "product.on_sale",
      "product.currency",
      "product.availability",
      "product.merchant.id",
      "product.merchant.object_id",
      "product.merchant.name",
      "product.network.id",
      "product.network.object_id",
      "product.network.name",
      "client.country",
      "client.is_robot",
      "client.robot_name",
      "client.device_type",
      "client.browser_name",
      "client.browser_version"
    ],
    "trace_id": "019f928c-677d-7075-889b-1277a9cd4b12"
  },
  "data": [
    {
      "id": "01ky98f5181va0cffv65pgf0rv",
      "created_at": "2026-07-24T05:09:46.000000Z",
      "event_type": "click",
      "offer_type": "product",
      "account_id": "01k12fc58qqr2y71n3dnrz0xcx",
      "team_id": 9,
      "request_url": "https://go.dustin.dk/t/t?a=1755474683&as=@@@&t=2&tk=1&cupa_sku=5020067783&url=https://www.dustin.dk/product/5020067783/folio-case?priceinclusivevat=1",
      "origin_url": "https://4381.click.affili8.dev/a/eyJpdiI6Ii4uLiJ9",
      "origin_query_parameters": {
        "affiliate_id": "@@@",
        "sub_id": null
      },
      "sub_id": null,
      "trace_id": "019f9287-05d8-713e-8fbb-49faeff2f435",
      "click_tracking": false,
      "product": {
        "id": "8663182891802204718",
        "name": "Zagg Folio Case Iphone 13, Iphone 14, Iphone 15, Iphone 16e, Iphone 17e Sort",
        "urls": {
          "direct": "https://www.dustin.dk/product/5020067783/folio-case?priceinclusivevat=1"
        },
        "regular_price": 131.25,
        "final_price": 131,
        "on_sale": true,
        "currency": "DKK",
        "availability": "InStock",
        "merchant": {
          "id": "66318",
          "object_id": "nmer_01khfmtj1vpvy6345xfhwepz9t",
          "name": "Dustin"
        },
        "network": {
          "id": "323",
          "object_id": "rnet_01kkgbyq466tn06cgev3b1dnaa",
          "name": "Adtraction Denmark"
        }
      },
      "client": {
        "country": "US",
        "is_robot": false,
        "robot_name": null,
        "device_type": "desktop",
        "browser_name": "Chrome",
        "browser_version": "150.0.0.0"
      }
    }
  ]
}
```

## Response fields

### `meta` object

<ResponseField name="meta.total" type="integer">
  Total number of events matching the query.
</ResponseField>

<ResponseField name="meta.from" type="integer">
  Index of the first event on the current page. `null` when there are no results.
</ResponseField>

<ResponseField name="meta.to" type="integer">
  Index of the last event on the current page. `null` when there are no results.
</ResponseField>

<ResponseField name="meta.current_page" type="integer">
  The current page number.
</ResponseField>

<ResponseField name="meta.last_page" type="integer">
  The total number of pages.
</ResponseField>

<ResponseField name="meta.per_page" type="integer">
  The number of records per page.
</ResponseField>

<ResponseField name="meta.fields" type="string[]">
  The field paths included in each event.
</ResponseField>

<ResponseField name="meta.trace_id" type="string">
  Unique identifier for this request. Include this value when contacting support.
</ResponseField>

### Event object (`data[]`)

<ResponseField name="id" type="string">
  Unique identifier for the click event.
</ResponseField>

<ResponseField name="created_at" type="string">
  Click timestamp, ISO 8601 (UTC).
</ResponseField>

<ResponseField name="event_type" type="string">
  The event type (e.g. `click`).
</ResponseField>

<ResponseField name="offer_type" type="string">
  The offer type: `product` or `merchant` (matches the `offer_type` filter).
</ResponseField>

<ResponseField name="account_id" type="string">
  The account that owns the click.
</ResponseField>

<ResponseField name="team_id" type="integer">
  The team that owns the click.
</ResponseField>

<ResponseField name="request_url" type="string">
  The provider tracking URL the click was sent to.
</ResponseField>

<ResponseField name="origin_url" type="string">
  The Affiliate.com outclick URL that initiated the redirect.
</ResponseField>

<ResponseField name="origin_query_parameters" type="object">
  Query parameters captured from the origin URL (e.g. `affiliate_id`, `sub_id`).
</ResponseField>

<ResponseField name="sub_id" type="string">
  The sub ID recorded on the click.
</ResponseField>

<ResponseField name="trace_id" type="string">
  Trace identifier for the click.
</ResponseField>

<ResponseField name="click_tracking" type="boolean">
  Whether click tracking was enabled for this outclick.
</ResponseField>

<ResponseField name="merchant" type="object">
  Merchant identity (`id`, `object_id`, `name`). Populated for **merchant** outclicks; on product clicks the merchant is under `product.merchant`.
</ResponseField>

<ResponseField name="network" type="object">
  Network identity (`id`, `object_id`, `name`). Populated for **merchant** outclicks; on product clicks the network is under `product.network`.
</ResponseField>

<ResponseField name="product" type="object">
  The offer snapshot for **product** outclicks. `null` on merchant outclicks.

  <Expandable title="Product object">
    <ResponseField name="id" type="string">
      The product (offer) ID.
    </ResponseField>

    <ResponseField name="name" type="string">
      The product name captured in the offer snapshot.
    </ResponseField>

    <ResponseField name="urls.direct" type="string">
      The direct product URL from the offer snapshot.
    </ResponseField>

    <ResponseField name="regular_price" type="float">
      The regular price at click time.
    </ResponseField>

    <ResponseField name="final_price" type="float">
      The final price at click time.
    </ResponseField>

    <ResponseField name="on_sale" type="boolean">
      Whether the product was on sale at click time.
    </ResponseField>

    <ResponseField name="currency" type="string">
      ISO currency code at click time.
    </ResponseField>

    <ResponseField name="availability" type="string">
      Availability at click time (e.g. `InStock`).
    </ResponseField>

    <ResponseField name="merchant" type="object">
      The merchant (provider) data.

      <Expandable title="Merchant object">
        <ResponseField name="id" type="string">
          The network merchant (provider) ID.
        </ResponseField>

        <ResponseField name="object_id" type="string">
          The Affiliate.com merchant object ID (`nmer_` prefix).
        </ResponseField>

        <ResponseField name="name" type="string">
          The merchant name.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="network" type="object">
      The network (provider) data.

      <Expandable title="Network object">
        <ResponseField name="id" type="string">
          The network (provider) ID.
        </ResponseField>

        <ResponseField name="object_id" type="string">
          The Affiliate.com network object ID (`rnet_` prefix).
        </ResponseField>

        <ResponseField name="name" type="string">
          The network name.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="client" type="object">
  The client (visitor) data captured at click time.

  <Expandable title="Client object">
    <ResponseField name="country" type="string">
      Two-letter client country code.
    </ResponseField>

    <ResponseField name="is_robot" type="boolean">
      Whether the click was identified as a robot.
    </ResponseField>

    <ResponseField name="robot_name" type="string">
      The robot name, when identified.
    </ResponseField>

    <ResponseField name="device_type" type="string">
      The client device type (e.g. `desktop`).
    </ResponseField>

    <ResponseField name="browser_name" type="string">
      The client browser name.
    </ResponseField>

    <ResponseField name="browser_version" type="string">
      The client browser version.
    </ResponseField>
  </Expandable>
</ResponseField>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.

---

## Integration Guides

---

# Connect an AI agent over MCP

Source: https://guides.affiliate.com/guides/mcp.md

> ## 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.

# Connect an AI agent over MCP

> Search products, look up merchants and networks, and convert product identifiers through an MCP-compatible AI client instead of writing REST integration code.

Affiliate.com exposes an [MCP](https://modelcontextprotocol.io) (Model Context Protocol) interface alongside the REST API, so an MCP-compatible AI client — Claude Code, Claude Desktop, Cursor, or any other MCP client — can search products, look up merchants and networks, and convert product identifiers directly through natural-language tool calls.

MCP is a separate interface from the REST API: different host, different tools, different authentication.

<Note>
  MCP requires an active MCP subscription on your account. A request from an account without one returns `403 Forbidden`.
</Note>

## Connecting

MCP servers are hosted on their own domain, not `api.affiliate.com`:

```
https://mcp.affiliate.com/{server}
```

Five servers are available, each exposing a different set of tools:

| Path | Tools |
| - | - |
| `/product` | `search-products` |
| `/merchant` | `list-merchants`, `get-merchant` |
| `/network` | `list-networks`, `get-network` |
| `/conversion` | `asin-to-barcode`, `barcode-to-asin`, `barcode-to-sku`, `sku-to-barcode`, `url-to-barcode` |
| `/all` | Every tool above, on one server |

Use `/all` unless your client benefits from a narrower toolset — for example, to keep an agent's available tools focused on one domain.

<Warning>
  Authentication is **OAuth 2.1** — there is no API key or bearer token to configure. Your MCP client discovers the authorization endpoints automatically and walks you through sign-in the first time you connect.
</Warning>

<Frame caption="The consent screen your MCP client shows on first connection.">
  <img src="https://mintcdn.com/affiliatecom-e0014deb/rKY9SEPsK3-A_lNv/images/mcp-oauth-consent.jpg?fit=max&auto=format&n=rKY9SEPsK3-A_lNv&q=85&s=f35cbcb5ec89e30b74ea46e63d2c1998" alt="Affiliate.com OAuth authorization request screen" width="1600" height="1008" data-path="images/mcp-oauth-consent.jpg" />
</Frame>

<Tabs>
  <Tab title="ChatGPT">
    <Steps>
      <Step title="Enable Developer mode">
        Go to **Settings → Apps → Advanced Settings** and enable **Developer mode**.
      </Step>

      <Step title="Create the app">
        Click **Create App**:

        * Name: `Affiliate.com` (or any name you prefer)
        * MCP Server: `https://mcp.affiliate.com/all`
        * Check "I understand and want to continue"
        * Click **Create**
      </Step>

      <Step title="Use it in a chat">
        In the chat box, click **+ → More… → Affiliate.com**.
      </Step>
    </Steps>

    <Note>A ChatGPT Plus or Pro account is required to use this feature.</Note>
  </Tab>

  <Tab title="Claude">
    <Steps>
      <Step title="Add a custom connector">
        Go to **Settings → Connectors → Add custom connector**.
      </Step>

      <Step title="Create the app">
        Click **Create App**:

        * Name: `Affiliate.com` (or whatever you prefer)
        * Remote MCP Server URL: `https://mcp.affiliate.com/all`
        * Click **Add**.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Claude Code / CLI">
    ```bash theme={null}
    claude mcp add --transport http affiliate https://mcp.affiliate.com/all
    ```

    Complete the OAuth sign-in flow when your client prompts for it.
  </Tab>
</Tabs>

## Example prompts

Once connected, ask your AI client things like:

* "Find 50 merchants with 20,000+ products that have logos. Show me their network info and their logo image URLs."
* "What are the barcodes for these ASINs? B08DH979F7 and B09LNWG826"
* "Find laptops between \$500–\$700 USD, sorted by price. Give me also their PDP URLs."
* "I'm looking for a comfortable office chair for back pain, my budget is \$400, and I prefer buying it from Walmart."
* "Find 10 Sony or Samsung headphones under \$100 USD that are on sale now. Avoid duplicates. I need their product info, merchant and network info, and PDP URLs."
* "Compare Nike vs Adidas running shoes — get merchant and price stats."

## Rate limits and usage

The same per-account rate limits that apply to the REST API apply to MCP requests.

Each tool call also consumes account credits, at a weight that reflects the work it does:

| Tool | Credits |
| - | - |
| `search-products` | 4 |
| `list-merchants`, `list-networks` | 2 |
| Everything else (`get-merchant`, `get-network`, and all `/conversion` tools) | 1 |

## Tools

### `search-products`

<sub>`/product`, `/all`</sub>

Search and filter products — the same field/value/operator search used by [`POST /v1/products`](/api-reference/products/search), with a reduced operator set and feature list tuned for AI clients.

| | |
| - | - |
| **Fields** | id, name, description, any · regular\_price, final\_price, on\_sale, sale\_discount, currency · brand, category, color, condition, country, gender, genre, manufacturer, model, size, material, author, artist, publisher, subtitle, tags · barcode, sku, mpn, asin · network.id, network.name · merchant.id, merchant.name · in\_stock, stock\_quantity, availability, commissionable\_status · url, direct\_url, image\_url, commission\_url · added\_at, updated\_at |
| **Operators** | Text: `=`, `!=`, `LIKE`, `NOT LIKE`, `IS NULL`, `NOT NULL`. Numeric/date: `=`, `!=`, `<`, `<=`, `>`, `>=`, `BETWEEN` |
| **OR conditions** | `"field": "name\|\|brand"` searches multiple fields · `"value": "Nike\|\|Adidas\|\|Puma"` matches any value · `"value": "50\|200"` (single pipe) is a `BETWEEN` range |
| **Facets** | `network`, `merchant`, `final_price` only |
| **Field filtering** | `fields` limits the response to the fields you name (dot notation for nested fields, e.g. `network.name`); omit it and every field is returned |
| **Pagination** | Page-based, maximum 100 products per page |

<Note>
  Natural-language query rewriting, semantic search, and image-based search are not available on this tool.
</Note>

### `list-merchants`

<sub>`/merchant`, `/all`</sub>

List merchants with filtering, search, and pagination.

* **Standard mode** (default): filter by network IDs, presence of icon/logo/description/domains, and product count range.
* **Extended mode** (`extended: true`): adds category (id or name), canonical hierarchy, country (origin/market/generic), currency, feed language, approval status (`relationship_status`), approval scoped to a network credential (`credential_id`), promotion count range, plus `country_ids` / `origin_ids` / `shopnomix_campaign_ids`. In extended mode, `network_ids` accepts prefixed IDs (`rnet_` for regional networks, `net_` for canonical networks).
* `search` matches merchant name or domain.
* Pagination: page-based, maximum 100 per page.

### `get-merchant`

<sub>`/merchant`, `/all`</sub>

Get full details for one merchant by `id`. Pass `include_deleted: true` to also retrieve archived (soft-deleted) merchants.

### `list-networks`

<sub>`/network`, `/all`</sub>

List networks with filtering, search, and pagination — filter by `group_ids`, `country_ids`, or `record_type` (`products` or `coupons`); search by network name; sort by name, merchant count (total or active), product count, or country. Pagination: page-based, maximum 100 per page.

### `get-network`

<sub>`/network`, `/all`</sub>

Get full details for one network by `id`, including its country and network group.

### Conversion tools

<sub>`/conversion`, `/all`</sub>

Five tools convert between product identifier types:

| Tool | Converts | Limit per request |
| - | - | - |
| `asin-to-barcode` | Amazon ASINs → barcodes (EAN/UPC), given a marketplace locale | 10 |
| `barcode-to-asin` | Barcodes (EAN/UPC) → Amazon ASINs | 20 |
| `barcode-to-sku` | Barcodes → merchant SKUs | 100 |
| `sku-to-barcode` | Merchant SKUs → barcodes | 100 |
| `url-to-barcode` | Product URLs → barcodes | 100 |

`barcode-to-sku` and `sku-to-barcode` need a merchant, identified by either `merchant_name` (e.g. `"walmart"`) or `merchant_url` (any URL on the merchant's domain).

### Response shape

Every tool returns the same top-level structure:

```json theme={null}
{
  "meta": { "...": "tool-specific metadata, e.g. pagination or conversion counts" },
  "data": "the result — an object, or an array for list/conversion tools"
}
```

Values that can't be resolved come back as `null` or an empty array in `data`, not an error.

## Best practices

* **Be specific.** More specific queries return better results — "wireless over-ear headphones under \$100 from Sony or Bose" beats "headphones." Include brand, price range, or category when you know them.
* **Use facets to explore.** Before drilling into a large result set, ask for facets to see its shape: "Search for 'running shoes' with merchant and price facets."
* **Paginate by page number.** Ask for a specific page — "Get page 2 of the laptop search results" — every list and search tool paginates this way.
* **Chain tools for multi-step tasks.** For example: search for products by keyword, pull barcodes for the ones you like, then convert those barcodes to ASINs to check Amazon availability. The `find-products-by-merchant` and `find-products-by-region` [prompts](#prompts) below already encode the most common chains.

## Prompts

Beyond tools, the `/product`, `/merchant`, `/network`, and `/all` servers also expose MCP **prompts** — pre-built templates for common multi-step tasks that an MCP client can invoke directly:

| Prompt | What it does |
| - | - |
| `find-products` | Plans a `search-products` call from a natural-language query. |
| `count-products` | Plans a count-only `search-products` call. |
| `format-search-results` | Style guide for presenting `search-products` output (count, list, or comparison). |
| `find-products-by-merchant` | Finds products at a specific merchant by chaining `list-merchants` → `search-products`. |
| `find-products-by-region` | Finds products from networks in a country/region by chaining `list-networks` → `search-products`. |
| `disambiguate-merchant` | Picks the right merchant ID from an ambiguous name search. |
| `inspect-merchant` | Retrieves full merchant details by ID or name, resolving ambiguity automatically. |
| `audit-merchant-data-quality` | Finds merchants missing metadata (icon, logo, description, domains). |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.

---

# Outclick + Shopnomix — join clicks to conversions

Source: https://guides.affiliate.com/guides/outclick-shopnomix-join.md

> ## 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.

# Outclick + Shopnomix — join clicks to conversions

> Pull Affiliate.com outclick data and join it to Shopnomix conversions for the full click-to-sale picture.

This guide shows how to pull individual click rows from Affiliate.com, pull individual
conversions from Shopnomix, and join them on a shared click id to get the full
**click → sale** picture.

## Overview

| Step | Source | What you get |
| - | - | - |
| 1. Pull outclicks | Affiliate.com `GET /v1/reports/outclick` | Every click, plus product, price, merchant, and `sub_id` |
| 2. Pull conversions | Shopnomix `GET /api/v2/reporting/conversion` | Revenue and commission status, only when a sale happens |
| 3. Join | `cl-` + outclick `id` = conversion `click_id` | Clicks matched to sales |

<Info>
  You don't need to configure anything to make the join work. When Affiliate.com builds a
  Shopnomix outclick redirect, it automatically appends `cid=cl-<id>` to the outbound URL,
  where `<id>` is the same click identifier returned as the `id` field in the outclick
  report. Shopnomix captures that value in its `click_id` field.
</Info>

## Step 1 — Get clicks (Affiliate.com)

Use [`GET /v1/reports/outclick`](/api-reference/reports/outclick) to retrieve individual
click rows, including the product, price, merchant, and `sub_id`.

| Parameter | Required | Notes |
| - | - | - |
| `start_at` | Yes | Inclusive start. RFC 3339 timestamp or UTC date. |
| `end_at` | Yes | Exclusive end. At least 5 minutes in the past; no more than 24 hours after `start_at`. |
| `page` | No | Defaults to `1`. |
| `per_page` | No | 1–1000. Defaults to `100`. |
| `sub_id` | No | Exact-match filter. |

See the [endpoint reference](/api-reference/reports/outclick) for the full parameter and
response field list.

### Example request

```bash theme={null}
curl -s "https://api.affiliate.com/v1/reports/outclick\
?start_at=2026-07-27T00:00:00Z\
&end_at=2026-07-28T00:00:00Z\
&per_page=100" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <AFFILIATE_COM_API_KEY>"
```

### Example response row

```json theme={null}
{
  "id": "01kyn6z1rg0vnabvnenwfxr25c",
  "created_at": "2026-07-28T20:34:23.000000Z",
  "sub_id": "homepage",
  "product": {
    "id": "8544191246662442858",
    "name": "Bose QuietComfort Headphones",
    "final_price": 229.99,
    "currency": "USD",
    "merchant": { "id": "54419", "name": "Target" },
    "network": { "id": "335", "name": "Impact US" }
  },
  "client": { "country": "US", "device_type": "desktop" }
}
```

<Note>
  **Join key from this row.** Prefix the outclick `id` with `cl-` to get the value Shopnomix
  stores in `click_id`: `cl-01kyn6z1rg0vnabvnenwfxr25c`.
</Note>

## Step 2 — Get conversions (Shopnomix)

Use `GET /api/v2/reporting/conversion` on `https://r.v2i8b.com`. This returns individual
conversions, each with a `click_id` you can join on. Shopnomix does **not** expose a
per-click feed — only conversions.

| Parameter | Required | Notes |
| - | - | - |
| `campaign_id` | Yes | Your Shopnomix campaign ID. |
| `start_date` | Yes | `YYYY-MM-DD` (inclusive). |
| `end_date` | Yes | `YYYY-MM-DD` (inclusive). |
| `limit` | No | Page size (e.g. `1000`). |

**Auth:** `Authorization: Bearer <SHOPNOMIX_API_KEY>` · **Pagination:** follow
`meta.next_page` until it is `null`.

### Example request

```bash theme={null}
curl -s "https://r.v2i8b.com/api/v2/reporting/conversion\
?campaign_id=<SHOPNOMIX_CAMPAIGN_ID>\
&start_date=2026-07-27\
&end_date=2026-07-28\
&limit=1000" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <SHOPNOMIX_API_KEY>"
```

### Example response

```json theme={null}
{
  "data": [
    {
      "commission_id": "5349.6782.1234927",
      "click_id": "cl-01kyn6z1rg0vnabvnenwfxr25c",
      "root_domain": "target.com",
      "revenue": "12.50",
      "status": "OPEN",
      "country": "US",
      "source": "homepage",
      "click_time": "2026-07-28T20:34:23",
      "last_updated": "2026-07-28T21:10:00.000000",
      "metadata": {}
    }
  ],
  "meta": {
    "next_page": null
  }
}
```

<Warning>
  Only rows with a non-null `click_id` can be joined. Conversions with `click_id: null` have
  no link back to the outclick report.
</Warning>

## Step 3 — Join for the full picture

Join on the click id, adding the `cl-` prefix to the outclick `id`:

```
conversion.click_id === "cl-" + outclick.id
```

For example, an outclick `id` of `01kyn6z1rg0vnabvnenwfxr25c` matches a Shopnomix
`click_id` of `cl-01kyn6z1rg0vnabvnenwfxr25c`.

| From Outclick | From Shopnomix |
| - | - |
| Every click + product, price, merchant, `sub_id` | Revenue + commission status (only when a sale happens) |
| Outclick row with no matching conversion | A click with no sale (yet) |
| — | Conversion with `click_id: null` → cannot be joined |

### Pseudo-code

```text theme={null}
outclicks    = GET api.affiliate.com /v1/reports/outclick?...
conversions  = GET r.v2i8b.com /api/v2/reporting/conversion?...

by_click_id = index conversions by click_id

for row in outclicks:
    cid  = "cl-" + row.id
    sale = by_click_id.get(cid)          # may be null

    # full picture = click fields + sale.revenue / sale.status
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.