Get the buyer's membership as a UCP loyalty object

GET /customers/{customer_id}/ucp-loyalty


Scope	`customers:read`
Customer session token	Accepted with the `read` scope, for the token’s own customer
Rate limit class	`read` (limits)
Idempotency key	Not used
MCP tool	`charm_get_ucp_loyalty`

The Universal Commerce Protocol loyalty extension (dev.ucp.common.loyalty) for this customer: tier, benefits and reward currency, keyed by the program’s reverse-domain claim id. For merchants and platforms answering UCP catalog, cart and checkout requests for AI agents. A non-member answers an empty map with an eligibility_invalid message.

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.
`locale` (optional)	query	string	Language for benefit texts, e.g. `de`.

Response `200`

Returns UcpLoyalty.

Field	Type	Description
`loyalty`	object	The UCP `dev.ucp.common.loyalty` map, keyed by the program’s reverse-domain claim id (`com.myshopify.<handle>.loyalty`). Empty when the buyer is not a member.
`messages`	array of UcpMessage

{
  "loyalty": {},
  "messages": [
    {
      "type": "info",
      "code": "code",
      "path": "path",
      "content": "content"
    }
  ]
}

Example

curl -X GET "https://charm.appfleece.app/api/v1/customers/7712345/ucp-loyalty" \
  -H "Authorization: Bearer chrm_live_..."

Errors

unauthorized · invalid_token · token_expired · insufficient_scope · access_required · not_found · validation_error · rate_limited

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