get_coupon
Fetch one coupon by UUID — discount, limits, redemption tally, plan restriction and whether it is redeemable right now.
Read one coupon code in full. The row is the same one list_coupons
emits, so an agent that spotted a code in the list reads exactly the same fields back here, and the
row a write tool returns after a change is comparable field for field.
Reads go through the coupon service, so the tenant scope and the token's scope:project: allow-list
both apply. An id the token cannot see — unknown, another team's, or on a project outside the
allow-list — answers RESOURCE_NOT_FOUND, indistinguishable from an id that never existed.
Call it before update_coupon or
delete_coupon to read the current state rather than assuming it.
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
coupon_id*stringUUID of the coupon to fetch.
What 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" }}`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. Do not summarise it as "not applied to any plan".
active is not redeemable. A code can be switched on and still not apply — before
starts_at, after expires_at, or with the cap reached. redeemable is the combined answer for the
coupon as a whole; per-subscriber caps are only resolved at checkout.
Prefer redemptions.remaining over your own subtraction. It is derived from settled redemptions
plus reservations whose hold has not expired, so an in-flight checkout is already counted.
discount_value is a decimal string — parse it as a decimal, not a float. currency is an ISO
code, and null on a percentage coupon.
How it fails
RESOURCE_NOT_FOUNDunknown coupon_id, a coupon on another team's project, one outside the
AUTHENTICATION_REQUIREDno authenticated user on the request.
TOKEN_MISSING_ABILITYtoken lacks project-coupon:view.
How is this guide?
Last updated on