Change the referral program

PATCH /program/referrals

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_referral_program

Changes what referrers and friends get and when: fields are the referral rule’s catalog keys (referrer reward type, points or discount, gift product, the friend’s points, minimum order, cooldown, caps, milestones); friend_discount is the friend’s first-order code (its minimum always follows fields.referralMinimumOrderAmount); code_prefix sets how codes begin. Keys you omit stay. Live friend codes follow the new settings on save. Switching the referral program on or off stays in the admin; a program never set up is created switched off. Call with dry_run: true first.

Request body

Field	Type	Description
fields	object	The referral rule’s configuration, keyed as GET /program/rule-types?kind=earning documents for type referral. Omitted keys stay. (optional)
title	string or null	The referral card’s title in the primary language; null restores the default. (optional, nullable)
title_translations	object	The title in other published languages; null removes one. (optional)
friend_discount	object	(optional)
code_prefix	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 ReferralWriteResult.

Field	Type	Description
dry_run	boolean	True when nothing was written.
revision	integer	The program revision after the write (unchanged on a dry run).
operation	string: create, update, none
diff	array of FieldChange
summary	string or null	The admin’s one-line summary of the referral rule after the change. (nullable)
referral_program	ReferralProgram
friend_codes_resync_failed	integer	Live friend codes that could not be updated to the new settings now; the next save retries them. (optional)

{
  "dry_run": false,
  "revision": 1,
  "operation": "create",
  "diff": [
    {
      "path": "path",
      "before": null,
      "after": null
    }
  ],
  "summary": "summary",
  "referral_program": {
    "revision": 1,
    "enabled": true,
    "earning_rule": {
      "id": null,
      "type": null,
      "enabled": null,
      "label": null,
      "points": null,
      "points_per_currency": null,
      "limit": null,
      "title": null,
      "title_translations": null,
      "fields": null,
      "summary": null
    },
    "friend_discount": {
      "enabled": true,
      "type": "percentage",
      "value": 1,
      "usage_limit": 1,
      "minimum_purchase": 1,
      "tier_overrides": {}
    },
    "code_prefix": {
      "custom": false,
      "prefix": "prefix"
    }
  },
  "friend_codes_resync_failed": 1
}

Example

curl -X PATCH "https://charm.appfleece.app/api/v1/program/referrals" \
  -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.