create_coupon
Create a coupon for Checkout Page.
Use this when a merchant wants a discount code that customers can enter on eligible pages.
Where and what a coupon discounts:
ruleslists where the coupon works and what it discounts:[{ pageId, appliesTo, priceIds, ticketTypeIds, bumpProductIds }]. Omit it (or send an empty list) for a coupon that discounts the whole order on every checkout page and event.A coupon works on any page a rule names. Several rules on one page are combined with OR. An event can't mix
ticketsandticketsAndAddOnsrules.Checkout pages:
wholeOrder(the main product at any price and every order bump),prices(applies when the customer buys one ofpriceIds, discounting that price only),pricesAndBumps(applies only when the customer buys one ofpriceIdsAND one ofbumpProductIds, discounting both).Events:
wholeOrder(every ticket and add-on),tickets(applies when the customer buys one ofticketTypeIds, discounting those tickets only),ticketsAndAddOns(applies only when the customer buys one ofticketTypeIdsAND one ofbumpProductIds, discounting both).priceIdsare theids of the page's main product'sprices(fromget_product), not Stripe price ids.bumpProductIdsare products of order bumps or add-ons on that page. LeavepriceIds,ticketTypeIdsorbumpProductIdsempty for every price, ticket type, bump or add-on on the page, including ones added later. A page with no bumps or add-ons cannot usepricesAndBumpsorticketsAndAddOns.When no rule matches the order, the code is accepted but discounts nothing. Setup fees and ticket fees join with
appliesToSetupFeeandappliesToTicketFees.pageIdsandticketTypeIdsare deprecated: userules. They are still accepted withoutrules(each page whole order, or tickets on an event with picked ticket types).
How discount types work:
amountOffis a fixed amount discount. It requirescurrency. It comes off once per order, shared equally across the lines the coupon applies to (on a subscription it stays on the main recurring line).percentOffis a percentage discount applied to the eligible checkout total.Set exactly one of
amountOfforpercentOff, never both.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"label": "<label>",
"code": "<code>",
"duration": "<duration>"
},
"name": "create_coupon"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | The coupon code a customer enters. | |
| label | Yes | Internal name for the coupon. | |
| rules | No | Where the coupon works and what it discounts, one rule per page. A coupon works on a page when any of its rules names that page, and on each page the rules are combined with OR (an event cannot mix `tickets` and `ticketsAndAddOns` rules). Omit `rules` (and `pageIds`), or send an empty list, for a coupon that discounts the whole order on every checkout page and event. | |
| pageIds | No | Deprecated: use `rules`. The checkout pages and events this coupon can be used on, each discounting the whole order. Accepted only without `rules`. In responses, the pages named by `rules`. | |
| currency | No | Three-letter ISO code for the currency of the amountOff parameter. Required when `amountOff` is set, and not allowed when `percentOff` is set. | |
| duration | Yes | How long the discount lasts: `once` applies to the first eligible payment, `repeating` applies for a fixed number of months, and `forever` applies until canceled or expired. | |
| redeemBy | No | The ISO datetime that this coupon must be used before. | |
| amountOff | No | A positive integer representing the amount to subtract from an invoice total, in the smallest currency unit of `currency` (for example `500` USD is $5.00 and `500` JPY is ¥500). Required if `percentOff` is not passed. | |
| percentOff | No | A positive float larger than 0, and smaller or equal to 100, that represents the discount the coupon will apply (required if `amountOff` is not passed). | |
| ticketTypeIds | No | Deprecated: use `rules`. Ticket types of events in `pageIds`: on such an event the coupon discounts only those tickets. Accepted only without `rules`. In responses, every ticket type named by `rules`. | |
| maxRedemptions | No | The total number of times this coupon can be redeemed across all customers. Doesn't limit a single customer from redeeming multiple times. Omit for unlimited redemptions. | |
| durationInMonths | No | A positive integer representing the number of months the coupon applies for. Required when `duration === repeating`, and not allowed when `duration` is `once` or `forever`. | |
| appliesToSetupFee | No | When enabled, applies this coupon discount to the setup fee. | |
| appliesToTicketFees | No | When enabled, applies this coupon discount to ticket-level fees on event pages as well as the ticket prices. Defaults to false, which leaves ticket fees undiscounted. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes |