Heldsway

Appearance

Affiliate Management API ​

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

Prerequisites ​

Your API key must be granted the appropriate scopes:

ScopeGrants Access To
affiliates:readList and retrieve affiliates, links, commission data
affiliates:writeCreate, update, delete affiliates and links; manage commission
text
Authorization: Bearer <access_token>

Table of Contents ​

Affiliates

Referral Links

Commission Configuration

Business Settings

Data Models ​

Affiliate Object ​

json
{
  "id": 42,
  "referral_code": "ABC12345",
  "status": "active",
  "commission_rate": "10.00",
  "notes": "VIP partner",
  "approved_at": "2026-04-01T09:00: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"
  }
}
FieldTypeDescription
idintegerUnique affiliate ID
referral_codestringUnique tracking code used in referral links
statusstringpending | active | suspended | terminated
commission_ratestring|nullAffiliate-specific commission rate (%). null = inherits business default
notesstring|nullInternal notes visible only to business owner
approved_atISO 8601|nullWhen the affiliate was approved
suspended_atISO 8601|nullWhen the affiliate was suspended
terminated_atISO 8601|nullWhen the affiliate was terminated
created_atISO 8601Record creation timestamp
affiliate_user.idintegerThe affiliated user's account ID
affiliate_user.namestringFull name
affiliate_user.emailstringEmail address
affiliate_user.phonestring|nullPhone number

Affiliate Status Transitions ​

text
pending ──► active ──► suspended ──► active
   │                       │
   ▼                       ▼
 active               terminated
   │
   ▼
terminated
Current StatusValid Actions
pendingapprove, suspend, terminate
activesuspend, terminate
suspendedreactivate, terminate
terminated(no further transitions)
json
{
  "id": 10,
  "affiliate_id": 42,
  "slug": "summer2026",
  "destination_url": "https://example.com/landing",
  "campaign": "Summer Campaign",
  "is_active": true,
  "click_count": 142,
  "tracking_url": "https://yourbusiness.heldsway.com/r/summer2026",
  "metadata": { "source": "email" },
  "created_at": "2026-04-01T09:00:00.000000Z"
}
FieldTypeDescription
idintegerUnique link ID
affiliate_idintegerID of the owning affiliate
slugstringURL-safe identifier used in the tracking URL
destination_urlstringWhere the visitor is sent after click tracking
campaignstring|nullOptional campaign label for grouping
is_activebooleanWhether this link is currently accepting clicks
click_countintegerTotal recorded clicks
tracking_urlstringThe full public URL affiliates share (/r/{slug})
metadataobject|nullArbitrary key-value pairs for your own use
created_atISO 8601Record creation timestamp

Commission Rule Object ​

json
{
  "id": 5,
  "label": "Black Friday Deal",
  "commission_rate": 20.00,
  "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"
}
FieldTypeDescription
idintegerUnique rule ID
labelstring|nullHuman-readable name for the rule
commission_ratefloatCommission percentage (0–100)
priorityintegerHigher value = higher precedence. When multiple rules apply, the one with the highest priority wins
valid_fromISO 8601|nullRule becomes active at this time. null = no start restriction
valid_untilISO 8601|nullRule expires at this time. null = no expiry
max_conversionsinteger|nullMaximum conversions this rule applies to. null = unlimited
conversion_countintegerHow many conversions have used this rule (read-only)
is_activebooleanWhether the rule is enabled
statusstringComputed status: active | scheduled | expired | exhausted | disabled
created_atISO 8601Record creation timestamp

Batch Object ​

Returned by the Get Batch Status endpoint after a Bulk Create request.

json
{
  "batch_id": 17,
  "status": "completed",
  "total_items": 3,
  "created_count": 2,
  "error_count": 1,
  "created_at": "2026-04-14T10:00:00.000000Z",
  "completed_at": "2026-04-14T10:00:05.000000Z",
  "created_link_ids": [101, 102],
  "created_links": [ ... ],
  "errors": [ ... ]
}
FieldTypeDescription
batch_idintegerUnique batch ID
statusstringpending | processing | completed | failed
total_itemsintegerNumber of items submitted in the request
created_countintegerNumber of links successfully created
error_countintegerNumber of items that failed
created_atISO 8601When the batch was submitted
completed_atISO 8601|nullWhen processing finished. null while pending/processing
created_link_idsarray<integer>IDs of created links. Present only when completed or failed
created_linksarray<Referral Link>Full link objects with tracking_url. Present only when completed or failed and links exist
errorsarrayPer-item errors. Each has index (0-based), destination_url, and message. Present only when completed or failed

Commission Resolution Order ​

When a conversion occurs, the system determines the commission rate using this priority chain (highest to lowest):

  1. Active per-link commission rule (highest priority rule wins)
  2. Affiliate-level commission rate override
  3. Business default commission rate
  4. Platform base rate (fallback)

Quick Reference ​

Affiliate Endpoints ​

MethodPathScopeDescription
GET/v1/affiliatesaffiliates:readList affiliates
GET/v1/affiliates/{id}affiliates:readGet affiliate
POST/v1/affiliatesaffiliates:writeCreate affiliate (active)
POST/v1/affiliates/registeraffiliates:writeAffiliate self-registration (pending)
PATCH/v1/affiliates/{id}affiliates:writeUpdate affiliate
DELETE/v1/affiliates/{id}affiliates:writeDelete affiliate
POST/v1/affiliates/{id}/approveaffiliates:writeApprove pending affiliate
POST/v1/affiliates/{id}/suspendaffiliates:writeSuspend affiliate
POST/v1/affiliates/{id}/reactivateaffiliates:writeReactivate suspended affiliate
POST/v1/affiliates/{id}/terminateaffiliates:writeTerminate affiliate (permanent)
MethodPathScopeDescription
GET/v1/linksaffiliates:readList all links
GET/v1/affiliates/{id}/linksaffiliates:readList links for one affiliate
POST/v1/affiliates/{id}/linksaffiliates:writeCreate referral link
POST/v1/affiliates/{id}/links?bulk_create=trueaffiliates:writeBulk create referral links (async)
GET/v1/affiliates/{id}/link-batches/{batchId}affiliates:readPoll batch status
PATCH/v1/links/{id}affiliates:writeUpdate referral link
DELETE/v1/links/{id}affiliates:writeDelete referral link

Commission Endpoints ​

MethodPathScopeDescription
GET/v1/affiliates/{id}/commissionaffiliates:readGet affiliate commission config
PUT/v1/affiliates/{id}/commissionaffiliates:writeSet/clear affiliate commission override
GET/v1/links/{id}/commission-rulesaffiliates:readList commission rules for link
POST/v1/links/{id}/commission-rulesaffiliates:writeCreate commission rule
PATCH/v1/links/{linkId}/commission-rules/{ruleId}affiliates:writeUpdate commission rule
DELETE/v1/links/{linkId}/commission-rules/{ruleId}affiliates:writeDelete commission rule

Released under the MIT License.

Copyright © 2026 Heldsway