Affiliates

List Affiliates

Retrieve a paginated list of all affiliates for your business.

GET /v1/affiliates

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

Query Parameters

Parameter	Type	Default	Description
`page`	integer	`1`	Page number
`per_page`	integer	`25`	Results per page. Max `100`
`status`	string	—	Filter by status: `pending` \| `active` \| `suspended` \| `terminated`
`search`	string	—	Search across name, email, and referral code
`sort`	string	`created_at`	Sort field: `created_at` \| `referral_code` \| `status` \| `commission_rate`
`direction`	string	`desc`	Sort direction: `asc` \| `desc`

Example Request

bash

curl "https://heldsway.com/api/v1/affiliates?status=active&per_page=10&sort=created_at&direction=desc" \
  -H "Authorization: Bearer <access_token>"

Success Response — 200 OK

json

{
  "success": true,
  "message": "OK",
  "data": {
    "items": [
      {
        "id": 42,
        "referral_code": "ABC12345",
        "status": "active",
        "commission_rate": "10.00",
        "notes": null,
        "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": null
        }
      }
    ],
    "meta": {
      "current_page": 1,
      "per_page": 10,
      "total": 87,
      "last_page": 9
    }
  }
}

Get Affiliate

Retrieve a single affiliate by ID.

GET /v1/affiliates/{id}

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

Path Parameters

Parameter	Type	Description
`id`	integer	Affiliate ID

Example Request

bash

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

Success Response — 200 OK

json

{
  "success": true,
  "message": "OK",
  "data": {
    "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"
    },
    "referral_links_count": 3
  }
}

Error Responses

Status	Code	Description
`404`	`NOT_FOUND`	Affiliate does not exist for this business

Create Affiliate

Create a new affiliate account directly. The affiliate is immediately set to active status — no approval step required. Use this when you are adding affiliates on their behalf.

If the email already exists as an affiliate user account (across any business), they will be linked to your business without changing their password. If no account exists, one is created with the provided credentials.

POST /v1/affiliates

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

Request Body

Field	Type	Required	Constraints	Description
`name`	string	Yes	max 255	Affiliate's full name
`email`	string	Yes	valid email, max 255	Affiliate's email address
`password`	string	Yes	min 8, max 255	Account password
`phone`	string	No	max 30	Phone number
`commission_rate`	float	No	0–100	Override commission rate (%). Omit to use business default
`notes`	string	No	max 1000	Internal notes
`referral_code`	string	No	alphanumeric, max 32, unique	Custom referral code. Auto-generated if omitted

Example Request

bash

curl -X POST "https://heldsway.com/api/v1/affiliates" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Doe",
    "email": "jane@example.com",
    "password": "SecurePass123!",
    "phone": "+14155552671",
    "commission_rate": 12.5,
    "notes": "Referred by our sales team",
    "referral_code": "JANE2026"
  }'

Success Response — 201 Created

json

{
  "success": true,
  "message": "Created",
  "data": {
    "id": 42,
    "referral_code": "JANE2026",
    "status": "active",
    "commission_rate": "12.50",
    "notes": "Referred by our sales team",
    "approved_at": "2026-04-13T10:00:00.000000Z",
    "suspended_at": null,
    "terminated_at": null,
    "created_at": "2026-04-13T10:00:00.000000Z",
    "affiliate_user": {
      "id": 7,
      "name": "Jane Doe",
      "email": "jane@example.com",
      "phone": "+14155552671"
    }
  }
}

Error Responses

Status	Code	Description
`409`	`AFFILIATE_EXISTS`	This email is already an affiliate of your business
`422`	`VALIDATION_ERROR`	Missing or invalid fields

Affiliate Self-Registration

Allow an individual to register themselves as an affiliate for your business. This endpoint is intended for use in your own frontend — your backend calls our API with your access token, passing the user's details.

Prerequisite: The business setting allow_self_registration must be enabled. If it is off, this endpoint returns 403. This setting is configured in your business dashboard under Affiliate Program → Settings.

Affiliates created via this endpoint start with pending status and must be approved by you before they can earn commissions.

POST /v1/affiliates/register

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

Request Body

