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.- 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
Authorization: Bearer <YOUR_API_KEY>) — 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. (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 aproviders array. Each entry is one way to earn commission on this merchant — one network or subnetwork.
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
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 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 fromstatus. 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 asurl).
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 for a full worked example.
5. Deep-linking to any page
When a provider’sdeeplink 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):
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.
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
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.
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 withpool_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.
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.
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 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), so the providers below resolve against that pool’s own credentials rather than your account’s default pool: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.)
Step 3 — Homepage link — use the provider you’re approved with (Shopnomix, in this example). Take its outclick and fill your IDs:
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:
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: