Merchant Data API: affiliate merchant feed and Firm entities in one REST contract

When to use Merchant Data API vs sibling pages

Endpoints: account firms and global merchant catalogue

Both surfaces are Bearer-token JSON POSTs. Successful list calls count toward monthly API caps on your plan. Catalog has no offerUrl; account /me includes tracked links on related coupon/product rows when available.

Account-scoped firms vs catalog display-name dedupe

Curl and JSON examples

Create an fdco_ token in the dashboard, then POST JSON. Spec: openapi-customer.yaml. Docs hub: /docs.

curl -sS -X POST "https://api.feedico.io/api/v1/me/networks" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"page":1,"pageSize":50}'

{
  "ok": true,
  "recordCount": 2,
  "page": 1,
  "pageSize": 50,
  "networks": [
    {
      "id": "net_1001",
      "provider": "cj_affiliate",
      "displayName": "Example Outdoor Co",
      "externalMerchantKey": "4210991",
      "merchantWebsiteUrl": "https://www.example-outdoor.com",
      "status": "active",
      "couponCount": 14,
      "fetchedAt": "2026-09-07T12:00:00.000Z"
    },
    {
      "id": "net_1002",
      "provider": "awin_affiliate",
      "displayName": "Example Beauty EU",
      "externalMerchantKey": "18822",
      "merchantWebsiteUrl": "https://www.example-beauty.eu",
      "status": "active",
      "couponCount": 9,
      "fetchedAt": "2026-09-07T11:55:00.000Z"
    }
  ],
  "availableProviders": ["cj_affiliate", "awin_affiliate"]
}

curl -sS -X POST "https://api.feedico.io/api/v1/catalog/networks" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"page":1,"pageSize":50,"q":"outdoor"}'

{
  "ok": true,
  "recordCount": 1,
  "page": 1,
  "pageSize": 50,
  "networks": [
    {
      "id": "firm_agg_88a1",
      "displayName": "Example Outdoor Co",
      "providers": ["cj_affiliate", "impact_com"],
      "merchantWebsiteUrl": "https://www.example-outdoor.com",
      "couponCountWithCode": 22
    }
  ]
}

Field glossary: Firm entity

Architecture workflow: merchant feed into your product

1. Connect networks in the dashboard with credentials for programmes you are approved to promote.
2. Sync Firms via scheduled jobs; upsert on (provider, externalMerchantKey) into your warehouse.
3. Page /me/networks with page/pageSize (and filters such as provider or q) until you have the full merchant set.
4. Join children: coupons via /me/coupons, products via /me/products.
5. Optional discovery with /catalog/networks when you need brand search without another publisher's tracking URL. See unified affiliate API.

Networks (CJ / Awin / Impact / …)
        |  sync adapters
        v
   Firm rows  (/me/networks)
        |\
        | \__ Coupon rows  (/me/coupons)
        | \__ Product rows (/me/products)
        v
  Your CMS / warehouse / AI agent

Catalog discovery (optional):
  /catalog/networks  →  displayName aggregates (no offerUrl)

Merchant Data API FAQ

What is a Merchant Data API in Feedico?

The Merchant Data API exposes Firm rows: merchant or programme entities synced from affiliate networks you connected. Primary endpoints are POST /api/v1/me/networks (account-scoped) and POST /api/v1/catalog/networks (global discovery, deduped by display name).

What is a Firm entity?

Firm is Feedico's normalized merchant/programme object. It carries provider, externalMerchantKey, displayName, merchantWebsiteUrl, status, couponCount, and sync timestamps. Coupons and products reference firms via networkId or firmName depending on the surface.

What is externalMerchantKey?

externalMerchantKey is the upstream network's stable merchant or programme identifier. Combined with provider, it forms the natural upsert key for account-scoped firms: (provider, externalMerchantKey).

How does /me/networks differ from /catalog/networks?

/me/networks returns firms from programmes you connected with your credentials, one row per provider+key. /catalog/networks is a cross-tenant discovery index that merges merchants by display name and does not share other publishers' tracking URLs.

Does the merchant catalogue include offerUrl?

No. Catalog networks omit publisher-specific tracking links. Use /me endpoints when you need tracked offerUrl values from your own sync. Catalog rows are for discovery and merchant metadata only.

How is couponCount calculated?

On account-scoped network rows, couponCount reflects active promo rows linked to that firm for your tenant. Catalog aggregates may expose couponCountWithCode for coded offers under the deduped display name.

Do I need a Bearer token?

Yes. Both /me/networks and /catalog/networks require Authorization: Bearer with an fdco_ API token. Successful calls count toward your plan's monthly API request cap (UTC month).

When should I use Merchant Data API vs Coupon API?

Use Merchant Data API to list stores, filter by provider, and power merchant directories or shop indexes. Use the Coupon API (/coupon-api) when you need promo codes, titles, eligibility windows, and offerUrl for listing pages.