Skip to main content
Glama

Checkout Page

by com.checkoutpage
OverviewDiscussionsAdmin

create_booking

Destructive

Create a real event booking on an existing event, without collecting card payment.

This writes live data and has customer-visible side effects - it is not a dry run or a preview. Tickets are issued, a confirmation email with the ticket PDF is sent to the customer, live-mode bookings decrement the ticket type's remaining capacity (test-mode bookings do not), the booking.paid webhook fires, and an invoice may be generated. There is no undo through this API: cancellations, refunds and ticket transfers must be done in the Checkout Page dashboard. Confirm the event, the ticket quantities and the customer's email with the merchant before calling it.

Not idempotent - never retry blindly. Every call creates a new booking, so calling again after a timeout or an unclear error can issue duplicate tickets and send a second confirmation email. If the outcome of a call is uncertain, check list_bookings (search by the customer's email) before trying again.

No card payment is collected. There are two booking strategies, and exactly one of them must be supplied:

  • paymentOption.manualType records the booking as unpaid with the full amount as its balance due, settled outside checkout by invoice (invoice) or on arrival (cash_on_delivery); a free booking simply has nothing due. Use it for box-office and phone bookings, invoiced corporate registrations, and migrating bookings in.

  • complimentary: true records the booking as paid with amount, amountPaid and amountDue of 0 and isComplimentary: true. The ticket lines keep their face value and a matching complimentaryDiscountAmount brings the total to 0, so the forgone revenue stays visible on the booking and its invoice. Use it for comped guests, speakers, staff and press. No coupon can be applied.

Neither strategy takes a card payment: that belongs on the event's own checkout.

The storefront guards still apply, exactly as they would for a buyer checking out:

  • 409 — the ticket type or its ticket group is sold out, or the requested quantity exceeds remaining capacity.

  • 409 - tickets are not on sale: the sale window has not opened or has closed, or the ticket type or its ticket group is disabled. A disabled ticket cannot be booked by any strategy, complimentary included.

  • 403 — the event's registration limit has been reached.

  • 400 — a required field is missing, a required address sub-field is missing, or the email value is not a valid address.

  • 400 — the seller account is not connected to Stripe.

  • 429 - the store has reached its daily limit on added bookings.

  • 400 - both paymentOption and complimentary: true were supplied, or neither was. Exactly one is required.

  • 400 - a couponId was supplied on a complimentary booking. A comp is already at zero, so no coupon can be applied.

Example uses:

  • "Comp two VIP tickets for jane@example.com on the Summer Gala" → complimentary: true

  • "Register Acme Corp for 10 standard tickets to the conference and invoice them" → paymentOption: { manualType: 'invoice' }

  • "Add a walk-in booking for the Tuesday workshop, paying cash on arrival" → paymentOption: { manualType: 'cash_on_delivery' }

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
fieldsYesValues for the event's fields. Must include a value for the event's email field - the booking's customer is created from it.
eventIdYesThe ID of the event to book onto.
ticketsYesTicket types to book, keyed by ticket type ID with the quantity as the value. Use the event to discover ticket type IDs. A disabled ticket type, or one in a disabled ticket group, cannot be booked.
couponIdNoA coupon to apply to the booking.
complimentaryNoIssue the tickets at no charge. The booking is recorded as `paid` with `amount`, `amountPaid` and `amountDue` of 0, `isComplimentary: true`, and the ticket lines at their face value with a matching complimentary discount. Mutually exclusive with `paymentOption` and `couponId`.
paymentOptionNoHow a manually settled booking is paid for. This endpoint never collects card payment: the booking is recorded as unpaid with the amount as its balance due - for a free booking that balance is zero. Settlement happens outside checkout. Omit it and pass `complimentary: true` instead to issue the tickets at no charge.
queryParametersNoAttribution or tracking parameters to record against the booking, mirroring the query string a storefront checkout captures from its page link. Stored on the booking and included in exports; not used in pricing.
ticketPwywAmountsNoChosen amounts for pay-what-you-want ticket types, keyed by ticket type ID, in the smallest currency unit. Required for any pay-what-you-want ticket type included in `tickets`.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
dataYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only flag destructive/write; the description goes far beyond, disclosing the concrete side effects that make it destructive (tickets issued, PDF confirmation email sent, capacity decremented in live mode, booking.paid webhook fires, invoice may be generated), the absence of undo through this API, and the non-idempotency warning against blind retries. These are exactly the traits annotations cannot convey.

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?

Bold front-loaded warnings and bulleted strategy/error blocks make it scannable despite being long. It is dense but almost every line earns its place; the nine-point error list is arguably more than strictly needed, slightly diluting structure.

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?

A destructive, non-idempotent mutation tool with 8 params and an output schema present; the description covers side effects, no-undo path, exclusivity rules, capacity/sold-out guards with specific status codes, and worked examples. An agent has everything needed to call it safely and interpret failures.

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 baseline is 3, but the description adds real semantic value the schema does not: it explains the exclusivity constraint between paymentOption and complimentary, the meaning of each manualType ('unpaid with full amount as balance due, settled outside checkout'), and that complimentary records paid with isComplimentary true. It omits notes on couponId incompatibility with comp (covered in errors) and fields/ticketPwywAmounts semantics, keeping it from a 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?

States a specific verb+resource ('Create a real event booking on an existing event') and crucially distinguishes scope from siblings by declaring it does NOT collect card payment, which separates it from create_checkout_page. An agent can route between this and checkout instantly.

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?

Explicitly enumerates when to use each of two mutually exclusive strategies (paymentOption.manualType vs complimentary: true) with named scenarios (box-office, phone, invoiced corporate, migrations vs comped guests, speakers, staff, press). It also routes recovery: 'If the outcome of a call is uncertain, check list_bookings before trying again.'

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