Claim a claimable earning rule

POST /customers/{customer_id}/claims

Scope	customers:write
Customer session token	Accepted with the write scope, for the token’s own customer
Rate limit class	write (limits)
Idempotency key	Required (idempotency)
MCP tool	charm_claim_earning_rule

The widget’s claim button for rules the merchant made claimable: newsletter or SMS signup (verified against Shopify marketing consent; send marketing_consent: true to subscribe, phone for SMS), birthday (in the birthday month), social follows, visiting a URL and custom actions (once per customer). Refusals carry details.reason, e.g. already_claimed, consent_required, not_birthday_month, join_required.

Parameters

Name	In	Type	Description
customer_id	path	string	Shopify customer GID (percent-encoded, e.g. gid%3A%2F%2Fshopify%2FCustomer%2F123) or the numeric customer id.

Request body

Field	Type	Description
rule_id	string	An earning rule id from /v1/program.
marketing_consent	boolean	(optional)
phone	string	(optional)
locale	string	(optional)

Response 200

Returns ClaimResult.

Field	Type	Description
changed	boolean
rule_id	string
points_awarded	number
balance_after	number or null	(nullable)
discount_code	string or null	When the rule rewards with a code (e.g. a birthday reward). (nullable)
is_pending	boolean	Points held until a waiting period passes.

{
  "changed": true,
  "rule_id": "rule id",
  "points_awarded": 120,
  "balance_after": 120,
  "discount_code": "CHARM-7Q2X9",
  "is_pending": false
}

Example

curl -X POST "https://charm.appfleece.app/api/v1/customers/7712345/claims" \
  -H "Authorization: Bearer chrm_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"rule_id":"rule id"}'

Errors

unauthorized · invalid_token · token_expired · insufficient_scope · access_required · not_found · validation_error · rate_limited · idempotency_conflict

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