list_coupons
List coupon codes with derived remaining-redemption counts. Read-only. Paginated, optionally narrowed to one project or filtered by on/off state.
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.
Requires ability
The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.
Runs the same action as
The REST endpoint and this tool share one action, so validation, permissions and events are identical.
Annotations
It reads and never changes anything.
Arguments
project_idstringoptionalOptional project UUID to narrow the list to a single project.
activebooleanoptionalOptional filter: true for codes that are switched on, false for those switched off.
limitintegeroptionalMaximum coupons to return per page (1..100).
1max100pageintegeroptional1-indexed page number.
1What it returns
{ "data": [ { "id": "4b9d3e08-a1f6-4275-9c83-7e01d6a2f594", "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13", "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 }}How it fails
RESOURCE_NOT_FOUNDunknown project_id, or the project is outside the token's scope.
AUTHENTICATION_REQUIREDno authenticated user on the request.
TOKEN_MISSING_ABILITYtoken lacks project-coupon:view-any.
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.
How is this guide?
Last updated on