Business Settings API

Note: Every endpoint in this document requires an active subscription. Without one it returns 402 SUBSCRIPTION_REQUIRED; see the REST API Overview.

Configure your affiliate program settings, branding, commission tiers, and payout schedules programmatically. These endpoints mirror the settings available in the business admin panel at /settings.

Authentication

Requires a Bearer access token with the appropriate scope:

Authorization: Bearer <access_token>

Base URL: https://api.heldsway.com/api. Endpoint paths in this document (/v1/...) are relative to it, so GET /v1/settings is https://api.heldsway.com/api/v1/settings. Endpoint paths in this document (/v1/...) are relative to https://api.heldsway.com/api.

Rate Limits

Data Models

Settings Object

The full settings object returned by GET /v1/settings and PUT /v1/settings:

{
  "commission_rate": 10.0,
  "cookie_duration": 30,
  "auto_approve_enabled": false,
  "auto_approve_delay_days": 0,
  "auto_approve_min_amount": null,
  "auto_approve_max_amount": null,
  "allow_self_registration": false,
  "store_catalog_path": "products-list"
}

Settings Field Reference

Branding Object

{
  "logo_url": "https://s3.amazonaws.com/your-bucket/logo.png",
  "primary_color": "#FF6B2B"
}

Commission Tier Object

{
  "id": 12,
  "sort_order": 0,
  "type": "percentage",
  "min_amount": "0.00",
  "max_amount": "500.00",
  "rate": "8.00"
}

Commission Priority

When resolving the effective commission rate for a conversion, the system evaluates in this order (highest priority wins):

Per-affiliate rate  >  Business flat rate  >  Business tiers  >  Platform tiers  >  Platform base rate

Payout Settings Object

The payout configuration returned by GET /v1/settings/payouts and PUT /v1/settings/payouts:

{
  "payout_frequency": "monthly",
  "payout_day": 1,
  "min_payout": "50.00",
  "currency": "USD",
  "allow_early_requests": true,
  "auto_create_payouts": true,
  "next_payout_date": "2026-11-01"
}

General Settings

Get All Settings

Retrieve all affiliate program settings for the business.

GET /v1/settings

Scope: settings:read
Rate limit: 120 requests/minute

Example request:

curl "https://api.heldsway.com/api/v1/settings"   -H "Authorization: Bearer <token>"

Response — 200 OK

{
  "success": true,
  "message": "OK",
  "data": {
    "commission_rate": null,
    "cookie_duration": 30,
    "auto_approve_enabled": false,
    "auto_approve_delay_days": 0,
    "auto_approve_min_amount": null,
    "auto_approve_max_amount": null,
    "allow_self_registration": false,
    "store_catalog_path": "products-list"
  }
}

Get Single Setting

Retrieve a single setting by its key.

GET /v1/settings/{key}

Scope: settings:read
Rate limit: 120 requests/minute

Path Parameters

Example request:

curl "https://api.heldsway.com/api/v1/settings/cookie_duration"   -H "Authorization: Bearer <token>"

Response — 200 OK

{
  "success": true,
  "message": "OK",
  "data": {
    "key": "cookie_duration",
    "value": 30
  }
}

Error — 404 Not Found (unknown key)

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Unknown setting key."
  }
}

Update Settings (Bulk)

Update one or more settings in a single request. Only fields present in the request body are updated; omitted fields remain unchanged.

PUT /v1/settings
Content-Type: application/json

Scope: settings:write
Rate limit: 60 requests/minute

Body Parameters — All fields are optional. Include only the settings you want to change.

Example request:

curl -X PUT "https://api.heldsway.com/api/v1/settings"   -H "Authorization: Bearer <token>"   -H "Content-Type: application/json"   -d '{
    "commission_rate": 12.5,
    "cookie_duration": 45,
    "auto_approve_enabled": true,
    "auto_approve_delay_days": 7,
    "store_catalog_path": "catalog"
  }'

Response — 200 OK — Returns the full settings object after the update.

{
  "success": true,
  "message": "Settings updated.",
  "data": {
    "commission_rate": 12.5,
    "cookie_duration": 45,
    "auto_approve_enabled": true,
    "auto_approve_delay_days": 7,
    "auto_approve_min_amount": null,
    "auto_approve_max_amount": null,
    "allow_self_registration": false,
    "store_catalog_path": "catalog"
  }
}

Error — 422 Unprocessable Entity (validation failure — Laravel’s standard validation body from UpdateBusinessSettingsApiRequest)

{
  "message": "The commission rate field must not be greater than 100.",
  "errors": {
    "commission_rate": ["The commission rate field must not be greater than 100."]
  }
}

Update Single Setting

Update a single setting by its key.

PUT /v1/settings/{key}
Content-Type: application/json

Scope: settings:write
Rate limit: 60 requests/minute

Path Parameters

Body Parameters

Example request:

