Estimate the points a cart would earn

POST /estimates


Scope	`program: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_estimate_cart_points`

The points a whole cart would earn, computed like the order award: line exclusions, the program’s amount basis and tax handling, order campaigns and, with customer_id, the customer’s tier multiplier. Send unit prices in the shop currency; no Shopify lookup happens. No idempotency key: an estimate has no side effect.

Request body

Field	Type	Description
`lines`	array of object
`customer_id`	string	Prices the cart for this customer (tier, campaigns). (optional)
`discounts_total`	number	Order-level discounts in the shop currency. (optional)

Response `200`

Returns CartEstimate.

Field	Type	Description
`enabled`	boolean	False when nothing would be earned; see `reason`.
`reason`	string or null: `program_disabled`, `no_points_layer`, `customer_excluded`, `no_eligible_lines`, `nothing_earned`	(nullable)
`points`	integer	Total the cart would earn.
`base_points`	integer	Before tier and campaign multipliers.
`bonus_points`	integer	From the tier multiplier and campaigns.
`tier_multiplier`	number
`campaign_multiplier`	number
`points_per_currency`	number	The order rule’s rate, points per unit of the shop currency.
`eligible_amount`	number	The amount that earns, in the shop currency, after exclusions and tax handling.
`lines`	array of CartEstimateLine
`currency`	string or null	(nullable)
`customer_id`	string or null	The customer the estimate was priced for; null for anonymous. (nullable)
`estimate`	`true`

{
  "enabled": true,
  "reason": "program_disabled",
  "points": 120,
  "base_points": 120,
  "bonus_points": 120,
  "tier_multiplier": 1,
  "campaign_multiplier": 1,
  "points_per_currency": 120,
  "eligible_amount": 1,
  "lines": [
    {
      "index": 1,
      "product_id": "8123456789",
      "eligible": false
    }
  ],
  "currency": "EUR",
  "customer_id": "gid://shopify/Customer/7712345",
  "estimate": true
}

Example

curl -X POST "https://charm.appfleece.app/api/v1/estimates" \
  -H "Authorization: Bearer chrm_live_..." \
  -H "Content-Type: application/json" \
  -d '{"lines":[{"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 · 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.