Change the partner programme

PATCH /program/affiliates/settings

Scope	program:write
Customer session token	Not accepted: call from your server with an API key
Rate limit class	write_shopify (limits)
Idempotency key	Required (idempotency)
MCP tool	charm_update_affiliate_program_settings

Changes the programme’s defaults. A new buyer discount reaches every partner code that inherits it. Switching the programme on, opening applications, approving partners, payouts and invoicing stay in the admin. Call with dry_run: true first.

Request body

Field	Type	Description
commission	object	(optional)
customer_discount	object	(optional)
commission_base	object	(optional)
holdback_days	integer	(optional)
link_attribution_window_days	integer	(optional)
code_prefix	string	(optional)
terms_url	string or null	(optional, nullable)
allow_self_referral	boolean	(optional)
hub_invite_after_referrals	integer	(optional)
hide_order_value	boolean	(optional)
utm	object	(optional)
dry_run	boolean	Preview only: validate, resolve references and return the diff and summary, but write nothing. Costs no idempotency key and is limited as a read. Call with this first, show the merchant, then repeat without it. (optional)
if_revision	integer	The program revision you last read (from GET /program or a previous write). When the program changed since, the write is refused with 409 revision_conflict instead of overwriting a concurrent admin edit. (optional)

Response 200

Returns AffiliateSettingsWriteResult.

Field	Type	Description
dry_run	boolean
revision	integer
operation	string: update, none
diff	array of FieldChange
summary	string or null	(nullable)
affiliate_settings	AffiliateProgramSettings
partner_codes_sync_failed	boolean	Saved, but some partner codes did not take the new buyer discount yet; the next change retries. (optional)

{
  "dry_run": false,
  "revision": 1,
  "operation": "update",
  "diff": [
    {
      "path": "path",
      "before": null,
      "after": null
    }
  ],
  "summary": "summary",
  "affiliate_settings": {
    "revision": 1,
    "enabled": true,
    "applications_open": false,
    "auto_approve": false,
    "commission": {
      "type": "percent",
      "code_rate": 1,
      "link_rate": 1
    },
    "customer_discount": {
      "type": "percentage",
      "value": 1
    },
    "commission_base": {
      "include_shipping": false,
      "include_tax": false,
      "after_discounts": false
    },
    "holdback_days": 1,
    "link_attribution_window_days": 1,
    "code_prefix": "REF",
    "terms_url": "terms url",
    "allow_self_referral": false,
    "hub_invite_after_referrals": 1,
    "hide_order_value": false,
    "utm": {
      "enabled": true,
      "source": "order",
      "medium": "medium",
      "campaign": "campaign"
    }
  },
  "partner_codes_sync_failed": false
}

Example

curl -X PATCH "https://charm.appfleece.app/api/v1/program/affiliates/settings" \
  -H "Authorization: Bearer chrm_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

Errors

unauthorized · invalid_token · insufficient_scope · access_required · validation_error · rate_limited · idempotency_conflict · shopify_unavailable

Every error body carries code, message, request_id and a doc_url pointing at the matching entry in the error catalog.