Field	Type	Required	Constraints	Description
`name`	string	Yes	max 255	Applicant's full name
`email`	string	Yes	valid email, max 255	Applicant's email
`password`	string	Yes	min 8, max 255	Account password they will use to log in
`phone`	string	No	max 30	Phone number

Example Request

bash

curl -X POST "https://heldsway.com/api/v1/affiliates/register" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Smith",
    "email": "john@example.com",
    "password": "MyPassword123!"
  }'

Success Response — 201 Created

json

{
  "success": true,
  "message": "Registration submitted. Pending approval.",
  "data": {
    "id": 55,
    "referral_code": "XK9P2QR7",
    "status": "pending",
    "commission_rate": null,
    "notes": null,
    "approved_at": null,
    "suspended_at": null,
    "terminated_at": null,
    "created_at": "2026-04-13T11:30:00.000000Z",
    "affiliate_user": {
      "id": 12,
      "name": "John Smith",
      "email": "john@example.com",
      "phone": null
    }
  }
}

Error Responses

Status	Code	Description
`403`	`REGISTRATION_DISABLED`	`allow_self_registration` is not enabled for this business
`409`	`AFFILIATE_EXISTS`	This email is already an affiliate of your business
`422`	`VALIDATION_ERROR`	Missing or invalid fields

Update Affiliate

Update editable fields on an existing affiliate. Only include fields you want to change — all fields are optional.

PATCH /v1/affiliates/{id}

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

Path Parameters

Parameter	Type	Description
`id`	integer	Affiliate ID

Request Body

Field	Type	Required	Constraints	Description
`commission_rate`	float\|null	No	0–100	Override rate. Send `null` to revert to business default
`notes`	string\|null	No	max 1000	Internal notes

Example Request

bash

curl -X PATCH "https://heldsway.com/api/v1/affiliates/42" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "commission_rate": 15.0,
    "notes": "Upgraded to premium tier"
  }'

Success Response — 200 OK

Returns the updated Affiliate Object.

Error Responses

Status	Code	Description
`404`	`NOT_FOUND`	Affiliate does not exist for this business
`422`	`VALIDATION_ERROR`	Invalid field values

Delete Affiliate

Soft-delete an affiliate from your business. This removes the affiliate record but does not delete their user account — they may still be an affiliate for other businesses. Historical conversion and click data is preserved.

DELETE /v1/affiliates/{id}

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

Path Parameters

Parameter	Type	Description
`id`	integer	Affiliate ID

Example Request

bash

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

Success Response — 204 No Content

Empty body.

Error Responses

Status	Code	Description
`404`	`NOT_FOUND`	Affiliate does not exist for this business

Approve Affiliate

Approve a pending affiliate, moving them to active status and allowing them to start earning commissions.

POST /v1/affiliates/{id}/approve

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

Path Parameters

Parameter	Type	Description
`id`	integer	Affiliate ID

Example Request

bash

curl -X POST "https://heldsway.com/api/v1/affiliates/55/approve" \
  -H "Authorization: Bearer <access_token>"

Success Response — 200 OK

json

{
  "success": true,
  "message": "Affiliate approved.",
  "data": {
    "id": 55,
    "status": "active",
    "approved_at": "2026-04-13T12:00:00.000000Z"
  }
}

Error Responses

Status	Code	Description
`404`	`NOT_FOUND`	Affiliate not found
`409`	`INVALID_STATUS`	Affiliate is not in `pending` status

Suspend Affiliate

Suspend an active or pending affiliate. Suspended affiliates cannot earn new commissions. Existing approved commissions are not affected.

POST /v1/affiliates/{id}/suspend

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

Path Parameters

Parameter	Type	Description
`id`	integer	Affiliate ID

Request Body

Field	Type	Required	Description
`reason`	string	No	Internal reason for suspension (max 500 chars). Appended to notes.

Example Request

bash

curl -X POST "https://heldsway.com/api/v1/affiliates/42/suspend" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Suspected fraudulent activity under review." }'

Success Response — 200 OK

json

