HeldSway REST API — Overview

Manage affiliates, referral links, commission rules, tracked orders, reports, payouts, and business settings programmatically with the HeldSway REST API.

Base URL

All REST API endpoints are prefixed with the API base URL:

https://api.heldsway.com/api/v1

All requests must use HTTPS. In this documentation, paths are specified relative to this base URL (for example, GET /affiliates resolves to https://api.heldsway.com/api/v1/affiliates).

Authentication & Scopes

All endpoints (except Token Issuance POST /v1/auth/token) require a valid Bearer access token in the HTTP Authorization header:

Authorization: Bearer <access_token>

Bearer tokens are obtained via the Token Issuance endpoint using your business’s api_key and api_secret.

Available Scopes

Standard Response Envelope

All API responses follow a consistent JSON envelope format.

Success Response Format

{
  "success": true,
  "message": "Resource retrieved successfully.",
  "data": { ... },
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 20,
    "total": 92
  }
}

Error Response Format

{
  "success": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "The given data was invalid.",
    "details": {
      "email": ["The email has already been taken."]
    }
  }
}

Rate Limits

To guarantee service reliability, requests are throttled per API key or client IP:

When a throttle limit is reached, the API returns 429 Too Many Requests with a Retry-After: <seconds> response header.

Error Codes

Quick Reference Index

The HeldSway REST API exposes 60 dedicated endpoints across 10 functional modules:

1. Authentication

2. Affiliates

3. Referral Links

4. Commission Configuration

5. Orders & Conversions

6. Reports & Analytics

7. Coupon Reports

8. Payouts Management

9. Business Settings

10. Business Connection

Data Models

Affiliate Object

{
  "id": "aff_01HXYZ123456",
  "business_id": "biz_01HABC987654",
  "user_id": "usr_01HJ789012",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "status": "active",
  "commission_rate": null,
  "commission_type": null,
  "payment_method": "paypal",
  "payment_details": {
    "paypal_email": "jane@example.com"
  },
  "created_at": "2026-04-01T12:00:00Z",
  "updated_at": "2026-04-10T08:30:00Z"
}

Referral Link Object

{
  "id": "lnk_01HXYZ789012",
  "affiliate_id": "aff_01HXYZ123456",
  "business_id": "biz_01HABC987654",
  "slug": "jane-spring",
  "url": "https://store.example.com?ref=jane-spring",
  "destination_url": "https://store.example.com/spring-sale",
  "campaign": "Spring2026",
  "is_active": true,
  "coupon_code": "JANE10",
  "clicks_count": 1420,
  "conversions_count": 89,
  "created_at": "2026-04-01T12:00:00Z"
}

Order / Conversion Object

{
  "id": "ord_01HDEF345678",
  "business_id": "biz_01HABC987654",
  "affiliate_id": "aff_01HXYZ123456",
  "link_id": "lnk_01HXYZ789012",
  "order_number": "ORDER-99812",
  "amount": 120.00,
  "currency": "USD",
  "commission_amount": 12.00,
  "commission_rate": 10.0,
  "commission_status": "pending",
  "location_id": "loc_nyc_01",
  "location_name": "Manhattan Flagship",
  "product_id": "prod_camera_x1",
  "product_name": "Professional 4K Camera",
  "customer_id": "cust_88219",
  "created_at": "2026-04-15T14:22:10Z"
}