Record a share of the customer's referral link

POST /customers/{customer_id}/referral-shares


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

Counts one share per call, per channel and day, so referral reach is measurable from headless storefronts and apps. The total shows in include=referral.

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
`channel`	string: `copy_link`, `device_share`, `email`, `sms`, `whatsapp`, `messenger`, `telegram`, `facebook`, `x`, `instagram`, `other`

Response `200`

Returns ShareResult.

Field	Type	Description
`changed`	boolean
`channel`	string

{
  "changed": true,
  "channel": "channel"
}

Example

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

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.