curl -X PUT "https://api.heldsway.com/api/v1/settings/cookie_duration"   -H "Authorization: Bearer <token>"   -H "Content-Type: application/json"   -d '{ "value": 90 }'

Response — 200 OK

{
  "success": true,
  "message": "Setting updated.",
  "data": {
    "key": "cookie_duration",
    "value": 90
  }
}

Error — 403 Forbidden (unknown or disallowed key — UpdateSingleSettingApiRequest::authorize() returns false, so Laravel’s authorization response is returned, with no envelope or code)

{
  "message": "This action is unauthorized."
}

Error — 422 Unprocessable Entity (invalid value for the key — Laravel’s standard validation body from UpdateSingleSettingApiRequest)

{
  "message": "The value field must be at least 1.",
  "errors": {
    "value": ["The value field must be at least 1."]
  }
}

Branding

Get Branding

Retrieve the business branding configuration (logo and primary color).

GET /v1/settings/branding

Scope: settings:read
Rate limit: 120 requests/minute

Example request:

curl "https://api.heldsway.com/api/v1/settings/branding"   -H "Authorization: Bearer <token>"

Response — 200 OK

{
  "success": true,
  "message": "OK",
  "data": {
    "logo_url": "https://s3.amazonaws.com/your-bucket/logo.png",
    "primary_color": "#FF6B2B"
  }
}

If no branding is configured:

{
  "success": true,
  "message": "OK",
  "data": {
    "logo_url": null,
    "primary_color": null
  }
}

Update Branding

Update the business logo URL and/or primary brand color. You can also remove the logo by sending remove_logo: true.

PUT /v1/settings/branding
Content-Type: application/json

Scope: settings:write
Rate limit: 60 requests/minute

Body Parameters — All fields are optional. Include only what you want to change.

Example — Set logo and color:

curl -X PUT "https://api.heldsway.com/api/v1/settings/branding"   -H "Authorization: Bearer <token>"   -H "Content-Type: application/json"   -d '{
    "logo_url": "https://cdn.example.com/logos/acme.png",
    "primary_color": "#1A2B3C"
  }'

Response — 200 OK

{
  "success": true,
  "message": "Branding updated.",
  "data": {
    "logo_url": "https://cdn.example.com/logos/acme.png",
    "primary_color": "#1A2B3C"
  }
}

Example — Remove logo:

curl -X PUT "https://api.heldsway.com/api/v1/settings/branding"   -H "Authorization: Bearer <token>"   -H "Content-Type: application/json"   -d '{ "remove_logo": true }'

Response — 200 OK

{
  "success": true,
  "message": "Branding updated.",
  "data": {
    "logo_url": null,
    "primary_color": "#1A2B3C"
  }
}

Error — 422 Unprocessable Entity (Laravel’s standard validation body from UpdateBrandingApiRequest)

{
  "message": "The logo url field must be a valid URL. (and 1 more error)",
  "errors": {
    "logo_url": ["The logo url field must be a valid URL."],
    "primary_color": ["The primary color field format is invalid."]
  }
}

Commission Tiers

Commission tiers allow you to configure variable commission rates based on order amount. Each tier defines a min/max range and the commission rate applied when an order falls within that range.

Businesses can define custom tiers that override the platform default tiers. When no custom tiers exist, the platform defaults are used.

Get Commission Tiers

Retrieve both platform default tiers and custom business tiers.

GET /v1/settings/commission-tiers

Scope: settings:read
Rate limit: 120 requests/minute

Example request:

curl "https://api.heldsway.com/api/v1/settings/commission-tiers"   -H "Authorization: Bearer <token>"

Response — 200 OK (business has custom tiers)

{
  "success": true,
  "message": "OK",
  "data": {
    "using_custom": true,
    "platform_tiers": [
      { "type": "percentage", "min_amount": "0.00", "max_amount": "100.00", "rate": "5.00" },
      { "type": "percentage", "min_amount": "100.00", "max_amount": null, "rate": "10.00" }
    ],
    "business_tiers": [
      { "id": 12, "sort_order": 0, "type": "percentage", "min_amount": "0.00", "max_amount": "500.00", "rate": "8.00" },
      { "id": 13, "sort_order": 1, "type": "percentage", "min_amount": "500.00", "max_amount": null, "rate": "12.00" }
    ]
  }
}

Response — 200 OK (no custom tiers, using platform defaults)

{
  "success": true,
  "message": "OK",
  "data": {
    "using_custom": false,
    "platform_tiers": [
      { "type": "percentage", "min_amount": "0.00", "max_amount": "100.00", "rate": "5.00" },
      { "type": "percentage", "min_amount": "100.00", "max_amount": null, "rate": "10.00" }
    ],
    "business_tiers": []
  }
}

Response Fields

Create Commission Tier

Add a new custom commission tier. The tier range must not overlap with existing business tiers.

