Adjust a balance

POST /customers/{customer_id}/points/adjust


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

Applies a signed correction. Unlike earn there is no natural idempotency key, so the Idempotency-Key header is the only thing preventing a retry from applying twice. delta and reason may also be sent as query parameters, for no-code clients (a Gorgias action button, say) whose only way to collect a value from a human is the query string; the body wins when both are present, and the query string is part of the idempotency hash.

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.
`delta` (optional)	query	integer	Alternative to the body field of the same name.
`reason` (optional)	query	string	Alternative to the body field of the same name.

Request body

Field	Type	Description
`delta`	integer	Signed change; negative values deduct. Must be non-zero and within the safe integer range. A deduction larger than the balance is clamped, and the response reports both `requested` and `applied`.
`reason`	string	Shown verbatim in the customer’s history. (optional)

Response `200`

Returns AdjustResult.

Field	Type	Description
`changed`	boolean
`requested`	number
`applied`	number	What actually landed; differs from `requested` when a negative delta is clamped at zero.
`balance_after`	number or null	(nullable)
`balance`	Balance

{
  "changed": true,
  "requested": 120,
  "applied": 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/adjust" \
  -H "Authorization: Bearer chrm_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"delta":1,"reason":"Goodwill after a late delivery"}'

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.