Get the UCP loyalty object with an earning forecast for a cart

POST /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 needed: this call has no side effect
MCP tool	charm_forecast_ucp_loyalty

Same as GET, plus rewards[].earning_forecast for the cart in line_items: the points the purchase would earn, broken down into base earning, the tier multiplier and campaigns, whose amounts add up to the total. No idempotency key: nothing is written.

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
line_items	array of object
discounts_total	number	(optional)
locale	string	(optional)

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 POST "https://charm.appfleece.app/api/v1/customers/7712345/ucp-loyalty" \
  -H "Authorization: Bearer chrm_live_..." \
  -H "Content-Type: application/json" \
  -d '{"line_items":[{"product_id":"8123456789","variant_id":"44123456789","price":1,"quantity":1,"collection_ids":["collection ids"],"tags":["tags"]}]}'

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.