Merchants API

The Merchants API exposes Fyralynx's merchant knowledgebase - all 35 supported merchants with their current EPC hints, network coverage, regional availability, capability flags, and canonicalization metadata. Use it to build merchant comparison UIs, validate routing decisions, or understand which merchants are available for a given visitor country.

Base path: https://api.fyralynx.com/v1
Tier required: Publisher or Enterprise

---

The Merchant Object

{
  "merchantId": "amazon",
  "displayName": "Amazon",
  "description": "Global e-commerce flagship. 8 storefronts across US, IN, GB, DE, FR, CA, AU, JP. Supported via CJ, Awin, Impact, Admitad, Cuelinks, and Rakuten.",
  "domains": [
    "www.amazon.com",
    "www.amazon.co.uk",
    "www.amazon.in",
    "www.amazon.de",
    "www.amazon.fr",
    "www.amazon.ca",
    "www.amazon.com.au",
    "www.amazon.co.jp"
  ],
  "programType": "network",
  "supportedNetworks": ["CJ", "Awin", "Impact", "Admitad", "Cuelinks", "Rakuten"],
  "merchantCapabilities": {
    "deepLinking": true,
    "appIndexing": true,
    "utmPreservation": true,
    "multiNetworkRouting": true
  },
  "regionDefaults": {
    "baseCurrency": "USD",
    "epcBaseUsd": 0.035,
    "trustScore": 90
  },
  "regions": {
    "US": {
      "storefront": "www.amazon.com",
      "baseCurrency": "USD",
      "epcHints": {
        "CJ":       0.031,
        "Impact":   0.035,
        "Rakuten":  0.030,
        "Admitad":  0.000,
        "Cuelinks": 0.000
      },
      "trustScore": 90,
      "preferredNetworks": ["Impact", "CJ", "Rakuten"],
      "deepLinkSupported": true,
      "deepLinkMultiplier": 0.12,
      "deviceBiases": {
        "ios":     0.03,
        "android": 0.02,
        "desktop": 0.00
      },
      "availabilityFlags": {
        "globalAvailability": false,
        "stockAware": false,
        "shipsToCountries": ["US", "CA", "GB", "AU", "DE", "FR", "JP", "SG", "MX", "AE"]
      },
      "categoryMultipliers": {
        "Electronics": 1.05,
        "Computers":   1.08,
        "Mobile":      1.06,
        "Fashion":     1.12,
        "Books":       0.95,
        "Home":        1.02,
        "Sports":      1.03
      },
      "refundRateEstimate": 0.05,
      "codFactor": 1.0,
      "passthroughRequired": false
    },
    "IN": {
      "storefront": "www.amazon.in",
      "baseCurrency": "INR",
      "epcHints": {
        "CJ":       0.000,
        "Impact":   0.028,
        "Admitad":  0.025,
        "Cuelinks": 0.030,
        "Rakuten":  0.000,
        "Awin":     0.000
      },
      "trustScore": 88,
      "preferredNetworks": ["Cuelinks", "Impact", "Admitad"],
      "deepLinkSupported": true,
      "deepLinkMultiplier": 0.10,
      "deviceBiases": {
        "ios":     0.02,
        "android": 0.08,
        "desktop": 0.00
      },
      "availabilityFlags": {
        "globalAvailability": false,
        "stockAware": false,
        "shipsToCountries": ["IN"]
      },
      "codFactor": 0.82,
      "refundRateEstimate": 0.07
    }
  },
  "meta": {
    "version": "2026-03-15-01",
    "lastUpdated": "2026-03-15T10:00:00Z",
    "dataConfidenceScore": 92,
    "changelogNotes": "Updated Impact EPC hint for US region based on Q1 2026 affiliate community reports."
  }
}

Field reference

