list_coupons

List coupon codes with derived remaining-redemption counts. Read-only. Paginated, optionally narrowed to one project or filtered by on/off state.

Purpose

Discover existing coupon codes — to report on a campaign, to check whether a code already exists before calling create_coupon, or to find the id of a code the creator described by name.

Read-only. Never mutates anything.

Input schema

{
  "type": "object",
  "properties": {
    "project_id": {
      "type": "string",
      "description": "Optional project UUID to narrow the list to a single project."
    },
    "active": {
      "type": "boolean",
      "description": "Optional filter: true for codes that are switched on, false for those switched off."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "Maximum coupons to return per page (1..100). Defaults to 25."
    },
    "page": {
      "type": "integer",
      "minimum": 1,
      "description": "1-indexed page number. Defaults to 1."
    }
  }
}

Omitting project_id lists coupons across every project the token can reach.

Output shape

{
  "data": [
    {
      "id": "cpn_01HX...",
      "project_id": "prj_01HX...",
      "code": "BLACKFRIDAY",
      "name": "Black Friday 2026",
      "discount_type": "percentage",
      "discount_value": "25.0000",
      "currency": null,
      "duration": "once",
      "max_redemptions": 500,
      "max_redemptions_per_user": 1,
      "minimum_amount": null,
      "redemptions": {
        "count": 137,
        "remaining": 363,
        "exhausted": false
      },
      "starts_at": "2026-11-27T00:00:00+00:00",
      "expires_at": "2026-12-01T00:00:00+00:00",
      "plan_ids": [],
      "active": true,
      "redeemable": true,
      "created_at": "2026-11-20T09:14:02+00:00"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 25,
    "total": 4,
    "has_more": false
  }
}

Three fields worth reading carefully

`plan_ids: []` means every plan, not no plans

An empty array means the code applies to every plan in the project, including plans added later. An agent summarising a coupon must not report it as "not applied to any plan".

Prefer redemptions.remaining over your own subtraction. It is derived, not stored: the quota counts settled redemptions plus reservations whose hold has not expired, so an in-flight checkout is already accounted for and an abandoned one returns its slot. max_redemptions - count will disagree.

active is not redeemable. A code can be switched on and still not apply — outside its window, fully claimed, or capped for a particular subscriber. redeemable is the combined answer for the coupon as a whole; per-subscriber caps can only be resolved at checkout.

Example prompts

"List the coupon codes for project prj_01HX... and tell me which are still redeemable."

"How many uses are left on BLACKFRIDAY?"

"Do I already have a code called WELCOME10?"

"Show me every switched-off coupon across my projects."

Failure modes

RESOURCE_NOT_FOUND — unknown project_id, or the project is outside the token's scope.
AUTHENTICATION_REQUIRED — no authenticated user on the request.
TOKEN_MISSING_ABILITY — token lacks project-coupon:view-any.

An entitlement lapse is not a failure mode here. Listing keeps working without the Coupons Addon; only authoring is gated. Existing codes remain visible and simply stop applying at checkout.

create_coupon — author a new code.
Coupons API — update, delete, activate and deactivate.
coupon.* webhooks — react to redemptions instead of polling.