read.internal.promotion_simulate

DRY RUN: what this promotion would do to a cart the operator describes. Writes nothing, consumes nothing, charges nothing — it runs the SAME engine the checkout runs, so the admin never re-implements a rule. Internal face.

• Surface: GET /v1/read/internal/promotion_simulate · MCP tool read.internal.promotion_simulate
• Auth: ★ Internal read (operator) — a tenant credential is REQUIRED; requires the promotion.read scope. The tenant is resolved from the CALLER’s identity, never from store. Personal fields come back MASKED for an actor without pii.read (the shape is unchanged).

Params (JSON Schema)

{
  "properties": {
    "cart": {
      "type": "string"
    },
    "customer_email": {
      "format": "email",
      "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
      "type": "string"
    },
    "payment_method": {
      "enum": [
        "pix",
        "card",
        "promissory",
        "zero"
      ],
      "type": "string"
    },
    "promotion_id": {
      "minLength": 1,
      "type": "string"
    },
    "shipping_amount": {
      "maximum": 9007199254740991,
      "minimum": 0,
      "type": "integer"
    },
    "shipping_method_id": {
      "minLength": 1,
      "type": "string"
    }
  },
  "required": [
    "promotion_id",
    "cart"
  ],
  "type": "object"
}

Result (200)

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

Errors

validation_failed (400) · not_found (404) · unauthorized (401) · forbidden (403)