read.purchase_state

The WHOLE buying state of a cart in one call (by cart_id + store, the capability): the items of the purchase in flight with live prices and totals, the masked buyer and delivery, the payment state, the applied promotions, the custom fields, and the history of orders this cart has already placed. The cart is durable — it survives each order and can buy again — so this is the one read that orients any channel (storefront, CLI, agent) about where a purchase stands.

• Surface: GET /v1/read/purchase_state · CLI forge read purchase_state · MCP tool read.purchase_state
• Auth: public (no actor; store resolves the tenant)

Params (JSON Schema)

{
  "properties": {
    "cart_id": {
      "minLength": 1,
      "type": "string"
    },
    "store": {
      "minLength": 1,
      "type": "string"
    }
  },
  "required": [
    "store",
    "cart_id"
  ],
  "type": "object"
}

Result (200)

Open (unknown) — this capability does not declare an output schema.

Errors

validation_failed (400) · not_found (404)