Field	Type	Description
merchantId	string	Unique merchant identifier (lowercase, hyphenated).
displayName	string	Human-readable merchant name.
description	string	Summary of merchant coverage and network availability.
domains	string[]	All hostname variants for this merchant across all regions.
programType	string	network (routed via affiliate networks) or direct (in-house affiliate program only).
supportedNetworks	string[]	Affiliate networks through which this merchant is available. Empty array for direct programs.
merchantCapabilities.deepLinking	boolean	Whether app deep links are supported for any region.
merchantCapabilities.appIndexing	boolean	Whether the merchant supports app indexing (Google App Indexing).
merchantCapabilities.utmPreservation	boolean	Whether UTM parameters survive the merchant's redirect chain.
merchantCapabilities.multiNetworkRouting	boolean	Whether the creator can route between competing networks for this merchant. false for direct programs.
regionDefaults.epcBaseUsd	number	Fallback EPC in USD when no region-specific hint is available.
regionDefaults.trustScore	number	Default trust score (0-100).
regions	object	Keyed by region code (ISO 3166-1 alpha-2, or GLOBAL). See region sub-object below.
meta.version	string	Version string (YYYY-MM-DD-NN).
meta.dataConfidenceScore	number	0-100 confidence in the accuracy of EPC hints and metadata. < 70 triggers CI failure.

Region sub-object

Field	Type	Description
storefront	string	Hostname for this region's storefront.
baseCurrency	string	ISO 4217 currency code for epcHints values.
epcHints	object	Per-network EPC estimate in baseCurrency. 0 means the network is not available in this region.
trustScore	number	Trust score (0-100) for this region.
preferredNetworks	string[]	Recommended network order for this merchant+region.
deepLinkSupported	boolean	Whether app deep links are supported in this region.
deepLinkMultiplier	number	EPC bonus for validated deep links (0.0-0.12).
deviceBiases.ios	number	iOS device bias modifier (−0.05 to +0.10).
deviceBiases.android	number	Android device bias modifier.
deviceBiases.desktop	number	Desktop device bias modifier (often 0.0 - desktop is neutral).
availabilityFlags.shipsToCountries	string[] | null	ISO 3166-1 alpha-2 codes this storefront ships to. null = global availability.
categoryMultipliers	object	Per-category EPC multiplier keyed by FyralynxCategory name.
refundRateEstimate	number	Estimated refund rate (0.0-1.0). Feeds refund_penalty_r in the EPC formula.
codFactor	number	Cash-on-delivery conversion factor (0.0-1.0). Applies to IN/NG/PH/VN/ID markets.
passthroughRequired	boolean	When true, Fyralynx cannot canonicalize or re-route this merchant's links.

---

GET /merchants - List all merchants

Returns all 35 supported merchants. Results are ordered alphabetically by merchantId.

Tier: Publisher+

Query parameters

Parameter	Type	Description
region	string	Filter to merchants that have a storefront in this region code (e.g. IN, NG, SG).
networkId	string	Filter to merchants available via this affiliate network.
availableInCountry	string (ISO 3166-1 alpha-2)	Filter to merchants whose shipsToCountries includes this country (or whose list is null - globally available).

Response - 200 OK

{
  "data": {
    "merchants": [
      {
        "merchantId": "aliexpress",
        "displayName": "AliExpress",
        "programType": "network",
        "supportedNetworks": ["Impact", "Admitad"],
        "merchantCapabilities": {
          "deepLinking": false,
          "appIndexing": false,
          "utmPreservation": false,
          "multiNetworkRouting": true
        },
        "regionDefaults": {
          "baseCurrency": "USD",
          "epcBaseUsd": 0.022,
          "trustScore": 72
        },
        "meta": {
          "version": "2026-01-20-01",
          "lastUpdated": "2026-01-20T08:00:00Z",
          "dataConfidenceScore": 80
        }
      },
      {
        "merchantId": "amazon",
        "displayName": "Amazon",
        "programType": "network",
        "supportedNetworks": ["CJ", "Awin", "Impact", "Admitad", "Cuelinks", "Rakuten"],
        "merchantCapabilities": {
          "deepLinking": true,
          "appIndexing": true,
          "utmPreservation": true,
          "multiNetworkRouting": true
        },
        "regionDefaults": {
          "baseCurrency": "USD",
          "epcBaseUsd": 0.035,
          "trustScore": 90
        },
        "meta": {
          "version": "2026-03-15-01",
          "lastUpdated": "2026-03-15T10:00:00Z",
          "dataConfidenceScore": 92
        }
      }
    ],
    "total": 35
  }
}

Note: The list response returns a summary of each merchant (without per-region detail). Use GET /merchants/{id} for the full profile including per-region EPC hints, device biases, and canonicalization rules.

curl example

# All 35 merchants
curl "https://api.fyralynx.com/v1/merchants" \
  -H "Authorization: Bearer $FYRALYNX_API_KEY"

