Change who earns

PATCH /program/eligibility


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_eligibility`

Changes the exclusions and the opt-in requirement. A list you send replaces the stored list; keys you omit stay. Products, variants and collections must exist in Shopify. Switching opt_in.required on links the shop’s published terms and privacy policy and counts existing members as joined. Call with dry_run: true first.

Request body

Field	Type	Description
`customer_audience`	string: `all`, `b2c_only`, `b2b_only`	(optional)
`excluded_customer_tags`	array of string	(optional)
`excluded_order_tags`	array of string	(optional)
`excluded_product_tags`	array of string	(optional)
`excluded_products`	array of object	(optional)
`excluded_collections`	array of string	Collection ids, numeric or GID. (optional)
`exclude_gift_cards`	boolean	(optional)
`exclude_discounted_items`	boolean	(optional)
`exclude_subscription_renewals`	boolean	(optional)
`exclude_membership_purchases`	boolean	(optional)
`opt_in`	object	(optional)
`member_discounts`	object	What the automatic VIP tier and membership discount may touch at checkout. Keys you omit stay; lists replace. Membership products and gift cards are never discounted. (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 EligibilityWriteResult.

Field	Type	Description
`dry_run`	boolean
`revision`	integer
`operation`	string: `update`, `none`
`diff`	array of FieldChange
`summary`	string or null	(nullable)
`eligibility`	Eligibility

{
  "dry_run": false,
  "revision": 1,
  "operation": "update",
  "diff": [
    {
      "path": "path",
      "before": null,
      "after": null
    }
  ],
  "summary": "summary",
  "eligibility": {
    "revision": 1,
    "customer_audience": "all",
    "excluded_customer_tags": [
      "excluded customer tags"
    ],
    "excluded_order_tags": [
      "excluded order tags"
    ],
    "excluded_product_tags": [
      "excluded product tags"
    ],
    "excluded_products": [
      {
        "id": "id",
        "title": "title",
        "variant_ids": [
          null
        ]
      }
    ],
    "excluded_collections": [
      {
        "id": "id",
        "title": "title"
      }
    ],
    "exclude_gift_cards": false,
    "exclude_discounted_items": false,
    "exclude_subscription_renewals": false,
    "exclude_membership_purchases": false,
    "opt_in": {
      "required": false,
      "marketing_consent": false
    },
    "member_discounts": {
      "combine_with_other_discounts": false,
      "exclude_sale_items": false,
      "exclude_subscription_items": false,
      "excluded_product_tags": [
        "excluded product tags"
      ],
      "excluded_collections": [
        {
          "id": null,
          "title": null
        }
      ]
    }
  }
}

Example

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