create_coupon
Create a coupon code any number of subscribers can redeem for money off. Returns the coupon immediately — no job to poll.
Author a coupon code: one string many subscribers redeem for a discount at checkout. Distinct from an access code, which is one code for one person and grants access outright without a payment.
Synchronous — the coupon is returned in the response, and
coupon.created emits once.
Discounts apply to the first payment only. Renewals charge list price, so an agent should not describe a coupon as changing a subscriber's ongoing rate.
Requires the Coupons Addon or a Growth plan. Without it the call fails
with TEAM_TIER_REQUIRED rather than creating anything. Entitlement is
checked again when a subscriber redeems, so a coupon created today stops
applying if the addon later lapses.
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.
Fires one event
Delivered to every endpoint subscribed to it once the change is made.
Annotations
A client that honours annotations asks a person before running it. It reaches beyond Subscriby: a connector, a provider or a member.
Arguments
project_id*stringUUID of the project the code belongs to.
code*stringThe code subscribers type at checkout. Letters, numbers and dashes only, 3 to 64 characters. Stored uppercase.
namestringoptionalInternal label to tell your codes apart, e.g. "Black Friday 2026". Defaults to the code itself.
discount_type*stringEither "percentage" (works on plans in any currency) or "fixed" (requires currency_id, and only applies to plans priced in it).
discount_value*numberFor percentage, 1..99. For fixed, an amount greater than zero in the chosen currency.
currency_idstringoptionalCurrency UUID. Required when discount_type is "fixed", ignored otherwise.
max_redemptionsintegeroptionalTotal uses allowed across everyone. Omit for unlimited.
1max_redemptions_per_userintegeroptionalHow many times one subscriber may use the code. Defaults to 1.
1minimum_amountnumberoptionalOnly apply the code when the plan costs at least this much, in the plan's own currency.
starts_atstringoptionalISO 8601 instant the code becomes usable. Omit to start immediately.
expires_atstringoptionalISO 8601 instant the code stops working. Omit for no end date.
plan_idsstring[]optionalPlan UUIDs to restrict the code to. Leave empty or omit to cover every plan in the project, including ones added later.
activebooleanoptionalWhether the code is usable right away. Defaults to true.
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, "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" }}code comes back uppercase regardless of what was sent. discount_value is a decimal string —
parse it as a decimal, not a float.
How it fails
TEAM_TIER_REQUIREDthe creator has neither the Coupons Addon nor a Growth plan.
VALIDATION_FAILEDcode already taken in this project (compared uppercase), code outside 3–64
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:create.
How is this guide?
Last updated on