Skip to main content
Glama
Sign In

Checkout Page

by com.checkoutpage
OverviewDiscussionsAdmin

update_coupon

Destructive

Update an existing coupon in your Checkout Page account.

Only the fields you supply are changed; omitted fields are left as-is. Send null for maxRedemptions or redeemBy to remove that limit. rules is replaced wholesale rather than merged - send every rule you want, or an empty array to make the coupon work everywhere.

What cannot be changed: the discount itself. code, amountOff, percentOff, currency, duration, and durationInMonths are fixed once a coupon exists, because they are mirrored into Stripe. To change a discount, soft delete this coupon (deleted: true) and create a replacement with create_coupon.

Coupons created before 2025-10-04 cannot be updated at all — their redemption limits are synced with Stripe and the API returns a 400 saying so.

How scoping works:

  • rules lists 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 tickets and ticketsAndAddOns rules.

  • Checkout pages: wholeOrder (the main product at any price and every order bump), prices (applies when the customer buys one of priceIds, discounting that price only), pricesAndBumps (applies only when the customer buys one of priceIds AND one of bumpProductIds, discounting both).

  • Events: wholeOrder (every ticket and add-on), tickets (applies when the customer buys one of ticketTypeIds, discounting those tickets only), ticketsAndAddOns (applies only when the customer buys one of ticketTypeIds AND one of bumpProductIds, discounting both).

  • priceIds are the ids of the page's main product's prices (from get_product), not Stripe price ids. bumpProductIds are products of order bumps or add-ons on that page. Leave priceIds, ticketTypeIds or bumpProductIds empty 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 use pricesAndBumps or ticketsAndAddOns.

  • When no rule matches the order, the code is accepted but discounts nothing. Setup fees and ticket fees join with appliesToSetupFee and appliesToTicketFees.

  • pageIds and ticketTypeIds are deprecated: use rules. They are still accepted without rules (each page whole order, or tickets on an event with picked ticket types).

  • Without rules, pageIds replaces the rules with whole-order rules for those pages (an empty list makes the coupon work everywhere), and ticketTypeIds sent without pageIds must belong to the coupon's pages. A coupon whose rules go beyond one wholeOrder rule, or one tickets rule with picked ticketTypeIds, per page refuses pageIds and ticketTypeIds with a 400: send rules instead.

This tool modifies live data. Every change applies to live checkouts at once. There is no undo, because the previous values are not kept. Setting deleted: true stops the coupon working at checkout immediately.

Input Schema

NameRequiredDescriptionDefault
labelNoInternal name for the coupon.
rulesNoWhere 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. Replaces every stored rule; an empty list makes the coupon work everywhere.
deletedNoSet true to soft delete the coupon. It stops working at checkout but its data and redemption history are retained.
pageIdsNoDeprecated: 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`. Replaces the stored rules with whole-order rules for these pages; an empty array makes the coupon work everywhere. Refused with a 400 when the coupon's rules go beyond one `wholeOrder` rule, or one `tickets` rule with picked `ticketTypeIds`, per page: send `rules` instead.
couponIdYesThe ID of the coupon to update. Use `list_coupons` first if you need to discover the coupon ID by code or label.
redeemByNoThe ISO datetime that this coupon must be used before. Send `null` to remove the expiry.
ticketTypeIdsNoDeprecated: 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`. Without `pageIds`, checked against the pages already on the coupon. Refused with a 400 when the coupon's rules go beyond one `wholeOrder` rule, or one `tickets` rule with picked `ticketTypeIds`, per page.
maxRedemptionsNoThe total number of times this coupon can be redeemed across all customers. Doesn't limit a single customer from redeeming multiple times. Send `null` to remove the limit.

Output Schema

NameRequiredDescriptionDefault
dataYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • changedInput schema / properties / pageIds / description
      Previous value: -"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`. Replaces the stored rules with whole-order rules for these pages; an empty array makes the coupon work everywhere. Refused with a 400 when the coupon's rules go beyond one `wholeOrder` or `tickets` rule per page: send `rules` instead."New value: +"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`. Replaces the stored rules with whole-order rules for these pages; an empty array makes the coupon work everywhere. Refused with a 400 when the coupon's rules go beyond one `wholeOrder` rule, or one `tickets` rule with picked `ticketTypeIds`, per page: send `rules` instead."
    • changedInput schema / properties / ticketTypeIds / description
      Previous value: -"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`. Without `pageIds`, checked against the pages already on the coupon. Refused with a 400 when the coupon's rules go beyond one `wholeOrder` or `tickets` rule per page."New value: +"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`. Without `pageIds`, checked against the pages already on the coupon. Refused with a 400 when the coupon's rules go beyond one `wholeOrder` rule, or one `tickets` rule with picked `ticketTypeIds`, per page."
  2. Changed10 schema fields changed
    • addedInput schema / properties / pageIds / deprecated
      Added value: +true
    • changedInput schema / properties / pageIds / description
      Previous value: -"The pages this coupon can be used on. Replaces the existing list. An empty array clears it, making the coupon valid everywhere."New value: +"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`. Replaces the stored rules with whole-order rules for these pages; an empty array makes the coupon work everywhere. Refused with a 400 when the coupon's rules go beyond one `wholeOrder` or `tickets` rule per page: send `rules` instead."
    • addedInput schema / properties / rules
      Added value: +{
+  "description": "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. Replaces every stored rule; an empty list makes the coupon work everywhere.",
+  "example": [
+    {
+      "appliesTo": "wholeOrder",
+      "pageId": "67ee075004de439ab0b675b6"
+    }
+  ],
+  "items": {
+    "properties": {
+      "appliesTo": {
+        "description": "What the coupon discounts on the page. Checkout pages: `wholeOrder` (the main product at any price and every order bump), `prices` (applies when the customer buys one of `priceIds`, discounting that price only), `pricesAndBumps` (applies only when the customer buys one of `priceIds` and one of `bumpProductIds`, discounting both). Events: `wholeOrder` (every ticket and add-on), `tickets` (applies when the customer buys one of `ticketTypeIds`, discounting those tickets only), `ticketsAndAddOns` (applies only when the customer buys one of `ticketTypeIds` and one of `bumpProductIds`, discounting both). Setup fees and ticket fees follow `appliesToSetupFee` and `appliesToTicketFees`.",
+        "enum": [
+          "wholeOrder",
+          "prices",
+          "pricesAndBumps",
+          "tickets",
+          "ticketsAndAddOns"
+        ],
+        "example": "prices",
+        "type": "string"
+      },
+      "bumpProductIds": {
+        "description": "Products of order bumps (checkout pages) or add-ons (events) on the page, only for `pricesAndBumps` and `ticketsAndAddOns`. An empty list or no list means every bump or add-on on the page, including ones added later; the coupon still needs one of them bought.",
+        "items": {
+          "pattern": "^[0-9a-fA-F]{24}$",
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "pageId": {
+        "description": "The checkout page or event this rule applies to.",
+        "pattern": "^[0-9a-fA-F]{24}$",
+        "type": "string"
+      },
+      "priceIds": {
+        "description": "Prices of the page's main product, only for `prices` and `pricesAndBumps`. An empty list or no list means every price of the main product, including prices added later. These are the `id`s of a product's `prices`, not Stripe price ids.",
+        "example": [
+          "67fcbdac6a91c25ef2d3534a"
+        ],
+        "items": {
+          "pattern": "^[0-9a-fA-F]{24}$",
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "ticketTypeIds": {
+        "description": "Ticket types of the event, only for `tickets` and `ticketsAndAddOns`. An empty list or no list means every ticket type of the event, including ticket types added later.",
+        "items": {
+          "pattern": "^[0-9a-fA-F]{24}$",
+          "type": "string"
+        },
+        "type": "array"
+      }
+    },
+    "required": [
+      "pageId",
+      "appliesTo"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}
    • addedInput schema / properties / ticketTypeIds / deprecated
      Added value: +true
    • changedInput schema / properties / ticketTypeIds / description
      Previous value: -"The ticket types this coupon can be used with. Replaces the existing list; an empty array clears it. Every ID must belong to a page in `pageIds` — or, when `pageIds` is omitted, to the pages already on the coupon."New value: +"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`. Without `pageIds`, checked against the pages already on the coupon. Refused with a 400 when the coupon's rules go beyond one `wholeOrder` or `tickets` rule per page."
    • addedOutput schema / properties / data / properties / pageIds / deprecated
      Added value: +true
    • addedOutput schema / properties / data / properties / pageIds / description
      Added value: +"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`."
    • addedOutput schema / properties / data / properties / rules
      Added value: +{
+  "description": "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.",
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "appliesTo": {
+        "description": "What the coupon discounts on the page. Checkout pages: `wholeOrder` (the main product at any price and every order bump), `prices` (applies when the customer buys one of `priceIds`, discounting that price only), `pricesAndBumps` (applies only when the customer buys one of `priceIds` and one of `bumpProductIds`, discounting both). Events: `wholeOrder` (every ticket and add-on), `tickets` (applies when the customer buys one of `ticketTypeIds`, discounting those tickets only), `ticketsAndAddOns` (applies only when the customer buys one of `ticketTypeIds` and one of `bumpProductIds`, discounting both). Setup fees and ticket fees follow `appliesToSetupFee` and `appliesToTicketFees`.",
+        "enum": [
+          "wholeOrder",
+          "prices",
+          "pricesAndBumps",
+          "tickets",
+          "ticketsAndAddOns"
+        ],
+        "example": "prices",
+        "type": "string"
+      },
+      "bumpProductIds": {
+        "description": "Products of order bumps (checkout pages) or add-ons (events) on the page, only for `pricesAndBumps` and `ticketsAndAddOns`. An empty list or no list means every bump or add-on on the page, including ones added later; the coupon still needs one of them bought.",
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "pageId": {
+        "description": "The checkout page or event this rule applies to.",
+        "type": "string"
+      },
+      "priceIds": {
+        "description": "Prices of the page's main product, only for `prices` and `pricesAndBumps`. An empty list or no list means every price of the main product, including prices added later. These are the `id`s of a product's `prices`, not Stripe price ids.",
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "ticketTypeIds": {
+        "description": "Ticket types of the event, only for `tickets` and `ticketsAndAddOns`. An empty list or no list means every ticket type of the event, including ticket types added later.",
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      }
+    },
+    "required": [
+      "pageId",
+      "appliesTo",
+      "priceIds",
+      "ticketTypeIds",
+      "bumpProductIds"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}
    • addedOutput schema / properties / data / properties / ticketTypeIds / deprecated
      Added value: +true
    • changedOutput schema / properties / data / properties / ticketTypeIds / description
      Previous value: -"List of ticket type IDs that this coupon can be used with."New value: +"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`."
  3. First observed

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true, but the description adds the specifics that matter: every change hits live checkouts immediately, there is no undo because previous values are not retained, `deleted: true` stops redemption instantly while retaining history, and `rules` is replaced wholesale rather than merged. Those are exactly the traits an agent needs before invoking a destructive mutation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the mutation contract and immutability, then organized under bold headers (what cannot be changed, how scoping works, live-data warning). It runs long and the scoping bullets restate material already present in the `appliesTo` schema description, which is the main cost.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given a destructive, 8-parameter mutation with nested rule objects, the description covers everything an agent needs: partial-update contract, null semantics, immutable fields, legacy-coupon failure mode, deprecated-parameter interaction, and irreversibility. Return values are covered by the output schema, so nothing material is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description still adds value by explaining the replace-not-merge contract for `rules`, the empty-list meaning, OR combination across rules on one page, the prohibition on mixing `tickets` and `ticketsAndAddOns`, and how `pageIds` rewrites stored rules. It does overlap substantially with the schema's own rule/appliesTo descriptions, so it is not entirely additive.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Update an existing coupon in your Checkout Page account") and immediately distinguishes itself from create_coupon by naming the exact fields that are immutable and directing discount changes to soft-delete + create_coupon. An agent can place this tool relative to its siblings without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use rules: partial update semantics for supplied fields, use `null` to remove limits, replace the coupon instead when the discount must change, and legacy coupons created before 2025-10-04 cannot be updated (400). It also tells the agent to prefer `rules` over the deprecated `pageIds`/`ticketTypeIds` and explains the 400 refusal condition that forces that choice.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Checkout Page toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources