Deduct points

POST /customers/{customer_id}/points/deduct


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

Removes points. The balance is clamped at zero rather than going negative.

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
`reason`	string	(optional)
`source_ref`	string	(optional)

Response `200`

Returns DeductResult.

Field	Type	Description
`changed`	boolean
`requested`	number
`applied`	number
`points_deducted`	number	Same as `applied`. Kept for existing integrations.
`balance_after`	number or null	(nullable)
`balance`	Balance

{
  "changed": true,
  "requested": 120,
  "applied": 120,
  "points_deducted": 120,
  "balance_after": 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/deduct" \
  -H "Authorization: Bearer chrm_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"points":120}'

Errors

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

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