Business Settings

Configure your affiliate program settings, branding, and commission tiers via the API.

All settings endpoints require the settings:read or settings:write scope.

Settings Object

{
  "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
}

Field	Type	Default	Description
commission_rate	float|null	null	Default commission rate (%) for all affiliates. null uses platform default. Per-affiliate overrides take priority.
cookie_duration	integer	30	How long the affiliate tracking cookie lasts (days, 1–365).
auto_approve_enabled	boolean	false	Automatically approve pending conversions matching criteria.
auto_approve_delay_days	integer	0	Days to wait before auto-approving (0–365).
auto_approve_min_amount	float|null	null	Only auto-approve conversions above this amount. null = no minimum.
auto_approve_max_amount	float|null	null	Only auto-approve conversions below this amount. null = no maximum.
allow_self_registration	boolean	false	Allow public affiliate signup at /affiliate/join.

---

Get All Settings

Retrieve all affiliate program settings for the business.

GET /v1/settings

• Scope: settings:read

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

---

Get Single Setting

Retrieve a single setting by key.

GET /v1/settings/{key}

• Scope: settings:read

Path Parameters

Parameter	Type	Description
key	string	One of the setting keys listed above

Response 200 OK

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

Error 404 Not Found — Unknown setting key.

---

Update Settings (Bulk)

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

PUT /v1/settings

• Scope: settings:write

Request Body (all fields optional)

{
  "commission_rate": 12.5,
  "cookie_duration": 45,
  "auto_approve_enabled": true,
  "auto_approve_delay_days": 7,
  "allow_self_registration": true
}

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

---

Update Single Setting

Update a single setting by key.

PUT /v1/settings/{key}

• Scope: settings:write

Request Body

{
  "value": 90
}

Response 200 OK

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

Error 403 Forbidden — Unknown or disallowed setting key.

---

Get Branding

Retrieve the business branding configuration.

GET /v1/settings/branding

• Scope: settings:read

Response 200 OK

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

---

Update Branding

Update the business logo URL and/or primary brand color. Pass remove_logo: true to clear the logo.

PUT /v1/settings/branding

• Scope: settings:write

Request Body

Field	Type	Description
logo_url	string|null	External URL for the business logo (e.g., S3 URL). Max 2048 chars.
primary_color	string|null	Hex color code (e.g., #FF6B2B).
remove_logo	boolean	Set to true to remove the current logo.

{
  "logo_url": "https://cdn.example.com/logo.png",
  "primary_color": "#1A2B3C"
}

Response 200 OK — Returns the branding object after update.

---

Get Commission Tiers

Retrieve platform default tiers and custom business tiers.

GET /v1/settings/commission-tiers

• Scope: settings:read

Commission Priority (lowest → highest): Platform base rate → Platform tiers → Business flat rate → Business tiers → Per-affiliate override.

Response 200 OK

{
  "success": true,
  "message": "OK",
  "data": {
    "using_custom": true,
    "platform_tiers": [
      { "min_amount": "0.00", "max_amount": "100.00", "rate": "5.00" }
    ],
    "business_tiers": [
      { "id": 12, "sort_order": 0, "min_amount": "0.00", "max_amount": "500.00", "rate": "8.00" }
    ]
  }
}

---

Create Commission Tier

Add a custom commission tier for the business. Tier ranges must not overlap.

POST /v1/settings/commission-tiers

• Scope: settings:write

Request Body

Field	Type	Required	Description
min_amount	numeric	Yes	Minimum order amount for this tier (≥ 0).
max_amount	numeric|null	No	Maximum order amount. null = unlimited.
rate	numeric	Yes	Commission rate percentage (0–100).

Response 201 Created

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

Error 422 Unprocessable Entity — Validation failure or overlapping range.

---

Update Commission Tier

Update an existing business commission tier.

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

• Scope: settings:write

Request Body — Same as Create Commission Tier.

Response 200 OK — Returns the updated tier.

Error 404 Not Found — Tier not found or belongs to another business.

---

Delete Commission Tier

Delete a business commission tier.

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

• Scope: settings:write

Response 204 No Content

Error 404 Not Found — Tier not found or belongs to another business.

---

Reset Commission Tiers

Delete all custom business tiers, reverting to platform defaults.

POST /v1/settings/commission-tiers/reset

• Scope: settings:write

Response 200 OK

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

---

Settings Endpoints Summary

Method	Path	Scope	Description
GET	/v1/settings	settings:read	Get all settings
PUT	/v1/settings	settings:write	Bulk update settings
GET	/v1/settings/{key}	settings:read	Get single setting
PUT	/v1/settings/{key}	settings:write	Update single setting
GET	/v1/settings/branding	settings:read	Get branding
PUT	/v1/settings/branding	settings:write	Update branding
GET	/v1/settings/commission-tiers	settings:read	Get commission tiers
POST	/v1/settings/commission-tiers	settings:write	Create tier
PUT	/v1/settings/commission-tiers/{id}	settings:write	Update tier
DELETE	/v1/settings/commission-tiers/{id}	settings:write	Delete tier
POST	/v1/settings/commission-tiers/reset	settings:write	Reset to defaults