Heldsway

Appearance

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 ​

ParameterTypeDescription
idintegerAffiliate ID

Example Request ​

bash
curl "https://heldsway.com/api/v1/affiliates/42/commission" \
  -H "Authorization: Bearer <access_token>"

Success Response — 200 OK ​

json
{
  "success": true,
  "message": "OK",
  "data": {
    "affiliate_rate": 10.0,
    "business_default_rate": 8.0,
    "effective_rate": 10.0
  }
}
FieldTypeDescription
affiliate_ratefloat|nullThis affiliate's individual override rate. null if none is set
business_default_ratefloat|nullThe business-wide default commission rate
effective_ratefloat|nullThe rate that will actually be used (affiliate_rate if set, otherwise business_default_rate)

Error Responses ​

StatusCodeDescription
404NOT_FOUNDAffiliate not found

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 ​

ParameterTypeDescription
idintegerAffiliate ID

Request Body ​

FieldTypeRequiredDescription
commission_ratefloat|nullYesCommission percentage (0–100). Send null to remove the override and revert to the business default

Example Request — Set override ​

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

Example Request — Clear override ​

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

Success Response — 200 OK ​

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

Error Responses ​

StatusCodeDescription
404NOT_FOUNDAffiliate not found
422VALIDATION_ERRORcommission_rate missing from request body or out of range

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 ​

ParameterTypeDescription
idintegerReferral link ID

Example Request ​

bash
curl "https://heldsway.com/api/v1/links/10/commission-rules" \
  -H "Authorization: Bearer <access_token>"

Success Response — 200 OK ​

json
{
  "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 ​

StatusCodeDescription
404NOT_FOUNDReferral link not found

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 ​

ParameterTypeDescription
idintegerReferral link ID

Request Body ​

FieldTypeRequiredConstraintsDescription
commission_ratefloatYes0–100Commission percentage this rule applies
labelstringNomax 255Human-readable name (e.g. "Black Friday")
priorityintegerNomin 0, default 0Higher value = takes precedence over lower-priority rules
valid_fromdate/datetimeNo—Rule activates at this time. Omit for no start restriction
valid_untildate/datetimeNomust be ≥ valid_fromRule expires at this time. Omit for no expiry
max_conversionsintegerNomin 1Cap on how many conversions this rule applies to. Omit for unlimited
is_activebooleanNodefault trueWhether the rule is enabled immediately

Example Request — Timed promotional rule ​

bash
curl -X POST "https://heldsway.com/api/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 ​

bash
curl -X POST "https://heldsway.com/api/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 ​

json
{
  "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 ​

StatusCodeDescription
404NOT_FOUNDReferral link not found
422VALIDATION_ERRORInvalid fields

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 ​

ParameterTypeDescription
linkIdintegerReferral link ID
ruleIdintegerCommission rule ID

Request Body ​

All fields optional.

FieldTypeConstraintsDescription
commission_ratefloat0–100Updated commission percentage
labelstring|nullmax 255Updated label. Send null to clear
priorityintegermin 0Updated priority
valid_fromdate|null—Updated start date. Send null to remove
valid_untildate|null≥ valid_from if both presentUpdated expiry. Send null to remove
max_conversionsinteger|nullmin 1Updated cap. Send null to remove cap
is_activeboolean—Enable or disable the rule

Example Request — Disable a rule ​

bash
curl -X PATCH "https://heldsway.com/api/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 ​

bash
curl -X PATCH "https://heldsway.com/api/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 ​

StatusCodeDescription
404NOT_FOUNDLink or rule not found for this business
422VALIDATION_ERRORInvalid field values

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 ​

ParameterTypeDescription
linkIdintegerReferral link ID
ruleIdintegerCommission rule ID

Example Request ​

bash
curl -X DELETE "https://heldsway.com/api/v1/links/10/commission-rules/8" \
  -H "Authorization: Bearer <access_token>"

Success Response — 204 No Content ​

Empty body.

Error Responses ​

StatusCodeDescription
404NOT_FOUNDLink or rule not found for this business

Rate Limits ​

Endpoint GroupLimit
GET read endpoints120 requests/minute
POST, PATCH, PUT, DELETE write endpoints60 requests/minute
POST /v1/affiliates/register30 requests/minute

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

text
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:

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

details is only present on VALIDATION_ERROR responses.

Error Codes ​

HTTP StatusCodeDescription
400BAD_REQUESTGeneric bad request
401UNAUTHORIZEDMissing, invalid, or expired Bearer token
403FORBIDDENValid token but insufficient scope, or feature disabled
403REGISTRATION_DISABLEDSelf-registration is turned off for this business
404NOT_FOUNDResource does not exist or does not belong to this business
409AFFILIATE_EXISTSDuplicate affiliate — email already registered for this business
409INVALID_STATUSStatus transition is not valid from the current state
422VALIDATION_ERRORRequest body failed validation
429TOO_MANY_REQUESTSRate limit exceeded
500SERVER_ERRORInternal server error

Validation Error Example ​

json
{
  "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 ​

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