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
}

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

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

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

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