--- title: "Ticket Fairy Agent Checkout | ACP and UCP Ticket Sales" description: "Register your shopping agent, find events, hold tickets in a checkout and send the buyer to pay. Agentic Commerce Protocol and Universal Commerce Protocol endpoints." canonical: "https://www.ticketfairy.com/developers/agent-checkout" --- Ticket Fairy developer documentation # Let a shopping agent buy tickets Your shopping agent finds an event, holds the buyer's tickets, takes payment and looks after the order afterwards. Ticket Fairy speaks the Agentic Commerce Protocol (ACP) and the Universal Commerce Protocol (UCP), and the same sale limits, prices and fees apply as on the event page. [Register your agent](#register) [Read the UCP profile](https://www.ticketfairy.com/.well-known/ucp) No approval needed. An ACP agent gets its own buyer key at once, and a UCP agent is recognized from its signed profile. Register an ACP agent ``` $ curl -X POST 'https://www.ticketfairy.com/api/v1/agentic/agents/register' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: 9b2f6c1e-7a40-4d0b-8a77-3c2e5d1f9a64' \ -d '{"client_name": "Acme Shopping Assistant", "client_uri": "https://assistant.example.com"}' ``` ## How a sale works 1. ### Find the event Search with UCP catalog search, the [events MCP server](https://www.ticketfairy.com/developers/ai-agents#mcp) or the [event API](https://www.ticketfairy.com/developers#public-api). 2. ### Read the tickets on sale Ticket selection lists the ticket types the buyer can choose now, with prices and the most they can buy. 3. ### Hold the tickets Create a checkout with the tickets the buyer chose. Change it as the buyer decides, then show them the total. 4. ### The buyer pays Complete the checkout with the buyer's payment token or AP2 mandate. For a payment method your agent cannot use, send the buyer to its `continue_url`. 5. ### The buyer gets their tickets The buyer receives the tickets by email, as from any Ticket Fairy checkout. Your agent gets the order, its webhooks and later changes, such as a refund or a transfer. ## Identify your agent How your agent identifies itself depends on the protocol it speaks. ### ACP: register for a buyer key `POST https://www.ticketfairy.com/api/v1/agentic/agents/register` takes OAuth 2.0 dynamic client metadata (RFC 7591) and an `Idempotency-Key` header. - `client_name` is required, from 2 to 80 characters. Buyers can see it. - `client_uri` is your agent's HTTPS website. - `redirect_uris` lists up to 10 HTTPS addresses a buyer may return to after paying in the browser. - `jwks` holds up to 10 public EC P-256 or Ed25519 keys for your agent's signatures. | Status | What it means | | --- | --- | | 201 | Registered. The answer has your client\_id and your buyer key in access\_token, with the date it expires. The key is shown once. | | 400 | The Idempotency-Key header is missing, or the metadata is not valid. error\_description says what to change. | | 409 | You already used this Idempotency-Key. registration\_already\_completed means that registration finished: the key is never sent again, so register again with a new Idempotency-Key if you lost it. idempotency\_key\_reused means you sent different metadata with the same key. | | 429 | Too many registration requests from your network in the last hour, or registration is closed for today. Wait, then try again. | The buyer key lasts 365 days. Send it as `Authorization: Bearer` on each ACP checkout request. To stop using it, send it to `POST https://www.ticketfairy.com/api/v1/agentic/agents/revoke`. Store it like a password. ### UCP: sign each request with your profile's key A UCP agent has no registration step and no buyer key. Publish your public signing keys in the root `keys` of your own UCP profile, then sign every request with HTTP Message Signatures (RFC 9421): - Send `UCP-Agent: profile="https://your-agent.example/.well-known/ucp"`, with the address of your profile. - Send `Signature-Input` and `Signature`, signed with a key from that profile. - Cover the method, host, path and `UCP-Agent`, the query when there is one, and `Content-Digest` and `Content-Type` when there is a body. Ticket Fairy reads your profile on the first signed request and recognizes your agent from then on. To retire a key, remove it from your profile. Ticket Fairy reads the profile again on a later request that does not complete a checkout, at most once every 15 minutes, and then refuses requests signed with the removed key. Until that check succeeds, the key keeps working, including for completing a checkout. If a key is exposed, also email [support@theticketfairy.com](mailto:support@theticketfairy.com) so that Ticket Fairy can suspend your agent at once. ## Endpoints Use the protocol your agent already speaks. The UCP base address is `https://www.ticketfairy.com/api/v1/agentic/ucp` and the ACP base address is `https://www.ticketfairy.com/api/v1/agentic/acp`. | Step | UCP | ACP | | --- | --- | --- | | Find events | `POST /api/v1/agentic/ucp/catalog/search` | `The events MCP server or the event API` | | Read the tickets on sale | `POST /api/v1/agentic/ucp/ticket-selection` | `POST /api/v1/agentic/acp/ticket-selection` | | Hold tickets in a checkout | `POST /api/v1/agentic/ucp/checkout-sessions` | `POST /api/v1/agentic/acp/checkout_sessions` | | Read a checkout | `GET .../checkout-sessions/{id}` | `GET .../checkout_sessions/{id}` | | Change quantities, buyer details or a promo code | `PUT .../checkout-sessions/{id}` | `POST .../checkout_sessions/{id}` | | Pay | `POST .../checkout-sessions/{id}/complete` | `POST .../checkout_sessions/{id}/complete` | | Cancel and release the tickets | `POST .../checkout-sessions/{id}/cancel` | `POST .../checkout_sessions/{id}/cancel` | | Read the order | `GET /api/v1/agentic/ucp/orders/{id}` | `The completed checkout includes the order` | The [UCP profile](https://www.ticketfairy.com/.well-known/ucp) and the [ACP profile](https://www.ticketfairy.com/.well-known/acp.json) list the protocol versions, capabilities and payment handlers this site supports. Read them when your agent starts. Send an `Idempotency-Key` with every request that creates, changes, completes or cancels a checkout, so that a retry after a network error does not act twice. A UCP request includes it in the signature. ### Search the UCP catalog The catalog search does not need a signature, but it needs two headers. Send a `Request-Id` that is unique for each request, and a `UCP-Agent` header that names your profile as `profile="https://your-domain/.well-known/ucp"`. Without both, the answer is 400. The body takes a `query`, an optional `pagination` with a `limit` of 1 to 25 (10 if you leave it out) and the `cursor` from the previous page, and an optional `context` with a `currency`. Filters are not supported yet, so send none. Search the UCP catalog ``` $ curl -X POST 'https://www.ticketfairy.com/api/v1/agentic/ucp/catalog/search' \ -H 'Content-Type: application/json' \ -H 'Request-Id: 4c1d8e2a-6b7f-4f3e-9a51-2d0c7b8e6f13' \ -H 'UCP-Agent: profile="https://assistant.example.com/.well-known/ucp"' \ -d '{"query": "techno london", "pagination": {"limit": 10}}' ``` ## Payment ### Payment inside your agent Each checkout lists the payment handlers it accepts in its capabilities. Complete the checkout with the buyer's payment token or mandate from one of them. Ticket Fairy never takes a card number from an agent. | The buyer pays with | Your agent sends | Protocol | | --- | --- | --- | | Card, including Mastercard Agent Pay and Visa Intelligent Commerce | Stripe Shared Payment Token | ACP and UCP | | Link | Stripe Shared Payment Token | ACP and UCP | | Affirm and Klarna, where the event page offers them | Stripe Shared Payment Token | ACP and UCP | | A purchase the buyer approved in advance | AP2 direct or autonomous mandate | UCP | | Any other method the event accepts | The buyer pays at the continue\_url | ACP and UCP | While the payment or the tickets are still being processed, the checkout says so. Read it again after the number of seconds in `Retry-After`. ### When the bank asks the buyer to confirm An ACP checkout that negotiates the `3ds` intervention, and a UCP checkout that negotiates the payment authentication extension, return the bank's challenge to your agent. Show it to the buyer, then complete the checkout. A checkout that negotiates neither gives a `continue_url`, where the buyer confirms in their browser. ### Purchases the buyer approved in advance With AP2, the buyer can approve one checkout (a direct mandate) or give your agent limits to buy within later, such as an event, a ticket type, a most-per-ticket price and a deadline (an autonomous mandate). Ticket Fairy checks every limit before it charges, refuses a purchase outside them, and returns a signed checkout receipt and payment receipt. ### Payment in the browser When the buyer wants a payment method your agent cannot use, the checkout status is `requires_escalation` and it has a `continue_url`. Give that link to the buyer. It opens the Ticket Fairy checkout with the same tickets held. The buyer pays there with any payment method the event accepts. ## Seats, attendees and busy on-sales Each feature is a capability in the checkout. Your agent uses it when the checkout lists it. - **Assigned seats.** The checkout gives a seat map link. The buyer picks seats there, and your checkout keeps the same reservation. - **Attendee details.** The checkout asks for each attendee's name, the organizer's questions, a photo where the event needs one, and a shipping address for physical add-ons. - **Access codes.** Send an event password, an invitation link or a limited-purchase code to unlock the tickets it opens. - **Add-ons, payment plans and waiting-list offers** appear in ticket selection when the event has them. - **ID and age checks.** The checkout says when the buyer must prove their age or identity. - **Waiting room.** For a scarce on-sale, the buyer joins the same queue as the event page, with one place per buyer, and your agent learns when it is their turn. - **Purchase limits.** The event's limit applies to the buyer across every agent and the event page together. ## After the purchase Ticket Fairy sends a signed webhook to your agent's registered address when the order is created and each time it changes. A UCP agent can also read the order with Get Order. The order shows delivery status and whether a wallet pass is ready. Ticket barcodes stay with the buyer. Refunds, cancellations, attendee changes, transfers, face-value resale, seat changes, upgrades, payment-plan changes and waiting-list offers are capabilities on the order. The order lists the ones your agent can use. Each change follows the event's own refund, transfer and resale rules, needs the buyer's approval, and sends its own signed webhook when it is done. ## What organizers control Agent sales are on for every brand by default. A brand owner or admin can turn them off for the whole brand, or pause them for one event, in the dashboard or by asking Fai. A new checkout for that brand or event is then refused, and a buyer you already sent to the checkout page can still finish there. Organizers set the purchase limits and the refund, transfer and resale rules that every agent follows. No organizer can give an agent priority, extra holds or lower fees. ## Questions about agent checkout ### Does my agent need approval from Ticket Fairy? No. Any agent with Agentic Commerce Protocol or Universal Commerce Protocol support can identify itself and sell tickets for events on Ticket Fairy's own brands. Organizers can turn agent sales off for their brand or pause them for one event. ### Does the buyer pay inside my agent? Yes, for events that take card payments through Stripe: card, Link, and Affirm or Klarna where the event page offers them. A UCP agent can also pay within an AP2 mandate the buyer signed. Each checkout lists the payment handlers it accepts. For any other payment method, the checkout gives a continue\_url, and the buyer pays in their browser with the same tickets still held. ### What do the prices include? The checkout total is the price the buyer pays, fees included. The starting price that event search shows is not a quote, so always show the buyer the checkout total before they pay. ### Can my agent refund or transfer tickets? Yes, within the event's own rules. Refunds, cancellations, attendee changes, transfers, face-value resale, seat changes, upgrades and payment-plan changes are capabilities on the order. The order lists the ones your agent can use, and the buyer approves each change. ### Does an agent get better access than the event page? No. An agent sees the same tickets, prices, fees, purchase limits and waiting room as a person on the event page. No agent gets priority, extra holds or lower fees. ### Can my agent manage events? Not with a buyer key or a signed profile, which work only for buying tickets. To act for an organizer, connect the hosted organizer MCP server or use a credential the organizer approves, described in the authentication documentation. Ticket Fairy in full: [ticketing platform for event organizers](https://www.ticketfairy.com/event-ticketing/), with the features, pricing and support behind this page. ## Further Reading [**AI agents** MCP servers, Agent2Agent, WebMCP, agent skills and discovery files.](https://www.ticketfairy.com/developers/ai-agents) [**Developer documentation** The public event API, NLWeb, the SDKs and every developer page.](https://www.ticketfairy.com/developers) [**Authentication** Personal Access Tokens, agent approval and OAuth.](https://www.ticketfairy.com/developers/authentication) ## Building a shopping agent? Email [support@theticketfairy.com](mailto:support@theticketfairy.com) with your agent's name and the checkout ID if a request does not answer as you expect. [See every way to connect](https://www.ticketfairy.com/developers/ai-agents) [Read auth.md](https://www.ticketfairy.com/auth.md) --- This page is on Ticket Fairy, a ticketing, marketing and operations platform for live events and the venues that host them: festivals, club nights, concerts, conferences and tours, and night clubs, beach clubs and concert venues. It grows revenue with fan rewards that turn an audience into a sales channel, and runs the money side with payments and payouts, Vault business banking, and working capital advanced against ticket sales. [How Ticket Fairy ticketing works](https://www.ticketfairy.com/event-ticketing) ยท [Ticket Fairy for AI assistants](https://www.ticketfairy.com/llms.txt)