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 "api.heldsway.com/api//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 "api.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

curl -X PUT "api.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

{
  "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 "api.heldsway.com/api//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 "api.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

curl -X POST "api.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

{
  "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 "api.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

curl -X PATCH "api.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

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 "api.heldsway.com/api//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