Affiliate Management Overview

HeldSway provides programmatic management of affiliates, custom referral links, tiered commissions, and partner lifecycles.

Authentication & Scopes

All affiliate management endpoints require a Bearer access token obtained via the Token Issuance endpoint.

Scope	Grants Access To
`affiliates:read`	List and retrieve affiliates, links, stats, and commission overrides
`affiliates:write`	Create, update, delete, approve, suspend, and reactivate affiliates; create links
`settings:read`	Retrieve business program settings, branding, and commission tiers
`settings:write`	Update business settings, branding, and commission tiers

Documentation Sections

Affiliates API: Full CRUD endpoints, application approval, suspension, reactivation, termination, and CSV export.
Referral Links API: Single link creation, bulk generation across all affiliates, coupon attachment, QR code generation, and click stats.
Commission Configuration API: Tiered commission structures, per-link rules, and individual affiliate overrides.
Business Settings API: Program settings, catalog paths, branding, and payout scheduling.

Affiliate Lifecycle & Status Transitions

Affiliates transition between distinct statuses through their lifecycle:

stateDiagram-v2
    [*] --> pending: Self-registration / Created
    pending --> active: Approved by Business
    pending --> terminated: Rejected / Terminated
    active --> suspended: Suspended by Business
    suspended --> active: Reactivated
    active --> terminated: Terminated
    suspended --> terminated: Terminated
    terminated --> [*]

Current Status	Allowed Actions	Description
`pending`	`approve`, `suspend`, `terminate`	The application has been submitted and is awaiting business owner approval
`active`	`suspend`, `terminate`	The affiliate is in good standing; clicks and conversions are tracked and credited
`suspended`	`reactivate`, `terminate`	The affiliate is temporarily blocked from tracking or earning commissions
`terminated`	(none)	The affiliate relationship is permanently ended

Core Data Models

Affiliate Object

{
  "id": 42,
  "referral_code": "ABC12345",
  "status": "active",
  "commission_rate": "10.00",
  "notes": "Top tech blogger partner",
  "approved_at": "2026-03-15T14:22:00.000000Z",
  "suspended_at": null,
  "terminated_at": null,
  "created_at": "2026-03-15T14:22:00.000000Z",
  "affiliate_user": {
    "id": 7,
    "name": "Jane Doe",
    "email": "jane@example.com",
    "phone": "+14155552671"
  },
  "referral_link": {
    "id": 10,
    "slug": "jane-smith",
    "destination_url": "https://example.com/store",
    "tracking_url": "https://yourbusiness.heldsway.com/r/jane-smith",
    "qr_code_url": "https://yourbusiness.heldsway.com/r/jane-smith/qr",
    "qr_code_svg_url": "https://yourbusiness.heldsway.com/r/jane-smith/qr?format=svg"
  },
  "total_earned": 1250.00,
  "pending_payout": 150.00
}

Field	Type	Description
`id`	integer	Unique internal affiliate ID
`referral_code`	string	Unique tracking code used in referral links
`status`	string	`pending` \| `active` \| `suspended` \| `terminated`
`commission_rate`	string\|null	Affiliate-specific commission override percentage (`null` = inherits default)
`notes`	string\|null	Internal notes visible only to the business
`approved_at`	ISO 8601\|null	Timestamp when approved
`suspended_at`	ISO 8601\|null	Timestamp when suspended
`terminated_at`	ISO 8601\|null	Timestamp when terminated
`created_at`	ISO 8601	Application submission timestamp
`affiliate_user`	object	User profile containing `id`, `name`, `email`, and `phone`
`referral_link`	object\|null	Default referral link with tracking and QR code URLs
`total_earned`	float\|null	Cumulative approved commissions across all orders
`pending_payout`	float\|null	Commissions currently approved and awaiting payout

Referral Link Object

{
  "id": 10,
  "affiliate_id": 42,
  "affiliate_user": {
    "name": "Jane Smith",
    "email": "jane@example.com"
  },
  "slug": "summer2026",
  "destination_url": "https://example.com/store/cameras",
  "campaign": "Summer Campaign",
  "discount_code": {
    "id": 57,
    "code": "JANE15",
    "type": "percentage",
    "value": 15,
    "min_order": 0,
    "max_uses": 100,
    "expires_at": null
  },
  "is_active": true,
  "click_count": 142,
  "conversion_count": 9,
  "tracking_url": "https://yourbusiness.heldsway.com/r/summer2026",
  "qr_code_url": "https://yourbusiness.heldsway.com/r/summer2026/qr",
  "qr_code_svg_url": "https://yourbusiness.heldsway.com/r/summer2026/qr?format=svg",
  "type": "product",
  "metadata": {
    "source": "newsletter"
  },
  "location_id": "loc_01",
  "location_name": "Downtown Store",
  "product_id": "prod_cam_4k",
  "product_name": "4K Cinema Camera",
  "created_at": "2026-04-01T09:00:00.000000Z"
}

Commission Resolution Hierarchy

When a customer makes a purchase through a referral link, the commission rate is computed using this strict priority order (highest to lowest):

flowchart TD
    A[Order Conversion Recorded] --> B{Active Per-Link Rule?}
    B -- Yes --> C[Apply Link Rule Rate]
    B -- No --> D{Affiliate Custom Override?}
    D -- Yes --> E[Apply Affiliate Override Rate]
    D -- No --> F{Matching Commission Tier?}
    F -- Yes --> G[Apply Tier Rate]
    F -- No --> H[Apply Business Default Rate]

Per-Link Commission Rule: Highest priority rule defined for the specific referral link.
Affiliate-Level Override: Custom commission rate assigned to the individual affiliate.
Commission Tier: Tier matching the affiliate’s trailing 30-day conversion volume or revenue.
Business Default Rate: Fallback program default rate set in Business Settings.

← Authentication Affiliates →