# Merchants available in Nigeria
curl "https://api.fyralynx.com/v1/merchants?availableInCountry=NG" \
  -H "Authorization: Bearer $FYRALYNX_API_KEY"

# Merchants on Involve Asia
curl "https://api.fyralynx.com/v1/merchants?networkId=InvolveAsia" \
  -H "Authorization: Bearer $FYRALYNX_API_KEY"

# Merchants with an India storefront
curl "https://api.fyralynx.com/v1/merchants?region=IN" \
  -H "Authorization: Bearer $FYRALYNX_API_KEY"

---

GET /merchants/{id} - Get a merchant

Returns the full merchant profile for a single merchant, including all regional EPC hints, device biases, canonicalization rules, category multipliers, and availability flags.

Tier: Publisher+

Path parameters

Parameter	Type	Description
id	string	Merchant ID (e.g. amazon, flipkart, jumia, lazada). Case-sensitive lowercase.

Response - 200 OK

Full merchant profile as shown in The Merchant Object above.

curl examples

# Full Amazon profile
curl "https://api.fyralynx.com/v1/merchants/amazon" \
  -H "Authorization: Bearer $FYRALYNX_API_KEY"

# Jumia Africa profile (direct in-house program)
curl "https://api.fyralynx.com/v1/merchants/jumia" \
  -H "Authorization: Bearer $FYRALYNX_API_KEY"

# Lazada SE Asia (Involve Asia network)
curl "https://api.fyralynx.com/v1/merchants/lazada" \
  -H "Authorization: Bearer $FYRALYNX_API_KEY"

TypeScript example

interface MerchantRegion {
  storefront: string;
  baseCurrency: string;
  epcHints: Record<string, number>;
  trustScore: number;
  preferredNetworks: string[];
  deepLinkSupported: boolean;
  deepLinkMultiplier: number;
  deviceBiases: { ios: number; android: number; desktop: number };
  availabilityFlags: {
    globalAvailability: boolean;
    stockAware: boolean;
    shipsToCountries: string[] | null;
  };
  categoryMultipliers: Record<string, number>;
  refundRateEstimate: number;
  codFactor: number;
  passthroughRequired: boolean;
}

interface MerchantProfile {
  merchantId: string;
  displayName: string;
  programType: 'network' | 'direct';
  supportedNetworks: string[];
  regions: Record<string, MerchantRegion>;
  meta: {
    version: string;
    lastUpdated: string;
    dataConfidenceScore: number;
    changelogNotes: string;
  };
}

async function getMerchant(merchantId: string): Promise<MerchantProfile> {
  const response = await fetch(
    `https://api.fyralynx.com/v1/merchants/${merchantId}`,
    {
      headers: {
        Authorization: `Bearer ${process.env.FYRALYNX_API_KEY}`,
      },
    },
  );

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`Fyralynx ${response.status}: ${error.code}`);
  }

  const { data } = await response.json();
  return data;
}

---

Complete Merchant List

All 35 merchants supported at launch:

