Claim a referral for a friend

POST /referrals/claim

Scope	customers: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_claim_referral

For a friend who arrived through a member’s referral link: returns the friend’s discount (the member’s code, created on first use), what the friend earns, and the cart attribute that attributes the order. With customer_id, attributes the referral now, through the same fraud guards as the storefront (self-referral, returning customer, disposable domains, velocity, one referral per friend). Server side only.

Request body

Field	Type	Description
referral_code	string	The ref code from the link.
customer_id	string	The friend’s Shopify customer id, when they have an account. (optional)

Response 200

Returns ReferralClaim.

Field	Type	Description
changed	boolean	True when the referral was attributed to customer_id now.
referral_code	string
discount	object or null	(nullable)
friend_rewards	object
cart_attribute	object	Set on the Storefront API cart so the order attributes the referral without the code.
attributed	boolean or null	With customer_id: whether the referral is now attributed (fraud guards may refuse). Null without. (nullable)

{
  "changed": true,
  "referral_code": "JANE10",
  "discount": {
    "code": "code",
    "type": "percentage",
    "value": 1,
    "minimum_purchase": 1,
    "once_per_customer": true
  },
  "friend_rewards": {
    "points": 120,
    "gift": false
  },
  "cart_attribute": {
    "key": "key",
    "value": "value"
  },
  "attributed": false
}

Example

curl -X POST "https://charm.appfleece.app/api/v1/referrals/claim" \
  -H "Authorization: Bearer chrm_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"referral_code":"JANE10","customer_id":"gid://shopify/Customer/7712345"}'

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.