get_coupon

Fetch one coupon by UUID — discount, limits, redemption tally, plan restriction and whether it is redeemable right now.

Purpose

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.

Required ability

project-coupon:view

Input schema

{
  "type": "object",
  "required": ["coupon_id"],
  "properties": {
    "coupon_id": {
      "type": "string",
      "description": "UUID of the coupon to fetch."
    }
  }
}

Output shape

{
  "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.

Example prompts

"Show me coupon 4b9d3e08-a1f6-4275-9c83-7e01d6a2f594."

"How many uses are left on the BLACKFRIDAY code, and is it live right now?"

"Which plans does this coupon apply to?"

Failure modes

RESOURCE_NOT_FOUND — unknown coupon_id, a coupon on another team's project, one outside the token's scope:project: allow-list, or a coupon that has been deleted.
AUTHENTICATION_REQUIRED — no authenticated user on the request.
TOKEN_MISSING_ABILITY — token lacks project-coupon:view.

list_coupons — find the id.
update_coupon
activate_coupon / deactivate_coupon
delete_coupon
Coupons API — the REST equivalent.
Coupon Codes — the feature walkthrough.