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"
}

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",
  "note": "Optional note (e.g. campaign, source)"
}

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

3. Report signup (customer signup)

Record a customer signup attributed to an affiliate. Used for visibility only (no commission). Idempotent by signupId per merchant. Call from the browser (e.g. window.Affiliate.trackSignup(...)) or from your back-end after a user completes registration.

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

{
  "signupId": "user-12345",
  "affiliateCode": "ABC123",
  "clickId": "optional, from cookie",
  "email": "[email protected]",
  "role": "premium"
}

Responses

• 201: { "signupRecordId": "...", "signupId": "user-12345", "role": "premium", "createdAt": "..." }
• 200: Same signupId resubmitted; returns existing record
• 400: Missing signupId or missing affiliate
• 404: Merchant not found or invalid affiliate code

SDK: window.Affiliate.trackSignup({ signupId: "user-12345", email: "[email protected]", role: "premium" }) — affiliate and clickId come from cookie if omitted.

Signup list (admin/affiliate): GET /api/admin/signups and GET /api/affiliate/signups support query params role (filter by role), sortBy=createdAt|role, sortOrder=asc|desc. Response includes roles: string[] (distinct roles for filter dropdown).

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>

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>

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. Signup endpoint is idempotent by signupId per merchant.

Get affiliate code after page load: The SDK exposes window.Affiliate.onReady(callback). Register a callback; it runs when the script has finished (and when the visitor arrived with ref=CODE, after the track/click request completes and the cookie is set). Then call window.Affiliate.getAffiliateCode() inside the callback to get the current affiliate code, or null if none.

window.Affiliate.onReady(function() {
  var code = window.Affiliate.getAffiliateCode();
  if (code) { /* use for conversion or display */ }
});

For setup and script usage see the User guide.