Award points

POST /customers/{customer_id}/points/earn


Scope	`points:write`
Customer session token	Not accepted: call from your server with an API key
Rate limit class	`write` (limits)
Idempotency key	Required (idempotency)
MCP tool	`charm_earn_points`

Awards points for an external event. source_ref is required and makes the award idempotent at the database level: repeating it returns the original result with deduplicated: true instead of awarding twice.

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
`points`	integer	Points to award. Must be a whole number in the safe integer range.
`source_ref`	string	Your stable identifier for the event being rewarded. Reusing it is a no-op, so retries are safe.
`reason`	string	Shown verbatim in the customer’s history. When omitted, a localized default is used instead. (optional)
`metadata`	object	Arbitrary JSON stored alongside the transaction. (optional)

Response `200`

Returns EarnResult.

Field	Type	Description
`changed`	boolean	False when `source_ref` was already awarded (a retry).
`deduplicated`	boolean	Same as `!changed`. Kept for existing integrations.
`points_awarded`	number
`balance`	Balance

{
  "changed": true,
  "deduplicated": false,
  "points_awarded": 120,
  "balance": {
    "id": "gid://shopify/Customer/7712345",
    "legacy_id": 7712345,
    "points_balance": 120,
    "points_earned": 120,
    "points_redeemed": 120,
    "pending_points": 120
  }
}

Example

curl -X POST "https://charm.appfleece.app/api/v1/customers/7712345/points/earn" \
  -H "Authorization: Bearer chrm_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"points":120,"source_ref":"pos-receipt-4471"}'

Errors

unauthorized · invalid_token · 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.