API Reference (merchant integration)

For merchant site integrators: endpoints for reporting and querying data only. Authentication: after merchant login you receive a JWT; send it in the header Authorization: Bearer <token>.

Base URL: In production use the current domain (the site’s own origin, e.g. https://afflixo.com). No localhost in production. Local development: http://localhost:3820. Requests and responses are JSON; use Content-Type: application/json.

1. Public API — no API key

Identify the merchant by Merchant Slug; there is no separate API key. Get the slug from the dashboard URL or merchant settings (e.g. reviewgrow in /domain/reviewgrow/dashboard).

1. Report click

Report a click when a user lands via a referral link (with ref=CODE). Used for stats and attribution. Usually called by the front-end SDK; back-end can call it too.

POST /api/<merchantSlug>/track/click
Content-Type: application/json

{
  "affiliateCode": "ABC123"
}

Parameter	Type	Required	Description
affiliateCode	string	yes	Affiliate code (from URL `ref=` or header `X-Affiliate-Code`)

Responses

201: { "ok": true, "merchantId": "...", "cookieDuration": 30, "clickId": "..." }
The SDK stores clickId in the cookie so conversions can be linked to this click.
400: Missing affiliateCode
404: Merchant not found or invalid affiliate code
429: Too many requests from this IP

2. Report conversion (order)

Report a completed order for commission. Idempotent by orderId per merchant. Can be called from the browser (e.g. window.Affiliate.trackConversion(...)) or from the merchant back-end.

POST /api/<merchantSlug>/track/conversion
Content-Type: application/json

{
  "orderId": "ORD-12345",
  "amount": 99.00,
  "currency": "USD",
  "affiliateCode": "ABC123",
  "clickId": "optional, from cookie",
  "transactionId": "optional",
  "email": "[email protected]",
  "productName": "Product name"
}

Parameter	Type	Required	Description
orderId	string	yes	Merchant order id; unique per merchant (idempotency key)
amount	number	yes	Order amount used for commission
currency	string	no	Currency code; default USD
affiliateCode	string	no*	Affiliate code (*required if not sent via cookie or header `X-Affiliate-Code`)
clickId	string	no	From cookie; links conversion to click for first-order attribution
transactionId	string	no	Optional; for your records
email	string	no	Customer email; visible only to merchant/admin
productName	string	no	Product or order description

Responses

201: { "conversionId": "...", "commissionAmount": 9.9, "status": "pending" }
200: Same orderId resubmitted; same body; no duplicate commission
400: Invalid params or missing affiliate
404: Merchant not found or invalid affiliate code

2. Merchant API — JWT required

Merchant admin receives a JWT after login. Login: POST /api/auth/merchant-admin/login, body { "email": "...", "password": "..." }; response includes token.

Header: Authorization: Bearer <token>

1. Get affiliates list

Paginated list of affiliates for the current merchant.

GET /api/merchant/affiliates?page=1&limit=20&status=active
Authorization: Bearer <token>

Query param	Type	Required	Description
page	number	no	Page number; default 1
limit	number	no	Page size; default 20, max 100
status	string	no	Filter: active / suspended / pending

Response

{
  "affiliates": [
    {
      "affiliateId": "...",
      "userId": "...",
      "email": "[email protected]",
      "affiliateCode": "AF123456",
      "status": "active",
      "createdAt": "2024-01-01T00:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 50,
    "totalPages": 3
  }
}

2. Get single affiliate earnings

Clicks, conversions, commission summary, and payouts for one affiliate.

GET /api/merchant/affiliates/<affiliateId>/earnings
Authorization: Bearer <token>

Response

{
  "affiliateId": "...",
  "affiliateCode": "AF123456",
  "status": "active",
  "totalClicks": 100,
  "totalConversions": 10,
  "pendingCommission": 50.00,
  "approvedCommission": 200.00,
  "paidCommission": 150.00,
  "totalPayouts": 150.00,
  "conversions": [ { "conversionId", "order_id", "amount", "commission_amount", "status", "createdAt" } ],
  "payouts": [ { "payoutId", "amount", "status", "method", "createdAt", "paidAt" } ]
}

3. Get payouts list (paginated)

Paginated payout records for the current merchant.

GET /api/merchant/payouts?page=1&limit=20&status=requested
Authorization: Bearer <token>

Query param	Type	Required	Description
page	number	no	Page number; default 1
limit	number	no	Page size; default 20, max 100
status	string	no	Filter: requested / approved / paid

Response

{
  "payouts": [
    {
      "payoutId": "...",
      "affiliateId": "...",
      "affiliateCode": "AF123456",
      "amount": 100.00,
      "status": "requested",
      "method": "paypal",
      "createdAt": "...",
      "paidAt": null
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 30,
    "totalPages": 2
  }
}

3. Errors and conventions

401: Missing or invalid JWT (Merchant API)
404: Resource not found (e.g. affiliate not in current merchant)
429: Too many requests
Conversion endpoint is idempotent by orderId; duplicate submissions with the same orderId do not create duplicate commission.

For setup and script usage see the User guide.