merchantId	Display Name	Region	Networks	Program Type
amazon	Amazon	US, IN, GB, DE, FR, CA, AU, JP	CJ, Awin, Impact, Admitad, Cuelinks, Rakuten	Network
walmart	Walmart	US	CJ, Impact, Rakuten	Network
bestbuy	Best Buy	US	CJ, Impact, Rakuten	Network
target	Target	US	CJ, Impact, Rakuten	Network
ebay	eBay	US, GB, DE, AU, IN	CJ, Awin, Impact, Cuelinks	Network
aliexpress	AliExpress	GLOBAL	Impact, Admitad	Network
newegg	Newegg	US	CJ, Impact	Network
bandh	B&H Photo Video	US	CJ, Impact	Network
etsy	Etsy	US, GB, DE	Awin	Network
wayfair	Wayfair	US, GB, CA	CJ, Awin, Rakuten	Network
macys	Macy's	US	CJ, Impact, Rakuten	Network
nordstrom	Nordstrom	US	CJ, Impact, Rakuten	Network
zappos	Zappos	US	CJ, Impact	Network
homedepot	Home Depot	US	CJ, Impact, Rakuten	Network
asos	ASOS	GLOBAL	Awin, CJ	Network
zalando	Zalando	DE, FR, GB, NL, SE	Awin	Network
argos	Argos	GB	Awin, CJ	Network
currys	Currys	GB	Awin, CJ	Network
otto	Otto	DE	Awin	Network
decathlon	Decathlon	GLOBAL	Awin, Impact, Admitad	Network
rakuten-marketplace	Rakuten (marketplace)	JP	Rakuten	Network
flipkart	Flipkart	IN	Flipkart Affiliate (in-house)	Direct
myntra	Myntra	IN	Flipkart Affiliate (in-house)	Direct
nykaa	Nykaa	IN	Cuelinks, Admitad	Network
tatacliq	TataCliq	IN	Cuelinks, Admitad	Network
croma	Croma	IN	Cuelinks, Admitad	Network
lazada	Lazada	SG, MY, TH, ID, PH, VN	Involve Asia	Network
shopee	Shopee	SG, MY, TH, ID, PH, VN, TW	Involve Asia	Network
noon	Noon	AE, SA, EG	Noon Affiliate (in-house)	Direct
namshi	Namshi	AE, SA	Awin, Admitad	Network
jumia	Jumia	NG, KE, GH, EG, ZA, MA	Jumia Affiliate (in-house)	Direct
takealot	Takealot	ZA	- (affiliate programme closed)	Passthrough
mercadolibre	Mercado Libre	BR, MX, AR, CO, CL	Impact, Awin	Network
temu	Temu	US, IN, EU	CJ, Impact, Cuelinks, Rakuten	Network
shein	Shein	US, GB	CJ, Impact, Awin, Rakuten	Network

Note: Shein does not have an India region. Shein India has been banned since June 2020. Any attempt to route shein.in will result in passthrough: true automatically.

---

Direct Programs

Merchants with programType: "direct" operate in-house affiliate programs and do not route through any of the 7 affiliate networks:

Merchant	Program	Markets
Flipkart	Flipkart Affiliate	IN
Myntra	Flipkart Affiliate (shared)	IN
Noon	Noon Affiliate	AE, SA, EG
Jumia	Jumia Affiliate	NG, KE, GH, EG, ZA, MA

For direct-program merchants:

• supportedNetworks is an empty array.
• multiNetworkRouting is false.
• The creator must be independently registered with the merchant's in-house program.
• Fyralynx routes between merchants (e.g. Jumia NG vs Amazon US for a Nigerian visitor) but not between competing networks for the same merchant.
• Links can be created with passthrough: true to preserve the creator's existing affiliate URL exactly.

---

Merchant Data Freshness

Each merchant profile carries a meta.version (YYYY-MM-DD-NN) and meta.lastUpdated timestamp. Every change to any merchant profile is logged in the public Fyralynx changelog (filter by Data Update) with a description of what changed.

The meta.dataConfidenceScore (0-100) reflects the ops team's confidence in the accuracy of that profile's EPC hints and metadata:

• ≥ 90: High confidence. Data verified from multiple sources.
• 70-89: Good confidence. Primary source verified, some estimates.
• < 70: Lower confidence. CI will fail - a profile at this score requires investigation.

The dataConfidenceScore influences the confidence field in routing decisions and CRC traces.

---

EPC Hint Interpretation

epcHints[networkId] values are expressed in the region's baseCurrency. A value of 0 means the network is not available for this merchant/region combination - the routing engine will never generate a candidate for a zero-EPC-hint network.

"epcHints": {
  "CJ":       0.031,
  "Impact":   0.035,
  "Rakuten":  0.030,
  "Admitad":  0.000,
  "Cuelinks": 0.000
}

In this example, Admitad and Cuelinks are not available for Amazon US - only CJ, Impact, and Rakuten are candidates for this region. The routing engine applies all 16 EPC signals on top of these base hints to compute the final ROUTE_SCORE.

---

Error Reference

Code	Status	Description
NOT_FOUND	404	Merchant with this ID does not exist. Use GET /merchants to list all valid IDs.
PUBLISHER_TIER_REQUIRED	403	API access requires Publisher or Enterprise plan.
RATE_LIMIT_EXCEEDED	429	Rate limit exceeded.

---

See Also

• API Overview - base URL, authentication, response format
• Links API - create routed links using merchant data
• Concepts: EPC Model - how EPC hints feed the scoring formula
• Concepts: Routing Explained - candidate generation and merchant selection
• Fyralynx changelog - public record of every merchant profile update (filter by Data Update)