# Merchant lookup API: find Affiliate.com retailers by name or country

Affiliate.com's Merchants API lists the merchants behind its product catalog, filtered by name, country or product count, and returns one merchant's record by id, at $0.02 a request. Send `GET https://zeroclick.affiliate.com/zcj/gj1g6uu77pad/v1/merchants` with query filters, then `GET https://zeroclick.affiliate.com/zcj/gj1g6uu77pad/v1/merchants/{id}` for one merchant. Each call comes back first as a 402 stating its price; pay it and send the call again.

## At a glance

- **List endpoint:** `GET https://zeroclick.affiliate.com/zcj/gj1g6uu77pad/v1/merchants`
- **Detail endpoint:** `GET https://zeroclick.affiliate.com/zcj/gj1g6uu77pad/v1/merchants/{id}`, with optional `extended=true`
- **Filters:** `search`, `id`, `country_ids`, `product_count_min`, `product_count_max`, `fields`, `page`, `per_page`
- **Price:** $0.02, the same for every page size
- **Payment:** each call's 402 states its price; settle it in USDC over x402 or MPP and repeat the call. Nothing to sign up for.
- **Response:** JSON with `data` (the merchant records) and `meta` (paging and a `trace_id`)
- **Full purchase flow:** [the buyer skill](https://zeroclick.affiliate.com/zcj/gj1g6uu77pad/SKILL.md)

## Find merchants by name, country or catalog size

1. Send the list request with your filters:

   ```bash
   curl -s "https://zeroclick.affiliate.com/zcj/gj1g6uu77pad/v1/merchants?search=outdoor&per_page=3"
   ```

   The storefront returns a 402 with this shape:

   ```text
   HTTP/1.1 402 Payment Required
   {"error": "payment_required",
    "payment": {"amountUsd": "<string>", ...},
    "plan": {...},
    "protocols": {<a challenge for each rail offered>}}
   ```

   `payment.amountUsd` is the exact price. The signable challenges also arrive as response headers: `payment-required` for x402 and `www-authenticate` for MPP. Nothing is charged at this point, so it is safe to stop here.

2. Pay the 402 with your x402 or MPP client and send the same request again with the proof attached. The 200 response follows this shape, with types from the API reference:

   ```text
   {"data": [{"id": <integer>, "name": "<string>", "description": <string or null>,
              "domains": [<string>], "icon_url": <string or null>, "logo_url": <string or null>,
              "product_count": <integer>, "origin_id": <string or null>}],
    "meta": {"total": <integer>, "from": <integer>, "to": <integer>,
             "current_page": <integer>, "last_page": <integer>, "per_page": <integer>,
             "fields": [<string>]}}
   ```

   The example search paid $0.02 and returned three records in `data`. The example response's records contained `id`, `name`, `description`, `domains`, `icon_url`, `logo_url`, `product_count` and `origin_id`.

3. Page through the results if `meta.last_page` is greater than `meta.current_page`. Send the same filters with `page=2`, and so on. Each page is a separate request with its own 402.

4. Read one merchant using the `id` from a record:

   ```bash
   curl -s "https://zeroclick.affiliate.com/zcj/gj1g6uu77pad/v1/merchants/<id>?extended=true"
   ```

   The 402 quotes $0.02 again. After payment, `data` is a single merchant object and `meta` carries `trace_id`. `extended=true` adds expanded data such as the canonical record, categories, countries and network details.

## Choose the filters

| To get | Send |
| --- | --- |
| Merchants matching a name, domain or id | `search=walmart` (1 to 255 characters) |
| One known merchant in list form | `id=930288` (a numeric id or an `nmer_` ULID) |
| Merchants selling in given countries | `country_ids=US` (comma-separated ISO country codes) |
| Merchants with a large catalog | `product_count_min=1000` |
| Merchants with a small catalog | `product_count_max=500` |
| Only some fields per record | `fields=id,name,domains,product_count` |
| A different page or page size | `page=2`, `per_page=25` (`page` defaults to 1 and `per_page` to 100, and both are at least 1) |

Filters combine. For example, `country_ids=US&product_count_min=1000&per_page=25` returns US merchants with at least 1000 products, 25 to a page. Other record fields you can name in `fields` include `slug`, `home_url`, `countries`, `currencies`, `categories`, `network`, `object_id` and `canonical`. The full parameter list is in the [API reference](https://zeroclick.affiliate.com/zcj/gj1g6uu77pad/openapi.json).

## What is charged and what is not

- Each request is one charge of $0.02, whatever its `per_page`. A one-record page paid $0.02, the same as the three-record search.
- Four requests cost $0.08, since the list and detail calls are priced the same.
- An unpaid 402 charges nothing.
- The Merchants API only reads merchant records. Products come from the separate Product Search service, at $0.02.
- To draw from a prepaid balance instead, buy Credits (minimum $0.50, or $0.50 by card) with a bearer credential. A bearer credential is the agent identity the storefront issues at [auth.md](https://zeroclick.affiliate.com/zcj/gj1g6uu77pad/auth.md). The plan's purchase path is `/plans/{planId}/purchase`, and you find the plan in the [catalog](https://zeroclick.affiliate.com/zcj/gj1g6uu77pad/manifest.json).

## Errors

| Response | Meaning | Action |
| --- | --- | --- |
| `402` with a `payment` block | The per-request price quote | Pay it and retry the same request, or stop |
| `settlement_failed` | Your payment did not settle. `settlementReason` says why. | Fix the wallet, then send the request again for a fresh 402 |
| `409 payment_request_mismatch` | A payment was reused for a different request, such as another page | Pay a fresh 402 for each request |
| `rate_limit_exceeded` | Too many requests | Wait `retry_after` or `Retry-After`, then retry |
| `usage_exhausted` | Your Credits balance is used up | Top up with `POST https://zeroclick.affiliate.com/zcj/gj1g6uu77pad/extend`, or pay per request |

After a paid call is forwarded, the status and body come from Affiliate.com's own API. The full list of error codes is in [errors.md](https://zeroclick.affiliate.com/zcj/gj1g6uu77pad/errors.md).

## Frequently asked questions

### Can I find retailers by country with this API?

Yes. Pass `country_ids` with one or more comma-separated ISO country codes, such as `country_ids=US`. You can combine it with `search` and the product count filters in the same request.

### How much does a merchant lookup cost?

$0.02 per request, for a list page of any size and for a single merchant's details. The 402 states the exact amount before you pay.

### Do I need an account or API key to list merchants?

No. Pay-as-you-go calls are paid one at a time through the 402 quote over x402 or MPP. You need an agent identity only to buy Credits.

### What identifier does the merchant detail call accept?

`/v1/merchants/{id}` accepts a numeric id, an `nmer_` ULID, a `mer_` canonical id or a slug. The numeric `id` from a list record works directly.

### Does the Merchants API return the products a merchant sells?

No. It returns merchant records, including `product_count`. To list products, use Affiliate.com's Product Search service.

## Keep reading

- [Buyer skill](https://zeroclick.affiliate.com/zcj/gj1g6uu77pad/SKILL.md): the full purchase flow
- [How to pay](https://zeroclick.affiliate.com/zcj/gj1g6uu77pad/payment.md): the 402, x402, MPP, card and Credits
- [API reference](https://zeroclick.affiliate.com/zcj/gj1g6uu77pad/openapi.json): every parameter and response field
- [Error reference](https://zeroclick.affiliate.com/zcj/gj1g6uu77pad/errors.md): codes and actions

---

Updated 2026-10-16. All Affiliate.com guides: https://zeroclick.affiliate.com/guides.md. Storefront: https://zeroclick.affiliate.com/zcj/gj1g6uu77pad/llms.txt.