Claim a tier gift

POST /customers/{customer_id}/tier-gifts

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

Pulls a claimable gift of the customer’s tier and returns its code. Claiming twice returns the same code with changed: false.

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
gift_id	string	<tier_id>::<benefit_id>.

Response 200

Returns TierGiftClaim.

Field	Type	Description
changed	boolean	False when the gift was already claimed; the same code comes back.
gift_id	string
discount_code	string or null	(nullable)
reward_name	string or null	(nullable)

{
  "changed": true,
  "gift_id": "gift id",
  "discount_code": "CHARM-7Q2X9",
  "reward_name": "10% off"
}

Example

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

Errors

unauthorized · invalid_token · token_expired · insufficient_scope · access_required · not_found · 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.