Affiliate Management API

Manage affiliates, referral links, and commission configuration for your business programmatically.

Prerequisites

All endpoints in this document require a Bearer access token obtained via [POST /v1/auth/token](/docs/api/authentication).

Your API key must be granted the appropriate scopes:

Authorization: Bearer <access_token>

Referral Links

The referral link endpoint reference has moved to the dedicated Referral Links page. Use that page for list, create, bulk create, batch status, update, delete, and stats.

Commission Configuration

}’

#### Accepted Response — 202 Accepted

The request was accepted and queued for processing.

```json
{
  "success": true,
  "message": "Bulk creation queued.",
  "data": {
    "batch_id": 17,
    "status": "pending",
    "total_items": 3,
    "status_url": "/v1/affiliates/42/link-batches/17"
  }
}

Error Responses

The referral link endpoint reference has moved to the dedicated Referral Links page. Use that page for list, create, bulk create, batch status, update, delete, and stats.

Commission Configuration

Get Affiliate Commission

Retrieve the commission rate configuration for a specific affiliate, including the effective resolved rate.

GET /v1/affiliates/{id}/commission

Required scope: affiliates:read Rate limit: 120 requests/minute

Path Parameters

Example Request

curl "https://<API_DOMAIN>/v1/affiliates/42/commission" \
  -H "Authorization: Bearer <access_token>"

Success Response — 200 OK

{
  "success": true,
  "message": "OK",
  "data": {
    "affiliate_rate": 10.0,
    "business_default_rate": 8.0,
    "effective_rate": 10.0
  }
}

Error Responses

Set Affiliate Commission

Set or clear the individual commission rate override for an affiliate.

PUT /v1/affiliates/{id}/commission

Required scope: affiliates:write Rate limit: 60 requests/minute

Path Parameters

Request Body

Example Request — Set override

curl -X PUT "https://<API_DOMAIN>/v1/affiliates/42/commission" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{ "commission_rate": 20.0 }'

Example Request — Clear override

curl -X PUT "https://<API_DOMAIN>/v1/affiliates/42/commission" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{ "commission_rate": null }'

Success Response — 200 OK

{
  "success": true,
  "message": "Commission rate updated.",
  "data": {
    "affiliate_rate": 20.0,
    "business_default_rate": 8.0,
    "effective_rate": 20.0
  }
}

Error Responses

List Commission Rules for Link

List all commission rules attached to a referral link. Rules are returned ordered by priority (highest first), then by creation date.

GET /v1/links/{id}/commission-rules

Required scope: affiliates:read Rate limit: 120 requests/minute

Path Parameters

Example Request

curl "https://<API_DOMAIN>/v1/links/10/commission-rules" \
  -H "Authorization: Bearer <access_token>"

Success Response — 200 OK

{
  "success": true,
  "message": "OK",
  "data": [
    {
      "id": 5,
      "label": "Black Friday Deal",
      "commission_rate": 20.0,
      "priority": 10,
      "valid_from": "2026-11-28T00:00:00.000000Z",
      "valid_until": "2026-11-30T23:59:59.000000Z",
      "max_conversions": 100,
      "conversion_count": 45,
      "is_active": true,
      "status": "active",
      "created_at": "2026-10-01T09:00:00.000000Z"
    },
    {
      "id": 3,
      "label": "Always-on bonus",
      "commission_rate": 12.0,
      "priority": 0,
      "valid_from": null,
      "valid_until": null,
      "max_conversions": null,
      "conversion_count": 312,
      "is_active": true,
      "status": "active",
      "created_at": "2026-03-01T09:00:00.000000Z"
    }
  ]
}

Error Responses

Create Commission Rule

Attach a new commission rule to a referral link. Rules allow you to define time-limited promotions, conversion caps, or priority overrides on a per-link basis.

POST /v1/links/{id}/commission-rules

Required scope: affiliates:write Rate limit: 60 requests/minute

Path Parameters

Request Body

Example Request — Timed promotional rule

curl -X POST "https://<API_DOMAIN>/v1/links/10/commission-rules" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "commission_rate": 25.0,
    "label": "Launch Week Bonus",
    "priority": 5,
    "valid_from": "2026-05-01",
    "valid_until": "2026-05-07",
    "max_conversions": 50
  }'

Example Request — Permanent always-on rule

curl -X POST "https://<API_DOMAIN>/v1/links/10/commission-rules" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "commission_rate": 15.0,
    "label": "Base link rate"
  }'

Success Response — 201 Created

{
  "success": true,
  "message": "Created",
  "data": {
    "id": 8,
    "label": "Launch Week Bonus",
    "commission_rate": 25.0,
    "priority": 5,
    "valid_from": "2026-05-01T00:00:00.000000Z",
    "valid_until": "2026-05-07T00:00:00.000000Z",
    "max_conversions": 50,
    "conversion_count": 0,
    "is_active": true,
    "status": "scheduled",
    "created_at": "2026-04-13T10:00:00.000000Z"
  }
}

Error Responses

Update Commission Rule

Modify an existing commission rule. Only include fields you want to change.

Note: conversion_count is system-managed and cannot be updated via the API.

PATCH /v1/links/{linkId}/commission-rules/{ruleId}

Required scope: affiliates:write Rate limit: 60 requests/minute

Path Parameters

Request Body

All fields optional.

Example Request — Disable a rule

curl -X PATCH "https://<API_DOMAIN>/v1/links/10/commission-rules/8" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'

Example Request — Extend validity window

curl -X PATCH "https://<API_DOMAIN>/v1/links/10/commission-rules/8" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{ "valid_until": "2026-05-14" }'

Success Response — 200 OK

Returns the updated Commission Rule Object.

Error Responses

Delete Commission Rule

Permanently delete a commission rule. This cannot be undone. In-progress conversions already attributed to this rule are not affected.

DELETE /v1/links/{linkId}/commission-rules/{ruleId}

Required scope: affiliates:write Rate limit: 60 requests/minute

Path Parameters

Example Request

curl -X DELETE "https://<API_DOMAIN>/v1/links/10/commission-rules/8" \
  -H "Authorization: Bearer <access_token>"

Success Response — 204 No Content

Empty body.

Error Responses

Rate Limits

When a rate limit is exceeded, the API returns HTTP 429 Too Many Requests with the following headers:

Retry-After: 30
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0

Wait for the number of seconds indicated by Retry-After before retrying.

Error Reference

All errors follow the standard envelope:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "details": { }
  }
}

details is only present on VALIDATION_ERROR responses.

Error Codes

Validation Error Example

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": {
      "email": ["The email field is required."],
      "commission_rate": ["The commission rate must not be greater than 100."]
    }
  }
}

Quick Reference

Affiliate Endpoints

Referral Link Endpoints

Commission Endpoints

Business Settings

Configure your affiliate program settings, branding, and commission tiers via the API.

All settings endpoints require the settings:read or settings:write scope.

Settings Object

{
  "commission_rate": 10.0,
  "cookie_duration": 30,
  "auto_approve_enabled": false,
  "auto_approve_delay_days": 0,
  "auto_approve_min_amount": null,
  "auto_approve_max_amount": null,
  "allow_self_registration": false
}

Get All Settings

Retrieve all affiliate program settings for the business.

GET /v1/settings

Scope: settings:read

Response 200 OK

{
  "success": true,
  "message": "OK",
  "data": {
    "commission_rate": null,
    "cookie_duration": 30,
    "auto_approve_enabled": false,
    "auto_approve_delay_days": 0,
    "auto_approve_min_amount": null,
    "auto_approve_max_amount": null,
    "allow_self_registration": false
  }
}

Get Single Setting

Retrieve a single setting by key.

GET /v1/settings/{key}

Scope: settings:read

Path Parameters

Response 200 OK

{
  "success": true,
  "message": "OK",
  "data": {
    "key": "cookie_duration",
    "value": 30
  }
}

Error 404 Not Found — Unknown setting key.

Update Settings (Bulk)

Update one or more settings in a single request. Only provided fields are updated; omitted fields remain unchanged.

PUT /v1/settings

Scope: settings:write

Request Body (all fields optional)

{
  "commission_rate": 12.5,
  "cookie_duration": 45,
  "auto_approve_enabled": true,
  "auto_approve_delay_days": 7,
  "allow_self_registration": true
}

Response 200 OK — Returns the full settings object after update.

Update Single Setting

Update a single setting by key.

PUT /v1/settings/{key}

Scope: settings:write

Request Body

{
  "value": 90
}

Response 200 OK

{
  "success": true,
  "message": "Setting updated.",
  "data": {
    "key": "cookie_duration",
    "value": 90
  }
}

Error 403 Forbidden — Unknown or disallowed setting key.

Get Branding

Retrieve the business branding configuration.

GET /v1/settings/branding

Scope: settings:read

Response 200 OK

{
  "success": true,
  "message": "OK",
  "data": {
    "logo_url": "https://s3.amazonaws.com/bucket/logo.png",
    "primary_color": "#FF6B2B"
  }
}

Update Branding

Update the business logo URL and/or primary brand color. Pass remove_logo: true to clear the logo.

PUT /v1/settings/branding

Scope: settings:write

Request Body

{
  "logo_url": "https://cdn.example.com/logo.png",
  "primary_color": "#1A2B3C"
}

Response 200 OK — Returns the branding object after update.

Get Commission Tiers

Retrieve platform default tiers and custom business tiers.

GET /v1/settings/commission-tiers

Scope: settings:read

Commission Priority (lowest → highest): Platform base rate → Platform tiers → Business flat rate → Business tiers → Per-affiliate override.

Response 200 OK

{
  "success": true,
  "message": "OK",
  "data": {
    "using_custom": true,
    "platform_tiers": [
      { "min_amount": "0.00", "max_amount": "100.00", "rate": "5.00" }
    ],
    "business_tiers": [
      { "id": 12, "sort_order": 0, "min_amount": "0.00", "max_amount": "500.00", "rate": "8.00" }
    ]
  }
}

Create Commission Tier

Add a custom commission tier for the business. Tier ranges must not overlap.

POST /v1/settings/commission-tiers

Scope: settings:write

Request Body

Response 201 Created

{
  "success": true,
  "message": "Created",
  "data": {
    "id": 12,
    "sort_order": 0,
    "min_amount": "0.00",
    "max_amount": "500.00",
    "rate": "8.00"
  }
}

Error 422 Unprocessable Entity — Validation failure or overlapping range.

Update Commission Tier

Update an existing business commission tier.

PUT /v1/settings/commission-tiers/{id}

Scope: settings:write

Request Body — Same as Create Commission Tier.

Response 200 OK — Returns the updated tier.

Error 404 Not Found — Tier not found or belongs to another business.

Delete Commission Tier

Delete a business commission tier.

DELETE /v1/settings/commission-tiers/{id}

Scope: settings:write

Response 204 No Content

Error 404 Not Found — Tier not found or belongs to another business.

Reset Commission Tiers

Delete all custom business tiers, reverting to platform defaults.

POST /v1/settings/commission-tiers/reset

Scope: settings:write

Response 200 OK

{
  "success": true,
  "message": "Commission tiers reset to platform defaults."
}

Settings Endpoints Summary

—————————————Updated April 15, 2026——————————

Orders & Commissions API

Manage tracked conversions (orders), view commission statistics, approve or reject pending commissions, and export data.

Authentication

All endpoints require a Bearer access token with the appropriate scope. See authentication.md.

Endpoints

List Orders — GET /v1/orders

Returns a paginated list of conversions with filtering, sorting, and search.

Query Parameters

Example

curl "https://<API_DOMAIN>/v1/orders?status=pending&sort=order_total&direction=desc&per_page=10" \
  -H "Authorization: Bearer <access_token>"

Success Response — HTTP 200

{
  "success": true,
  "message": "OK",
  "data": {
    "items": [
      {
        "id": 42,
        "order_id": "#135419",
        "affiliate": {
          "id": 7,
          "name": "Salman",
          "referral_code": "SALMAN2026"
        },
        "customer": {
          "name": "Geonwoo Park",
          "email": "geonwoo@example.com"
        },
        "subtotal": "70.00",
        "discount_applied": "0.00",
        "tax": "0.00",
        "order_total": "70.00",
        "commission_rate": "10.00",
        "commission_amount": "7.00",
        "currency": "USD",
        "status": "pending",
        "converted_at": "2026-04-10T14:30:00.000000Z",
        "created_at": "2026-04-10T14:30:00.000000Z"
      },
      {
        "id": 41,
        "order_id": "#135380",
        "affiliate": null,
        "customer": null,
        "subtotal": "140.00",
        "discount_applied": "0.00",
        "tax": "0.00",
        "order_total": "140.00",
        "commission_rate": "0.00",
        "commission_amount": "0.00",
        "currency": "USD",
        "status": "approved",
        "converted_at": "2026-04-08T14:30:00.000000Z",
        "created_at": "2026-04-08T14:30:00.000000Z"
      }
    ],
    "meta": {
      "current_page": 1,
      "per_page": 10,
      "total": 2,
      "last_page": 1
    }
  }
}

Response Fields

Get Order Stats — GET /v1/orders/stats

Returns aggregated summary statistics for all conversions. Optionally filter by date range.

Query Parameters

Example

curl "https://<API_DOMAIN>/v1/orders/stats?from=2026-04-01&to=2026-04-15" \
  -H "Authorization: Bearer <access_token>"

Success Response — HTTP 200

{
  "success": true,
  "message": "OK",
  "data": {
    "total_orders": 2,
    "total_revenue": 210.00,
    "total_commission": 14.00,
    "pending_commission": 0.00,
    "approved_commission": 14.00
  }
}

Response Fields

Get Order Detail — GET /v1/orders/{id}

Returns the full detail for a single conversion, including line items and click attribution.

Path Parameters

Example

curl "https://<API_DOMAIN>/v1/orders/42" \
  -H "Authorization: Bearer <access_token>"

Success Response — HTTP 200

{
  "success": true,
  "message": "OK",
  "data": {
    "id": 42,
    "order_id": "#135380",
    "affiliate": {
      "id": 7,
      "name": "Salman",
      "referral_code": "SALMAN2026",
      "commission_rate": "10.00"
    },
    "customer": {
      "name": "Jane Smith",
      "email": "jane@example.com"
    },
    "subtotal": "140.00",
    "discount_applied": "0.00",
    "tax": "0.00",
    "order_total": "140.00",
    "commission_rate": "10.00",
    "commission_amount": "14.00",
    "currency": "USD",
    "status": "approved",
    "line_items": [
      { "name": "Mountain Bike Rental", "quantity": 1, "price": "140.00" }
    ],
    "ip_address": "192.168.1.100",
    "click": {
      "id": 123,
      "referral_link_id": 45,
      "landing_page": "https://mountainthreads.example.com/bikes",
      "referrer": "https://instagram.com",
      "created_at": "2026-04-08T10:00:00.000000Z"
    },
    "converted_at": "2026-04-08T14:30:00.000000Z",
    "created_at": "2026-04-08T14:30:00.000000Z",
    "updated_at": "2026-04-08T15:00:00.000000Z"
  }
}

Additional Detail Fields

These fields appear only in the detail response (not in the list):

Error — HTTP 404

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Order not found."
  }
}

Approve Order — POST /v1/orders/{id}/approve

Transitions a pending conversion to approved status. The commission is considered owed once approved.

Path Parameters

Body Parameters

Example

curl -X POST "https://<API_DOMAIN>/v1/orders/42/approve" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{ "notes": "Verified payment received" }'

Success Response — HTTP 200

{
  "success": true,
  "message": "Order #135419 approved.",
  "data": {
    "id": 42,
    "order_id": "#135419",
    "status": "approved",
    "commission_amount": "7.00",
    "updated_at": "2026-04-15T12:00:00.000000Z"
  }
}

Error — HTTP 409 (Invalid Status Transition)

{
  "success": false,
  "error": {
    "code": "INVALID_STATUS",
    "message": "Only pending conversions can be approved. Current status: approved"
  }
}

Error — HTTP 404

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Order not found."
  }
}

Reject Order — POST /v1/orders/{id}/reject

Transitions a pending conversion to rejected status. The commission is voided.

Path Parameters

Body Parameters

Example

curl -X POST "https://<API_DOMAIN>/v1/orders/42/reject" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Fraudulent order - chargeback received" }'

Success Response — HTTP 200

{
  "success": true,
  "message": "Order #135419 rejected.",
  "data": {
    "id": 42,
    "order_id": "#135419",
    "status": "rejected",
    "commission_amount": "7.00",
    "updated_at": "2026-04-15T12:00:00.000000Z"
  }
}

Error — HTTP 409 (Invalid Status Transition)

{
  "success": false,
  "error": {
    "code": "INVALID_STATUS",
    "message": "Only pending conversions can be rejected. Current status: approved"
  }
}

Bulk Approve — POST /v1/orders/bulk-approve

Approves multiple pending conversions in a single request. Non-pending conversions are silently skipped.

Body Parameters

Example

curl -X POST "https://<API_DOMAIN>/v1/orders/bulk-approve" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{ "ids": [42, 43, 44, 45, 46] }'

Success Response — HTTP 200

{
  "success": true,
  "message": "3 order(s) approved.",
  "data": {
    "approved_count": 3,
    "requested_count": 5,
    "skipped_count": 2
  }
}

Response Fields

Error — HTTP 422

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": {
      "ids": ["The ids field is required."]
    }
  }
}

Bulk Reject — POST /v1/orders/bulk-reject

Rejects multiple pending conversions in a single request. Non-pending conversions are silently skipped.

Body Parameters

Example

curl -X POST "https://<API_DOMAIN>/v1/orders/bulk-reject" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{ "ids": [47, 48], "reason": "Duplicate orders from same session" }'

Success Response — HTTP 200

{
  "success": true,
  "message": "2 order(s) rejected.",
  "data": {
    "rejected_count": 2,
    "requested_count": 2,
    "skipped_count": 0
  }
}

Response Fields

Export Orders — GET /v1/orders/export

Downloads all matching conversions as a CSV file. Same filters as the list endpoint but without pagination — returns all matching records up to 10,000 rows.

Query Parameters

Example

curl "https://<API_DOMAIN>/v1/orders/export?status=approved&from=2026-04-01" \
  -H "Authorization: Bearer <access_token>" \
  -o orders-export.csv

Success Response — HTTP 200

Content-Type: text/csv Content-Disposition: attachment; filename="orders-export-2026-04-15.csv"

Order ID,Affiliate Name,Affiliate Code,Subtotal,Discount,Tax,Order Total,Commission Rate (%),Commission Amount,Currency,Status,Customer Email,Converted At
#135380,Salman,SALMAN2026,140.00,0.00,0.00,140.00,10.00,14.00,USD,approved,jane@example.com,2026-04-08 14:30:00
#135419,,,70.00,0.00,0.00,70.00,0.00,0.00,USD,pending,geonwoo@example.com,2026-04-10 14:30:00

CSV Columns

Conversion Status Workflow

  ┌─────────┐
  │ pending  │ ← initial state (from SDK tracking)
  └────┬─────┘
       │
  ┌────┴────┐
  ▼         ▼
┌─────────┐ ┌──────────┐
│ approved│ │ rejected │
└─────────┘ └──────────┘

  ┌───────────┐
  │ cancelled │ ← set by system (order cancellation)
  └───────────┘

• Only pending conversions can be approved or rejected via the API.
• Attempting to approve/reject a non-pending conversion returns HTTP 409.
• The cancelled status is set by the system when an order is cancelled — it is not available as an API action.

Error Reference

Rate Limiting

Exceeding the limit returns HTTP 429 Too Many Requests.

—————————————Updated April 16, 2026——————————

Affiliate Reports API

Performance analytics and payout overview for affiliate programs. Retrieve stat cards with trend indicators, time-series commission charts, affiliate leaderboards, campaign breakdowns, payout history, and full CSV exports.

Authentication

All endpoints require a Bearer access token with the appropriate scope. See authentication.md.

Endpoints

Common Query Parameters

All endpoints accept date range filters. When omitted, defaults to the last 30 days.

Report Stats — GET /v1/reports/stats

Returns four headline metrics with percentage trends compared to the previous period of equal length.

Example

curl "https://<API_DOMAIN>/v1/reports/stats?from=2026-03-17&to=2026-04-16" \
  -H "Authorization: Bearer <access_token>"

Success Response — HTTP 200

{
  "success": true,
  "message": "Report statistics retrieved.",
  "data": {
    "total_commission_paid": 28.00,
    "pending_payouts": 14.00,
    "conversion_rate": 3.2,
    "total_referral_clicks": 2,
    "trends": {
      "commission_paid": 14.0,
      "pending_payouts": 0.0,
      "conversion_rate": 1.1,
      "referral_clicks": -8.3
    },
    "filters": {
      "from": "2026-03-17",
      "to": "2026-04-16"
    }
  }
}

Response Fields

Trend Calculation

Trends compare the requested date range against the immediately preceding period of equal length. For example, if from=2026-03-17 and to=2026-04-16 (31 days), the previous period is 2026-02-14 to 2026-03-16.

• Commission and clicks: ((current - previous) / previous) * 100, rounded to 1 decimal place. Returns 0.0 when the previous period value is zero.
• Conversion rate: Absolute difference in percentage points (current_rate - previous_rate), rounded to 1 decimal place.

Commission Chart — GET /v1/reports/commission-chart

Returns time-series data for rendering a commission-over-time bar chart. Supports daily, weekly, or monthly granularity.

Query Parameters

Example

curl "https://<API_DOMAIN>/v1/reports/commission-chart?from=2026-04-01&to=2026-04-16&granularity=daily" \
  -H "Authorization: Bearer <access_token>"

Success Response — HTTP 200

{
  "success": true,
  "message": "Commission chart data retrieved.",
  "data": {
    "granularity": "daily",
    "labels": ["Apr 01", "Apr 02", "Apr 03", "Apr 04", "Apr 05"],
    "data": [4.50, 0.00, 12.00, 0.00, 7.00],
    "filters": {
      "from": "2026-04-01",
      "to": "2026-04-16"
    }
  }
}

Response Fields

Label Format by Granularity

Empty time buckets are filled with 0.00 to ensure the chart has no gaps.

Top Affiliates — GET /v1/reports/top-affiliates

Returns the top-performing affiliates ranked by commission earned within the date range. Only affiliates with at least one conversion or click in the period are included.

Query Parameters

Example

curl "https://<API_DOMAIN>/v1/reports/top-affiliates?from=2026-03-17&to=2026-04-16&limit=5" \
  -H "Authorization: Bearer <access_token>"

Success Response — HTTP 200

{
  "success": true,
  "message": "Top affiliates retrieved.",
  "data": {
    "items": [
      {
        "affiliate_id": 1,
        "name": "Salman",
        "referral_code": "SALMAN2026",
        "earned": 140.00,
        "clicks": 2,
        "conversions": 5
      }
    ],
    "filters": {
      "from": "2026-03-17",
      "to": "2026-04-16"
    }
  }
}

Response Fields

Clicks by Campaign — GET /v1/reports/clicks-by-campaign

Returns referral click counts grouped by the campaign tag on referral links. All active campaigns for the business are included, even those with zero clicks in the date range.

Query Parameters

Example

curl "https://<API_DOMAIN>/v1/reports/clicks-by-campaign?from=2026-03-17&to=2026-04-16" \
  -H "Authorization: Bearer <access_token>"

Success Response — HTTP 200

{
  "success": true,
  "message": "Clicks by campaign retrieved.",
  "data": {
    "items": [
      {
        "campaign": "mountain_rentals_brand",
        "clicks": 0
      },
      {
        "campaign": "women_skier_interest",
        "clicks": 0
      },
      {
        "campaign": "winter_sale",
        "clicks": 0
      },
      {
        "campaign": null,
        "clicks": 2
      }
    ],
    "filters": {
      "from": "2026-03-17",
      "to": "2026-04-16"
    }
  }
}

Response Fields

Results are ordered by clicks descending. The null campaign entry (representing links without a campaign tag) is always listed last.

Payouts — GET /v1/reports/payouts

Returns a paginated list of payout records with optional filtering by status and affiliate.

Query Parameters

Example

curl "https://<API_DOMAIN>/v1/reports/payouts?status=completed&per_page=10" \
  -H "Authorization: Bearer <access_token>"

Success Response — HTTP 200

{
  "success": true,
  "message": "Payouts retrieved.",
  "data": {
    "items": [
      {
        "id": 1,
        "affiliate_id": 1,
        "affiliate_name": "Salman",
        "amount": 28.00,
        "currency": "USD",
        "method": "bank_transfer",
        "status": "completed",
        "reference": "TXN-20260410-001",
        "paid_at": "2026-04-10T14:30:00.000000Z",
        "created_at": "2026-04-10T14:00:00.000000Z"
      }
    ],
    "meta": {
      "current_page": 1,
      "per_page": 15,
      "total": 1,
      "last_page": 1
    },
    "filters": {
      "from": "2026-03-17",
      "to": "2026-04-16"
    }
  }
}

Response Fields

Date Range Behavior

Date range filters are applied differently based on payout status:

• Completed payouts: filtered by paid_at (when the payment was made)
• Pending/failed payouts: filtered by created_at (when the payout was recorded)

This ensures completed payouts appear in the period they were paid, not when they were initially created.

Export Report — GET /v1/reports/export

Downloads a CSV file containing report data. By default exports all sections; use the sections parameter to select specific sections.

Query Parameters

Available Sections

Example

curl "https://<API_DOMAIN>/v1/reports/export?from=2026-04-01&to=2026-04-16&sections=stats,top_affiliates" \
  -H "Authorization: Bearer <access_token>" \
  -o affiliate-reports.csv

Success Response — HTTP 200

Content-Type: text/csv Content-Disposition: attachment; filename="affiliate-reports-2026-04-16.csv"

"--- Report Stats ---"
Metric,Value,Trend (%)
Total Commission Paid,28.00,14.0
Pending Payouts,14.00,0.0
Conversion Rate (%),3.2,1.1
Total Referral Clicks,2,-8.3

"--- Top Affiliates ---"
Name,Referral Code,Earned,Clicks,Conversions
Salman,SALMAN2026,140.00,2,5

"--- Clicks by Campaign ---"
Campaign,Clicks
mountain_rentals_brand,0
women_skier_interest,0
winter_sale,0
(no campaign),2

"--- Commission Over Time (daily) ---"
Date,Commission
Apr 01,4.50
Apr 02,0.00
Apr 03,12.00

"--- Payouts ---"
Affiliate,Amount,Currency,Method,Status,Reference,Paid At,Created At
Salman,28.00,USD,bank_transfer,completed,TXN-20260410-001,2026-04-10 14:30:00,2026-04-10 14:00:00

CSV Structure

• Each section is separated by a header row in the format --- Section Name ---
• Sections appear in the order: stats, top affiliates, clicks by campaign, commission chart, payouts
• When sections is specified, only the requested sections appear
• Unknown section keys in the sections parameter are silently ignored
• Payout timestamps use YYYY-MM-DD HH:MM:SS format (not ISO 8601)

Payout Status Workflow

  ┌─────────┐
  │ pending  │ ← initial state (payout recorded)
  └────┬─────┘
       │
  ┌────┴────┐
  ▼         ▼
┌───────────┐ ┌────────┐
│ completed │ │ failed │
└───────────┘ └────────┘

• **pending**: Payout has been recorded but not yet processed
• **completed**: Payment was successfully processed (paid_at is set)
• **failed**: Payment processing failed

Error Reference

Error Response Format

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": {
      "granularity": ["The selected granularity is invalid."]
    }
  }
}

Rate Limiting

Exceeding the limit returns HTTP 429 Too Many Requests.

Get Link Stats

Returns aggregate statistics for all referral links in your business.

GET /v1/links/stats

Required scope: affiliates:read Rate limit: 120 requests/minute

Example Request

curl "https://<API_DOMAIN>/v1/links/stats" \
  -H "Authorization: Bearer <access_token>"

Success Response — 200 OK

{
  "success": true,
  "message": "OK",
  "data": {
    "total": 42,
    "active": 38,
    "inactive": 4,
    "total_clicks": 1523
  }
}

Response Fields

Note: Soft-deleted links are excluded from all counts. total_clicks is derived from the denormalized click_count field on each link, which is incremented in real time by the click tracking system.

————————————————Updated April 17, 2026 ———————————————————

Get Affiliate Stats

Returns aggregate counts of affiliates grouped by status for your business.

GET /v1/affiliates/stats

Required scope: affiliates:read Rate limit: 120 requests/minute

Example Request

curl "https://<API_DOMAIN>/v1/affiliates/stats" \
  -H "Authorization: Bearer <access_token>"

Success Response — 200 OK

{
  "success": true,
  "message": "OK",
  "data": {
    "total": 120,
    "active": 85,
    "pending": 20,
    "suspended": 10,
    "terminated": 5
  }
}

Response Fields

Note: Soft-deleted affiliates are excluded from all counts. total equals the sum of all four status counts.

Export Affiliates

Downloads affiliates as a CSV file. Supports the same filters as List Affiliates but without pagination — returns all matching records. An additional ids parameter allows exporting a specific selection of affiliates (e.g., from checkbox selection in the UI).

GET /v1/affiliates/export

Required scope: affiliates:read Rate limit: 30 requests/minute

Query Parameters

Filter precedence: When ids is provided, the endpoint returns exactly those affiliates (scoped to your business) regardless of any status or search parameters. Sorting still applies.

Example — Export all affiliates

curl "https://<API_DOMAIN>/v1/affiliates/export" \
  -H "Authorization: Bearer <access_token>" \
  -o affiliates.csv

Example — Export only active affiliates

curl "https://<API_DOMAIN>/v1/affiliates/export?status=active&sort=referral_code&direction=asc" \
  -H "Authorization: Bearer <access_token>" \
  -o active-affiliates.csv

Example — Export selected affiliates by ID

curl "https://<API_DOMAIN>/v1/affiliates/export?ids=42,55,78" \
  -H "Authorization: Bearer <access_token>" \
  -o selected-affiliates.csv

Success Response — HTTP 200

Content-Type: text/csv Content-Disposition: attachment; filename="affiliates-export-2026-04-17.csv"

ID,Name,Email,Phone,Referral Code,Commission Rate,Status,Joined,Approved At,Suspended At,Terminated At,Notes
42,"Jane Doe",jane@example.com,+14155552671,ABC12345,10.00,active,"2026-03-15 14:22:00","2026-04-01 09:00:00",,,"VIP partner"
55,"John Smith",john@example.com,,XK9P2QR7,,pending,"2026-04-13 11:30:00",,,,

CSV Columns

Error Responses

Get Affiliate Stats (Individual)

Returns performance statistics for a single affiliate: total earned commission, pending payouts, total orders, and referral clicks.

GET /v1/affiliates/{id}/stats

Required scope: affiliates:read Rate limit: 120 requests/minute

Path Parameters

Query Parameters

Example Request — All-time stats

curl "https://<API_DOMAIN>/v1/affiliates/42/stats" \
  -H "Authorization: Bearer <access_token>"

Example Request — Date-filtered stats

curl "https://<API_DOMAIN>/v1/affiliates/42/stats?date_from=2026-04-01&date_to=2026-04-30" \
  -H "Authorization: Bearer <access_token>"

Success Response — 200 OK

{
  "success": true,
  "message": "OK",
  "data": {
    "total_earned": 175.00,
    "pending_payout": 35.00,
    "total_orders": 12,
    "referral_clicks": 483
  }
}

Response Fields

Note: When no date range is specified, all-time totals are returned. total_earned includes commissions in all statuses (pending, approved, rejected, cancelled). pending_payout only includes commissions awaiting approval.

Error Responses

Bulk Referral Link Creation — All Affiliates

Create referral links across every affiliate of a business in a single API call. Each affiliate receives the full set of provided link templates. Processing is asynchronous via a fan-out worker pattern that distributes work into per-affiliate child jobs.

Overview

This endpoint is intended for partner platforms and business operators that need to roll out a set of destination URLs (and optional per-affiliate coupons) to their entire affiliate roster — for example, when launching a new product, refreshing campaigns, or onboarding affiliates to an existing catalog.

Key characteristics

For single-affiliate bulk creation, use [POST /v1/affiliates/{affiliateId}/links?bulk_create=true](/docs/api/partner-bulk-referral-links). This endpoint is a separate, additive flow and does not replace it.

Workflow

Client                    API                          Queue
  │                        │                             │
  │  POST /links/bulk-all-affiliates                     │
  │ ───────────────────────►                             │
  │                        │                             │
  │                        │  Create ReferralLinkBatch   │
  │                        │  (scope=all_affiliates)     │
  │                        │                             │
  │                        │  Dispatch fan-out job ─────►│
  │                        │                             │
  │ ◄─────────────────────  202 + batch_id              │
  │                                                      │
  │                                                      │  Fan-out:
  │                                                      │  chunkById(50)
  │                                                      │  dispatch N
  │                                                      │  child jobs
  │                                                      │
  │                                                      │  Child job per
  │                                                      │  affiliate:
  │                                                      │  - expand
  │                                                      │    templates
  │                                                      │  - resolve
  │                                                      │    coupons
  │                                                      │  - create links
  │                                                      │  - increment
  │                                                      │    counters
  │                                                      │
  │  GET /link-batches/{id} (poll)                       │
  │ ───────────────────────►                             │
  │ ◄─────────────────────  status + counts             │

Prerequisites

Endpoint

POST /v1/links/bulk-all-affiliates

Headers

Authorization: Bearer <access_token>
Content-Type: application/json

Request body

{
  "affiliate_filter": {
    "status": "active",
    "search": "vip"
  },
  "links": [
    {
      "destination_url": "https://example.com/products/widget",
      "campaign": "spring-2026",
      "is_active": true,
      "metadata": { "category": "widgets", "priority": 1 },
      "coupon_code_prefix": "SPRING",
      "coupon_type": "percentage",
      "coupon_value": 15.00,
      "coupon_min_order": 50.00,
      "coupon_max_uses": 100,
      "coupon_expires_at": "2026-06-30T23:59:59Z"
    },
    {
      "destination_url": "https://example.com/products/gadget",
      "campaign": "spring-2026"
    }
  ]
}

Field reference

Rejected fields

These are explicitly rejected by validation — supplying them returns 422:

Coupon Templates

When coupon_code_prefix is supplied, a unique coupon code is materialized per affiliate at processing time:

final_code = "{coupon_code_prefix}-{AFFILIATE_REFERRAL_CODE}"

For example, prefix SPRING with three affiliates whose referral_codes are ABC123, DEF456, GHI789 yields three coupons: SPRING-ABC123, SPRING-DEF456, SPRING-GHI789. Each coupon is owned by its respective affiliate.

Coupons are created via firstOrCreate keyed on (business_id, code) — running the same prefix twice is idempotent and does not produce duplicates.

Response

Success — 202 Accepted

{
  "success": true,
  "message": "Bulk creation queued for all affiliates.",
  "data": {
    "batch_id": 1284,
    "scope": "all_affiliates",
    "status": "pending",
    "total_affiliates": 312,
    "total_items": 624,
    "status_url": "/v1/link-batches/1284"
  }
}

Validation error — 422 Unprocessable Entity

Returned for any validation failure (rule violation, exceeded limit, no matching affiliates).

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The given data was invalid.",
    "details": {
      "links.0.coupon_code": [
        "Use coupon_code_prefix instead. coupon_code is unique per business and cannot be shared across affiliates."
      ]
    }
  }
}

Other 422 codes:

Server error — 500 Internal Server Error

{
  "success": false,
  "error": {
    "code": "SERVER_ERROR",
    "message": "Failed to queue bulk link creation."
  }
}

Polling for Status

GET /v1/link-batches/{batchId}

Headers

Authorization: Bearer <access_token>

Scope: affiliates:read.

Response — 200 OK

While processing:

{
  "success": true,
  "data": {
    "batch_id": 1284,
    "scope": "all_affiliates",
    "status": "processing",
    "total_items": 624,
    "created_count": 412,
    "error_count": 0,
    "total_affiliates": 312,
    "processed_affiliates": 206,
    "created_at": "2026-05-15T10:42:18Z",
    "completed_at": null
  }
}

On completion:

{
  "success": true,
  "data": {
    "batch_id": 1284,
    "scope": "all_affiliates",
    "status": "completed",
    "total_items": 624,
    "created_count": 622,
    "error_count": 2,
    "total_affiliates": 312,
    "processed_affiliates": 312,
    "created_at": "2026-05-15T10:42:18Z",
    "completed_at": "2026-05-15T10:44:31Z",
    "results": [
      {
        "affiliate_id": 42,
        "created": [9011, 9012],
        "errors": []
      },
      {
        "affiliate_id": 43,
        "created": [9013],
        "errors": [
          {
            "index": 1,
            "destination_url": "https://example.com/products/gadget",
            "message": "The slug \"abc12345\" is already taken."
          }
        ]
      }
    ],
    "errors": null
  }
}

Status values

Polling guidelines

• Poll no more than once every 2–5 seconds. The endpoint is rate-limited at 120 req/min within the affiliates:read group.
• Use processed_affiliates / total_affiliates as a progress ratio.
• A non-zero error_count does not imply batch failure — individual link errors are captured per affiliate without aborting the batch.

Not found — 404 Not Found

Returned if the batch ID does not exist or belongs to a different tenant.

{
  "success": false,
  "error": { "code": "NOT_FOUND", "message": "Batch not found." }
}

Worked Example

1. Submit batch

curl -X POST "https://api.heldsway.com/v1/links/bulk-all-affiliates" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "affiliate_filter": { "status": "active" },
    "links": [
      {
        "destination_url": "https://example.com/products/widget",
        "campaign": "spring-2026",
        "coupon_code_prefix": "SPRING",
        "coupon_type": "percentage",
        "coupon_value": 15.00
      },
      {
        "destination_url": "https://example.com/products/gadget",
        "campaign": "spring-2026"
      }
    ]
  }'

2. Response

{
  "success": true,
  "message": "Bulk creation queued for all affiliates.",
  "data": {
    "batch_id": 1284,
    "scope": "all_affiliates",
    "status": "pending",
    "total_affiliates": 312,
    "total_items": 624,
    "status_url": "/v1/link-batches/1284"
  }
}

3. Poll until complete

while true; do
  STATUS=$(curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
    "https://api.heldsway.com/v1/link-batches/1284" \
    | jq -r '.data.status')

  echo "Status: $STATUS"
  [[ "$STATUS" == "completed" || "$STATUS" == "failed" ]] && break
  sleep 3
done

4. Inspect per-affiliate results

curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://api.heldsway.com/v1/link-batches/1284" \
  | jq '.data.results[] | select(.errors | length > 0)'

Behavior Notes

Idempotency

• Coupon resolution is idempotent: re-submitting the same coupon_code_prefix will reuse the existing per-affiliate DiscountCode rather than creating duplicates.
• Link creation is not idempotent. Each submission produces a fresh set of referral links with newly generated slugs. Submitting the same payload twice doubles the number of links.

Tenant isolation

• The endpoint always operates on the affiliates of the access token’s tenant.
• Cross-tenant affiliate access is impossible: filters and queries are bound to business_id.

Partial success

• A child job that fails to create one or more links does not abort the batch. Failures are captured in the per-affiliate errors[] array with index, destination_url, and message.
• A child job that fails entirely (e.g. a database connection error) is recorded under that affiliate’s errors array as a single { "message": "Job failed: ..." } entry. The batch still progresses.

Concurrency

• Child jobs run in parallel across queue workers.
• Counter updates (created_count, error_count, processed_affiliates) use atomic SQL increments to remain consistent under parallel execution.
• The first child to observe processed_affiliates >= total_affiliates transitions the batch to completed.

Limits

Comparison: Single-Affiliate vs All-Affiliates

The unified GET /v1/link-batches/{batchId} endpoint works for batches of both scopes.

Error Reference

Changelog