Skip to main content
Glama
Sign In

Checkout Page

by com.checkoutpage
OverviewDiscussionsAdmin

list_coupons

Read-only

Retrieve a paginated list of discount coupons on your Checkout Page account. This is the only way to discover a coupon ID — take the id from here to use update_coupon.

search is a case-insensitive contains match on the coupon's label and code, so it answers "is there already a coupon for X?" before you create a duplicate with create_coupon.

Reading a coupon: the discount is either percentOff (a percentage) or amountOff (a flat amount in the smallest currency unit, paired with currency) — never both. duration is once, repeating (for durationInMonths), or forever. timesRedeemed counts redemptions so far, against maxRedemptions when one is set.

Whether a coupon actually works right now depends on several fields together, and there is no single "active" flag: deleted: true means soft deleted and dead; redeemBy in the past means expired; timesRedeemed >= maxRedemptions means exhausted. Check all three before telling a merchant a coupon is live. Soft-deleted coupons are returned by this tool — they are not filtered out.

Scoping: rules lists where the coupon works and what it discounts, one { pageId, appliesTo, priceIds, ticketTypeIds, bumpProductIds } per rule; with none it discounts the whole order on every checkout page and event. appliesTo is wholeOrder, prices (only the picked prices), pricesAndBumps (only when a picked price AND a picked bump are bought, discounting both), tickets (only the picked tickets) or ticketsAndAddOns (only when a picked ticket AND a picked add-on are bought). An empty priceIds, ticketTypeIds or bumpProductIds means every price, ticket type, bump or add-on on the page. Rules on the same page are combined with OR. pageIds and ticketTypeIds are deprecated and derived from the rules. These are IDs only: this tool does not resolve them to page, event, product or price names.

No filters beyond search. There is no way to filter by deleted, expiry, redemption count, or scope server-side. Page through and inspect those fields.

Coupons are returned sorted newest-first. Use cursor-based pagination (starting_after / ending_before) to page through large result sets. starting_after and ending_before cannot be used simultaneously. Max limit is 100, default is 10.

This tool is read-only. Use create_coupon to add one and update_coupon to change or soft delete one. A coupon's discount (code, amountOff, percentOff, currency, duration) can never be changed after creation.

Input Schema

NameRequiredDescriptionDefault
limitNoNumber of records per page (integer, max 100, default 10).
searchNoCase-insensitive contains match against the coupon's label and code. Searching '10off' matches the code `10OFF`; searching 'summer' matches the label 'Summer sale'. There is no filter for redemption count, expiry, or deleted status — page through and inspect those fields instead.
ending_beforeNoCursor-based pagination. Pass a record `id` to return results before it. Cannot be used with `starting_after`.
starting_afterNoCursor-based pagination. Pass a record `id` to return results after it. Cannot be used with `ending_before`.

Output Schema

NameRequiredDescriptionDefault
dataYes
totalYesTotal number of records matching the query across all pages.
has_moreYesWhether more records exist beyond the current page.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changed
    • addedOutput schema / properties / data / items / properties / pageIds / deprecated
      Added value: +true
    • addedOutput schema / properties / data / items / 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 / items / 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 / items / properties / ticketTypeIds / deprecated
      Added value: +true
    • changedOutput schema / properties / data / items / 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`."
  2. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Beyond the readOnlyHint/destructiveHint annotations, it discloses that soft-deleted coupons are returned, that there is no single 'active' flag (deleted/redeemBy/maxRedemptions must be combined), that results are newest-first, that discount fields are immutable after creation, and that there are no server-side filters beyond search. This is substantially more than the annotations carry.

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?

The description is front-loaded and well-sectioned with bold headers, and nearly every sentence is substantive. However, the 'Reading a coupon' and 'Scoping' sections explain return-value fields in depth even though an output schema exists, which is more length than the tool strictly requires. Dense and organized, but longer than necessary.

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?

For a 4-parameter, read-only list tool with full schema coverage and an output schema, the description covers purpose, alternatives, filtering limits, pagination, and the semantics an agent needs to interpret results correctly. Nothing material is left to inference.

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 adds value by explaining that `search` is a contains match on both label and code and is meant for duplicate detection, and by establishing newest-first ordering that gives the cursor parameters meaning. Some of the parameter detail (mutual exclusivity, limit max) repeats the schema, capping it below 5.

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?

The first sentence names a specific verb (Retrieve) and resource (paginated list of discount coupons) and scopes it to the Checkout Page account. It explicitly differentiates from siblings by naming create_coupon and update_coupon and describing its role relative to them. An agent can identify this tool 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?

It states the tool is 'the only way to discover a coupon ID' and routes the agent to update_coupon for changes and create_coupon for additions. The `search` guidance ties a concrete when-to-use case (duplicate check before create) to the parameter, and the 'No filters beyond search' section clarifies the limits of alternatives. Explicit when/when-not coverage.

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