> ## 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.
# Monetizing with the Merchants API
> Turn the Merchants endpoint's per-provider links, tracked outclicks, and deeplink formula into revenue — for any link to a merchant, not just products.
You already use the [Products API](/api-reference/products/search) to turn commissionable *products* into revenue. The Merchants endpoint gives you the same building blocks for the *merchant itself* — the links to reach it and a deeplink formula — so you can monetize any link to a brand: an editorial mention, a "Shop HelloFresh" button, a homepage link, or a deep link to any page on the merchant's site — no specific product required.
## Which API should I use?
**Start here.** Pick based on *what you're linking to* — **not** on whether the merchant has products. Most merchants support both, and you can use both.
| You want to link to… | Use |
| ------------------------------------------------------------------------------------------ | ---------------------------------------------- |
| A **specific product** — a price, a SKU, "buy this item", product grids, comparison, feeds | [Products API](/api-reference/products/search) |
| The **merchant itself** — homepage, a category, a "Shop X" button, an editorial mention | **Merchants API** (this guide) |
* **A merchant can be monetized more than one way.** Even when a merchant lists individual products, the brand or homepage may also be linkable — but which routes actually earn depends on your agreement with each provider (the network, and Shopnomix where present), not on where you place the link.
* **Nothing to link at the product level?** Some merchants have no products to link (`product_count: 0` — services, travel, finance, subscriptions). The merchant-level link here is the only way to earn on them.
**Affiliate.com doesn't run the affiliate programs and doesn't pay commission.** Each entry in `providers` is a network or subnetwork you earn *through* — an affiliate network (e.g. Awin, Impact) or a link subnetwork (e.g. Shopnomix). Whether a link actually earns depends on **your own approved relationship** with that provider (its `status`). Affiliate.com surfaces the merchant, your standing, and the links; the commercial relationship — approval, tracking, and payment — is between you and the provider.
## 1. The endpoint
```
GET https://api.affiliate.com/v1/merchants?extended=1&search=hellofresh
```
Send your API key as a bearer token (`Authorization: Bearer `) — your per-provider links and standing only appear on authenticated requests.
`extended=1` is what returns the commissionable links — they come back **inside the response**, as each merchant's `providers` array (`url` / `template` / `outclick`); there's no separate "commissionable URL" endpoint. `search=hellofresh` just locates that one merchant. To find the merchants you can monetize, drop the name search and page the list reading each row's `providers[].url` — see [§6](#6-finding-merchants-to-monetize). (Reach for `has_commissionable_url=1` only if you specifically want merchants with a stored link *template*; it is not the same set, and it is usually smaller.)
**Send `extended=1` even if you've seen `providers` without it.** Whether the extended fields come back by default depends on your account, so don't rely on it — some accounts get them automatically and some don't. Passing the flag is harmless either way, and it's the difference between a response that has commissionable links and one that doesn't. Every example in this guide includes it.
## 2. The providers array
Each merchant returns a `providers` array. **Each entry is one way to earn commission on this merchant** — one network or subnetwork.
| Field | What it is |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `provider` | Which network/subnetwork this entry is (e.g. `network`, `shopnomix`). |
| `status` | Your standing with this provider: `approved`, `pending`, `available`, `rejected`, `terminated`, `unavailable`, `unknown`, or `null` if you have no record. |
| `status_changed_at` | When your status last changed. |
| `credential_id` | The network credential your standing/link is tied to, or `null`. |
| `url` | A ready-to-use link built with your credentials — goes **straight to the provider's network** (not recorded by us). `null` when the provider has no built link for you; it tracks whether one exists, not what `status` says. |
| `template` | The shareable placeholder link — `{AFF_ID}` = your affiliate/campaign ID, `{SUB_ID}` = your sub-ID. Replace them to build your own link (also straight to the network). `null` if there's no shareable form. |
| `outclick` | A **tracked** link through Affiliate.com's redirector: when followed it records the click, then forwards to the provider. It carries the same `{AFF_ID}`/`{SUB_ID}` placeholder slots as `template` — fill them with your own IDs (whatever you pass is what gets credited). `null` only if there's nothing to link. |
| `supports_deeplinking` | Whether you can deep-link to any page on the merchant's site (`true`/`false`, or `null` if unknown). |
| `deeplink` | The deep-link builder (`domain` + `template`), or `null` if the provider can't deep-link. **`network` is always `null` here, even when `supports_deeplinking` is `true`** — that flag just relays what the network itself reports about its own capability; Affiliate.com has no redirect of its own to rewrite for a third-party network, so it can never hand you a deeplink template for one. Only a link-service provider (currently Shopnomix) — which wraps the destination in a redirect Affiliate.com owns — can populate this. See [§5](#5-deep-linking-to-any-page). |
| `approval` | The program's terms **as reported by the network** — commission structure, cookie window, dates, and an HTML `terms_and_conditions`. The `commission_data`/`epc_data` shapes vary by network. Present when your status is `approved` **or** `available` (so you can see the offer before applying), and `null` when the provider reports no terms (e.g. Shopnomix, whose links are built from your Shopnomix credential's campaign rather than a network approval record). Note that an entire network can report no terms — on a synced Awin pool every sampled merchant was `approved` with an empty `approval` — so don't rely on terms being present. |
**Use `outclick`.** It's not a required field, but for merchant-level links it's the default choice — there's rarely a reason to reach for `url`/`template` instead. `url` and `template` go **straight to the network** — Affiliate.com never sees the click, so it never shows up anywhere on our side. `outclick` routes **through us first**, so the click is recorded and shows up in `GET /v1/reports/outclick?offer_type=merchant` (the report defaults to `product`) — reconciliation against your provider's own reporting, a paper trail if a provider disputes a click, and a single report across every provider on every merchant. Either way the link carries your credentials to the same destination — the only difference is that `outclick` records the click on our side first. Publish `url`/`template` directly only when you have a specific reason to skip that record.
## 3. Placeholders
| Token | What it is |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `{AFF_ID}` | Your affiliate/campaign ID. Replace this **token** wherever it appears. The query-param around it varies by provider — `campaign_id` on Shopnomix, `id` on an Awin `awclick.php` link, `affiliate_id` on an `outclick` (`aff_id` on an AdMedia one) — but you only ever swap the `{AFF_ID}`, never the param name. |
| `{SUB_ID}` | Your sub-ID / source (attribution). Same idea — the surrounding param name varies (`source`, `sub_id`, …); just swap the `{SUB_ID}`. |
| `{target_url}` | An [RFC 6570](https://datatracker.ietf.org/doc/html/rfc6570)-style token (used in deeplink templates). Replace with your **URL-encoded** destination. |
**The rule is simple: replace the `{AFF_ID}`, `{SUB_ID}`, and `{target_url}` tokens wherever they appear, and leave the surrounding query-parameter names exactly as they are.** A single link can carry several at once — e.g. an unfilled deep-link holds `{target_url}` next to `{AFF_ID}`/`{SUB_ID}`.
These `{AFF_ID}`/`{SUB_ID}` names are used in the **merchants** response. The [Products API](/api-reference/products/search) still uses `@@@`/`###` for the same slots.
## 4. Which link do I use?
**Default to `outclick`.** It's the only one Affiliate.com records, so it's what makes a merchant-level link show up in your reporting at all — reach for `url`/`template` only when you deliberately don't want that.
* **`outclick`** — the **tracked** link (records the click, then forwards to the provider). This is the one to publish. Fill its `{AFF_ID}`/`{SUB_ID}` slots with your own IDs — whatever you pass is credited, so use your real ID.
* **`url`** — your ready-to-use link straight to the network (not recorded by us). Populated when the provider has a built link for you — check the field itself rather than inferring it from `status`. Use this only if you have your own tracking in place and don't need ours.
* **`template`** — build it yourself: replace `{AFF_ID}` with your affiliate/campaign ID and `{SUB_ID}` with your sub-ID (also straight to the network, same caveat as `url`).
**Read `url` to see what you have; read `status` to see whether it will earn.** They answer different questions and don't move together — a provider can show `available` and still return a usable `url`, or show `approved` with `url: null`. If `url` is `null`, build from `template`/`outclick` instead. Either way a link only **earns** once you're approved **by that provider** — Affiliate.com can't grant that for you.
See [§8](#8-end-to-end-example) for a full worked example.
## 5. Deep-linking to any page
When a provider's `deeplink` object is non-null, it lets you send commissionable traffic to *any* page on the merchant's site (check `deeplink` itself — `supports_deeplinking: true` on a `network` provider doesn't mean this object exists; see the table above):
```json theme={null}
"deeplink": {
"domain": "hellofresh.com",
"template": "https://r.v2i8b.com/api/v1/bid/redirect?url={target_url}&campaign_id={AFF_ID}&source={SUB_ID}"
}
```
* `domain` — your target page must be on this domain (the merchant's home URL can be a marketing path, so don't derive the domain from it).
* `template` — replace `{target_url}` with your **URL-encoded** destination, and replace `{AFF_ID}`/`{SUB_ID}` with your IDs.
```
https://r.v2i8b.com/api/v1/bid/redirect?url=https%3A%2F%2Fhellofresh.com%2Fplans&campaign_id=YOUR_ID&source=YOUR_SUBID
```
A deep link is the **provider's own** redirect (Shopnomix's, here) — the visitor goes straight to the provider, not through Affiliate.com's `outclick.co`. So deep-linked clicks won't appear in your `GET /v1/reports/outclick` report (there's no deep-link version of `outclick`); only the homepage-level `outclick` routes through us and is recorded. You still **earn** on deep links — they're just not measured on our side.
## 6. Finding merchants to monetize
| Goal | Parameter |
| ----------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| By record type (what they monetize) | `type[]=service` (see below) |
| By name | `search=hellofresh` |
| Merchants with a stored link template (**not** the same as "merchants I can link" — see caveat below) | `has_commissionable_url=1` |
| Only merchants you're approved with | `relationship_status=approved` |
| By category (fuzzy name or alias) | `category=meal kit` |
| By category ID (Shopify/Google) | `category_ids=fb-2-15-2` |
| Scoped to a pool (which merchants + whose credentials build the links) | `pool_id=` (see [§7](#7-pools)) |
`search` does a partial, case-insensitive match on the merchant's name and website URL. It does not match on `origin_id`, the internal `id`, or `nmer_`/`mer_` object IDs — only name/URL substrings — so both `search=hellofresh` (name) and `search=hellofresh.com` (website URL) find HelloFresh.
**`relationship_status` reads from merchant sync against your network credentials** — it has nothing to check on an account with no network credential at all. Verified live on a Shopnomix-only account: every value (including `approved`) returned zero merchants even though the account had 14+ merchants with `providers[].shopnomix.status: "approved"`. If you monetize only through Shopnomix, page the unfiltered list and read each merchant's `providers[].shopnomix.url` / `.status` yourself — there's no dedicated filter for non-network provider standing today.
**`has_commissionable_url=1` is not a substitute for that.** It matches only merchants with a stored `commissionable_url` **template**, and a link built from a synced approval's tracking URL needs no template — so the filter silently drops merchants you can earn on. Verified live on an Awin pool of 1834 merchants: the filter returned 834, and **all 1000** excluded merchants had a populated `providers[].url` (e.g. `1&1` → `https://www.awin1.com/awclick.php?mid=12554&id=84833`, ready to use, `template: null`). Use `providers[].url` as the test for "do I have a link."
### Record types (`type`)
Filter merchants by what they monetize. **Requires `extended=1`.** Pass one or more values as an array (`type[]=service&type[]=products`); a merchant matches if it has **any** of them.
| Value | Matches |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `products` | Merchants that list individual products |
| `service` | Service merchants — monetized by a single commissionable link rather than individual products (travel, subscriptions, finance, meal kits, etc.) |
| `promotions` | Merchants with active promotions (alias: `coupons`) |
Special values: `all` (no type filter), `none` (merchants with no record types).
**Service merchants** (travel, finance, meal kits, subscriptions, etc.) often have `product_count: 0` but are still fully commissionable — they just have no products to link, which is exactly why the merchant-level link matters. Find them with `type[]=service`.
## 7. Pools
If you run more than one pool — separate credentials for separate sites or brands, say — you can scope a merchants request to exactly one of them with `pool_id`. It requires `extended=1`, and it does two things at once: restricts which merchants come back, and decides whose network credentials (**Pools → Sources**) build `providers[]` links and approval status.
```
GET https://api.affiliate.com/v1/merchants?extended=1&pool_id=01JPSEEDP1ATA11P0010000100&search=hellofresh
```
This is **not** the same merge behavior as `pool_id` on `POST /v1/products`, `/v1/products/omni`, or `/v1/promotions` — there, the pool's `networks`/`merchants` are combined with any `network_ids`/`merchant_ids` you also pass. Here it's a hard scope: only merchants collected into that pool come back — there's no separate `merchant_ids` request parameter for it to merge with.
| | Products / Omni / Promotions | Merchants (this guide) |
| ------------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| What `pool_id` does | Combines pool `networks`/`merchants` with request `network_ids`/`merchant_ids` | Restricts results to **only** merchants collected into that pool |
| Effect on links | N/A | Also decides whose credentials resolve `providers[].url`/`template`/`outclick` **first** — account-level credentials remain a fallback |
| Omitted | No scoping | No scoping; link/approval resolution falls back to your account's **default pool** |
A provider configured as a Source on one pool never applies when resolving links for a different pool's request — pass the `pool_id` that actually matches the merchant/credential set you mean to monetize through. This is **not** provider isolation, though: for a provider the pool owns no credential for, resolution falls back to your account-level credential, so a pool set up for one network still returns links for other providers (verified with Shopnomix), with a different campaign than a pool that owns its own. See the [Pools API reference](/api-reference/pools/overview#using-a-pool-with-get-v1-merchants) for the full details.
## 8. End-to-end example
**Goal:** place a tracked link to HelloFresh, using whichever provider you're approved with.
**Step 1 — Find the merchant.** Scoped to a pool (see [§7](#7-pools)), so the providers below resolve against that pool's own credentials rather than your account's default pool:
```
GET https://api.affiliate.com/v1/merchants?extended=1&pool_id=01JPSEEDP1ATA11P0010000100&search=hellofresh
```
**Step 2 — Read the providers**
```json theme={null}
{
"name": "HelloFresh",
"providers": [
{
"provider": "network",
"status": "available",
"status_changed_at": "2026-05-02T09:14:00+00:00",
"credential_id": "01kkgc7xxw8gg7y7f6wrnpgepv",
"url": null,
"template": "https://hellofresh.pxf.io/c/{AFF_ID}/1234/5678?subId1={SUB_ID}",
"outclick": "https://outclick.co/a/NetworkToken?affiliate_id={AFF_ID}&sub_id={SUB_ID}",
"supports_deeplinking": false,
"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"
}
}
},
{
"provider": "shopnomix",
"status": "approved",
"status_changed_at": "2026-08-07T15:25:13+00:00",
"credential_id": "01j8z3example000credential",
"url": "https://r.v2i8b.com/api/v1/bid/redirect?url=https%3A%2F%2Fhellofresh.com&campaign_id=01J8Z3K9QW7RT2VN5XB6MC4FDH&source={SUB_ID}",
"template": "https://r.v2i8b.com/api/v1/bid/redirect?url=https%3A%2F%2Fhellofresh.com&campaign_id={AFF_ID}&source={SUB_ID}",
"outclick": "https://outclick.co/a/ShopnomixToken?affiliate_id={AFF_ID}&sub_id={SUB_ID}",
"supports_deeplinking": true,
"deeplink": {
"domain": "hellofresh.com",
"template": "https://r.v2i8b.com/api/v1/bid/redirect?url={target_url}&campaign_id=01J8Z3K9QW7RT2VN5XB6MC4FDH&source={SUB_ID}"
},
"approval": null
}
]
}
```
**Read each provider's `url` first, then its `status`.** In this example Shopnomix has a `url` ready to use, and the network program has `url: null` so you'd build from its `template` instead. `status` tells you whether the link will earn, not whether one exists — don't infer either from the other. Your own standing may differ — not every account has a Shopnomix relationship. Use whichever provider **you're** approved with; if that's none yet, you can still build a link from `template`/`outclick` and apply — it earns once you're approved. (The example trims `approval` to the two fields you'll act on — `commission_data` and `epc_data`; the full object also carries the cookie window, dates, and terms — see the [merchant reference](/api-reference/merchants/list-merchants).)
**Step 3 — Homepage link** — use the provider you're approved with (Shopnomix, in this example). Take its `outclick` and fill your IDs:
```
https://outclick.co/a/ShopnomixToken?affiliate_id=YOUR_ID&sub_id=YOUR_SUBID
```
When a visitor follows it, Affiliate.com **records the click**, then forwards them to Shopnomix — so it lands in your report. Publish this, not the raw `url`, unless you specifically don't want the click recorded on our side.
**Step 4 — Deep link to `/plans`** — Shopnomix `supports_deeplinking`, so take `deeplink.template` and replace `{target_url}` with your URL-encoded page:
```
https://r.v2i8b.com/api/v1/bid/redirect?url=https%3A%2F%2Fhellofresh.com%2Fplans&campaign_id=01J8Z3K9QW7RT2VN5XB6MC4FDH&source={SUB_ID}
```
`url` and `deeplink.template` already carry your campaign ID because you're approved — just set `source` if you want attribution.
**Step 5 — A provider you're *not* approved with** — the `network` here is `available` and has `url: null`, so there's no ready-made link to publish; build from `template`/`outclick`. Its `approval` terms are still shown — the program's public offer, so you can weigh the commission before applying. Build a link now from `template`/`outclick` if you like, but it only **earns** once you're `approved`.
**Step 6 — See the clicks.** Merchant outclicks appear in the report under the `merchant` offer type:
```
GET https://api.affiliate.com/v1/reports/outclick?offer_type=merchant
```