POST /v1/settings/commission-tiers
Content-Type: application/json

Scope: settings:write
Rate limit: 60 requests/minute

Body Parameters

Example request:

curl -X POST "https://api.heldsway.com/api/v1/settings/commission-tiers"   -H "Authorization: Bearer <token>"   -H "Content-Type: application/json"   -d '{
    "min_amount": 0,
    "max_amount": 500,
    "commission_type": "percentage",
    "rate": 8
  }'

Response — 201 Created

{
  "success": true,
  "message": "Created",
  "data": {
    "id": 12,
    "sort_order": 0,
    "type": "percentage",
    "min_amount": "0.00",
    "max_amount": "500.00",
    "rate": "8.00"
  }
}

Error — 422 Unprocessable Entity (overlapping range)

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": {
      "min_amount": ["This tier range overlaps with an existing tier."]
    }
  }
}

Error — 422 Unprocessable Entity (min >= max)

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": {
      "min_amount": ["Minimum amount must be less than maximum amount."]
    }
  }
}

Update Commission Tier

Update an existing business commission tier. The updated range must not overlap with other tiers.

PUT /v1/settings/commission-tiers/{id}
Content-Type: application/json

Scope: settings:write
Rate limit: 60 requests/minute

Path Parameters

Body Parameters — Same as Create Commission Tier.

Example request:

curl -X PUT "https://api.heldsway.com/api/v1/settings/commission-tiers/12"   -H "Authorization: Bearer <token>"   -H "Content-Type: application/json"   -d '{
    "min_amount": 0,
    "max_amount": 750,
    "commission_type": "percentage",
    "rate": 10
  }'

Response — 200 OK

{
  "success": true,
  "message": "Commission tier updated.",
  "data": {
    "id": 12,
    "sort_order": 0,
    "type": "percentage",
    "min_amount": "0.00",
    "max_amount": "750.00",
    "rate": "10.00"
  }
}

Error — 404 Not Found

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Commission tier not found."
  }
}

Note: Tiers are scoped to the business associated with your API key. You cannot access or modify tiers belonging to another business.

Delete Commission Tier

Delete a single business commission tier.

DELETE /v1/settings/commission-tiers/{id}

Scope: settings:write
Rate limit: 60 requests/minute

Path Parameters

Example request:

curl -X DELETE "https://api.heldsway.com/api/v1/settings/commission-tiers/12"   -H "Authorization: Bearer <token>"

Response — 204 No Content

No response body.

Error — 404 Not Found

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Commission tier not found."
  }
}

Reset Commission Tiers

Delete all custom business tiers, reverting the business to use platform default tiers.

POST /v1/settings/commission-tiers/reset

Scope: settings:write
Rate limit: 60 requests/minute

Example request:

curl -X POST "https://api.heldsway.com/api/v1/settings/commission-tiers/reset"   -H "Authorization: Bearer <token>"

Response — 200 OK

{
  "success": true,
  "message": "Commission tiers reset to platform defaults."
}

Payout Settings

Configure the schedule, minimum accrued threshold, and rules for generating affiliate payouts.

Get Payout Settings

Retrieve current payout configuration and the estimated date of the next payout cycle.

GET /v1/settings/payouts

Scope: settings:read
Rate limit: 120 requests/minute

Example request:

curl "https://api.heldsway.com/api/v1/settings/payouts"   -H "Authorization: Bearer <token>"

Response — 200 OK

{
  "success": true,
  "message": "OK",
  "data": {
    "payout_frequency": "monthly",
    "payout_day": 1,
    "min_payout": "50.00",
    "currency": "USD",
    "allow_early_requests": true,
    "auto_create_payouts": true,
    "next_payout_date": "2026-11-01"
  }
}

Update Payout Settings

Update payout frequency, scheduling, minimum payout threshold, and early request options.

PUT /v1/settings/payouts
Content-Type: application/json

Scope: settings:write
Rate limit: 60 requests/minute

Body Parameters

Example request:

curl -X PUT "https://api.heldsway.com/api/v1/settings/payouts" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "payout_frequency": "monthly",
    "payout_day": 15,
    "min_payout": 100.00,
    "allow_early_requests": false,
    "auto_create_payouts": true
  }'

Response — 200 OK

{
  "success": true,
  "message": "Payout settings updated.",
  "data": {
    "payout_frequency": "monthly",
    "payout_day": 15,
    "min_payout": "100.00",
    "currency": "USD",
    "allow_early_requests": false,
    "auto_create_payouts": true,
    "next_payout_date": "2026-11-15"
  }
}

Error — 422 Unprocessable Entity (Laravel’s standard validation body from UpdatePayoutSettingsApiRequest)

{
  "message": "The payout day field must not be greater than 7.",
  "errors": {
    "payout_day": ["The payout day field must not be greater than 7."]
  }
}

Error Reference

All endpoints follow the standard response envelope.

Quick Reference