{
  "success": true,
  "message": "Affiliate suspended.",
  "data": {
    "id": 42,
    "status": "suspended",
    "suspended_at": "2026-04-13T12:30:00.000000Z"
  }
}

Error Responses

Status	Code	Description
`404`	`NOT_FOUND`	Affiliate not found
`409`	`INVALID_STATUS`	Affiliate is already `suspended` or `terminated`

Reactivate Affiliate

Reactivate a suspended affiliate, restoring them to active status.

POST /v1/affiliates/{id}/reactivate

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

Path Parameters

Parameter	Type	Description
`id`	integer	Affiliate ID

Example Request

bash

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

Success Response — 200 OK

json

{
  "success": true,
  "message": "Affiliate reactivated.",
  "data": {
    "id": 42,
    "status": "active",
    "suspended_at": null
  }
}

Error Responses

Status	Code	Description
`404`	`NOT_FOUND`	Affiliate not found
`409`	`INVALID_STATUS`	Affiliate is not `suspended`

Terminate Affiliate

Permanently terminate an affiliate. This is irreversible — terminated affiliates cannot be reactivated. Use suspend if you may want to reinstate them later.

POST /v1/affiliates/{id}/terminate

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

Path Parameters

Parameter	Type	Description
`id`	integer	Affiliate ID

Request Body

Field	Type	Required	Description
`reason`	string	No	Reason for termination (max 500 chars). Appended to notes.

Example Request

bash

curl -X POST "https://heldsway.com/api/v1/affiliates/42/terminate" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Violated affiliate terms of service." }'

Success Response — 200 OK

json

{
  "success": true,
  "message": "Affiliate terminated.",
  "data": {
    "id": 42,
    "status": "terminated",
    "terminated_at": "2026-04-13T13:00:00.000000Z"
  }
}

Error Responses

Status	Code	Description
`404`	`NOT_FOUND`	Affiliate not found
`409`	`INVALID_STATUS`	Affiliate is already `terminated`

Affiliates ​

List Affiliates ​

Query Parameters ​

Example Request ​

Success Response — 200 OK ​

Get Affiliate ​

Path Parameters ​

Example Request ​

Success Response — 200 OK ​

Error Responses ​

Create Affiliate ​

Request Body ​

Example Request ​

Success Response — 201 Created ​

Error Responses ​

Affiliate Self-Registration ​

Request Body ​

Example Request ​

Success Response — 201 Created ​

Error Responses ​

Update Affiliate ​

Path Parameters ​

Request Body ​

Example Request ​

Success Response — 200 OK ​

Error Responses ​

Delete Affiliate ​

Path Parameters ​

Example Request ​

Success Response — 204 No Content ​

Error Responses ​

Approve Affiliate ​

Path Parameters ​

Example Request ​

Success Response — 200 OK ​

Error Responses ​

Suspend Affiliate ​

Path Parameters ​

Request Body ​

Example Request ​

Success Response — 200 OK ​

Error Responses ​

Reactivate Affiliate ​

Path Parameters ​

Example Request ​

Success Response — 200 OK ​

Error Responses ​

Terminate Affiliate ​

Path Parameters ​

Request Body ​

Example Request ​

Success Response — 200 OK ​

Error Responses ​

Affiliates

List Affiliates

Query Parameters

Example Request

Success Response — 200 OK

Get Affiliate

Path Parameters

Example Request

Success Response — 200 OK

Error Responses

Create Affiliate

Request Body

Example Request

Success Response — 201 Created

Error Responses

Affiliate Self-Registration

Request Body

Example Request

Success Response — 201 Created

Error Responses

Update Affiliate

Path Parameters

Request Body

Example Request

Success Response — 200 OK

Error Responses

Delete Affiliate

Path Parameters

Example Request

Success Response — 204 No Content

Error Responses

Approve Affiliate

Path Parameters

Example Request

Success Response — 200 OK

Error Responses

Suspend Affiliate

Path Parameters

Request Body

Example Request

Success Response — 200 OK

Error Responses

Reactivate Affiliate

Path Parameters

Example Request

Success Response — 200 OK

Error Responses

Terminate Affiliate

Path Parameters

Request Body

Example Request

Success Response — 200 OK

Error Responses