read.internal.promotions_admin

The operator’s promotion list: state (derived from the window), the STRUCTURED benefit and target (the reader composes the sentence — the kernel never writes one), the names of the SKUs a benefit points at, codes, usage, and the conflict warning for a promotion that can never apply. Internal face.

• Surface: GET /v1/read/internal/promotions_admin · MCP tool read.internal.promotions_admin
• 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": {
    "class": {
      "enum": [
        "item",
        "order",
        "shipping"
      ],
      "type": "string"
    },
    "limit": {
      "default": 25,
      "maximum": 100,
      "minimum": 1,
      "type": "integer"
    },
    "offset": {
      "default": 0,
      "maximum": 9007199254740991,
      "minimum": 0,
      "type": "integer"
    },
    "q": {
      "minLength": 1,
      "type": "string"
    },
    "sort": {
      "enum": [
        "name_asc",
        "name_desc",
        "newest",
        "oldest",
        "usage_desc",
        "usage_asc"
      ],
      "type": "string"
    },
    "stackable": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "enum": [
            "0",
            "1",
            "true",
            "false"
          ],
          "type": "string"
        }
      ]
    },
    "state": {
      "enum": [
        "draft",
        "scheduled",
        "active",
        "expired",
        "paused",
        "archived"
      ],
      "type": "string"
    },
    "trigger": {
      "enum": [
        "automatic",
        "coupon"
      ],
      "type": "string"
    }
  },
  "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)