# Events and tickets

Source: https://docs.tuppence.ai/docs/events/

> Sell tickets to an event with no booking fee. Create it, add ticket types, publish its page, and hear about every order. Ticket money is held until after the event.

For agents: [start here](https://docs.tuppence.ai/docs/agents.md), [every page](https://docs.tuppence.ai/docs/llms.txt), [the agent guide](https://docs.tuppence.ai/docs/SKILL.md), [the MCP server](https://docs.tuppence.ai/docs/mcp.md).

**Tuppence Events** sells tickets to meetups, workshops, gigs and conferences. You create an
event and its ticket types, publish it, and buyers pay on its page at `/e/<slug>` with Apple Pay,
Google Pay or a card. There is no booking fee: the price on the page is the price the buyer pays.
Each order's money is **held until after the event**, then released to your balance.

*Diagram: Selling tickets in four steps: create a draft event with POST /v1/ticketing/events, add ticket types with POST /v1/ticket_types, publish it so its page opens, then each paid order sends ticket_order.paid and the buyer gets their tickets by email.*

1. **Create**: `POST /v1/ticketing/events`
2. **Add tickets**: `POST /v1/ticket_types`
3. **Publish**: `…/events/{id}/publish`
4. **Sell**: `ticket_order.paid`

## 1. Create the event

A title and `starts_at` are enough. It starts as a `draft` in your account's timezone and
currency, with a public page, no capacity limit, refunds until a day before and a reminder 24
hours before.

#### curl

```bash
curl -sS https://api.tuppence.ai/v1/ticketing/events \
  -H "Authorization: Bearer $TUPPENCE_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"title": "Agents After Dark", "starts_at": "2026-12-03T18:30:00Z", "venue_name": "The Engine Room", "capacity": 120}'
```

#### Node

```js
import { Tuppence } from "@tuppence/node";

const tuppence = new Tuppence(process.env.TUPPENCE_SECRET_KEY);

const event = await tuppence.request("POST", "/v1/ticketing/events", {
  body: {
    title: "Agents After Dark",
    starts_at: "2026-12-03T18:30:00Z",
    venue_name: "The Engine Room",
    capacity: 120,
  },
});
```

#### Python

```python
import os
from tuppence import Tuppence

tuppence = Tuppence(os.environ["TUPPENCE_SECRET_KEY"])

event = tuppence.request("POST", "/v1/ticketing/events", body={
    "title": "Agents After Dark",
    "starts_at": "2026-12-03T18:30:00Z",
    "venue_name": "The Engine Room",
    "capacity": 120,
})
```

| Field | Default |
|---|---|
| `slug` | From the title. The page is `/e/<slug>`. |
| `timezone` | The account's (`GET /v1/account` → `timezone`). |
| `ends_at` | Two hours after `starts_at`. Send `dates` instead for an event with several dates. |
| `venue_name`, `venue_address` or `online_url` | None. `online_url` is shown only to ticket holders. |
| `capacity` | No limit. Each ticket type can have its own as well. |
| `visibility` | `public`. `unlisted`: only people with the link. |
| `refund_policy` | `until_1_day`: buyers can ask for a refund until a day before. |
| `reminder_hours_before` | `24`. `null` for no reminder. |
| `questions` | None. Asked of every ticket's holder at checkout. |

## 2. Add ticket types

A `name`, and a `price` in minor units for a paid ticket (none makes it free). Up to five
`price_phases` come before the base price: an early bird `until_at` a time or `until_sold` a number sold.

#### curl

```bash
curl -sS https://api.tuppence.ai/v1/ticket_types \
  -H "Authorization: Bearer $TUPPENCE_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"event": "tev_…", "name": "General admission", "price": 2500,
       "price_phases": [{"name": "Early bird", "price": 1500, "until_sold": 50}]}'
```

#### Node

```js
const general = await tuppence.request("POST", "/v1/ticket_types", {
  body: {
    event: event.id,
    name: "General admission",
    price: 2500,
    price_phases: [{ name: "Early bird", price: 1500, until_sold: 50 }],
  },
});
```

#### Python

```python
general = tuppence.request("POST", "/v1/ticket_types", body={
    "event": event["id"],
    "name": "General admission",
    "price": 2500,
    "price_phases": [{"name": "Early bird", "price": 1500, "until_sold": 50}],
})
```

Promo and access codes are `POST /v1/ticketing/promo_codes`: `percent_off` or `amount_off` off
each ticket, `unlocks` for hidden or code-only ticket types, or both.

## 3. Publish

`POST /v1/ticketing/events/{id}/publish` puts the draft on sale, opens its page and sends
`event.published`. `…/unpublish` takes it off sale again; tickets already sold stay valid.

#### curl

```bash
curl -sS -X POST https://api.tuppence.ai/v1/ticketing/events/tev_…/publish \
  -H "Authorization: Bearer $TUPPENCE_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

#### Node

```js
await tuppence.request("POST", `/v1/ticketing/events/${event.id}/publish`);
```

#### Python

```python
tuppence.request("POST", f"/v1/ticketing/events/{event['id']}/publish")
```

## 4. Hear about orders

A buyer's checkout holds their seats for 10 minutes at the price shown, then they pay. Each paid
order issues its tickets and emails them to the buyer (a PDF, and a page per ticket with its QR
code). Listen for these on a [webhook endpoint](/docs/webhooks/):

| Event | When |
|---|---|
| `event.published`, `event.unpublished` | The event goes on or comes off sale. |
| `ticket_order.paid` | An order is paid and its tickets issued. A free order is paid at once. |
| `ticket.issued` | Once per ticket. |
| `ticket_order.refunded`, `ticket.refunded` | A refund, of the whole order or some of its tickets. |
| `event.cancelled` | The event is cancelled. Every buyer's refund follows within minutes. |
| `ticket_funds.released` | A date's held money is released to your balance. |
| `ticket_funds.extended` | A release is put off for a review. |

Read orders and tickets with `GET /v1/ticket_orders?event=` and `GET /v1/tickets?event=` (or
`?order=`). A ticket's signing secret is never returned.

## Refunds and cancelling

| Call | What happens |
|---|---|
| `POST /v1/ticket_orders/{id}/refund` | Refunds the order, or only the `tickets` you name. Those tickets stop working and their seats go back on sale if the date hasn't started. |
| `POST /v1/refunds` on the order's payment | Treated the same way: refunding all of what is left voids every ticket. |
| `POST /v1/ticketing/events/{id}/cancel` | Comes off sale for good, voids every ticket and refunds every buyer in full, once. |

Refunds come out of the event's held money first.

## When you get paid

Ticket money is held per date until after it has happened. It can't be paid out, spent on a card
or moved before then. It is released at 00:00 in the event's timezone on the **next working day
after the date ends**; a new account's first events can take a little longer. A cancelled event,
or something on the account a person needs to look at, puts the release off for a review instead.

#### curl

```bash
curl -sS "https://api.tuppence.ai/v1/ticketing/funds_holds?event=tev_…" \
  -H "Authorization: Bearer $TUPPENCE_SECRET_KEY"
```

#### Node

```js
const holds = await tuppence.request("GET", `/v1/ticketing/funds_holds?event=${event.id}`);
```

#### Python

```python
holds = tuppence.request("GET", f"/v1/ticketing/funds_holds?event={event['id']}")
```

| `status` | Meaning |
|---|---|
| `held` | Waiting for the date to end. `release_after` says when it is released. |
| `released` | In your balance, paid out with your next payout. |
| `extended` | Put off for a review. `extended_reason` says why. |
| `used_for_refunds` | The event was cancelled and the money went back to its buyers. |

An event's settlement (gross, discounts, refunds, fees, net and what is held) is
`GET /v1/ticketing/events/{id}/settlement`, or `settlement.csv`.

> **Note**
>
> In test mode, move the account's clock past the event with `POST /v1/test_helpers/clock/advance`
> to watch a release happen. See [Testing](/docs/testing/).

## Fair tickets

Tickets can change hands without touts or fees:

| Call | What happens |
|---|---|
| `POST /v1/tickets/{id}/transfer` | Gives a valid ticket to someone else (`name`, `email`). The ticket is voided and a new one (a new code) is issued in their name and emailed to them. Sends `ticket.transferred`, then `ticket.issued`. |
| `POST /v1/tickets/{id}/return` | Gives a ticket back to its sold-out event's waitlist, to sell at the price its holder paid. It works until it sells; then it is voided and its holder refunded in full, with no fee. |
| `GET /v1/ticketing/waitlist?event=` | The event's waitlist: who is waiting, offered a ticket (held for 30 minutes) or got one. |

Buyers do the same from their ticket page, and join a sold-out type's waitlist from the event page.

| Setting on the event | Default | What it does |
|---|---|---|
| `named_tickets` | `false` | Checkout asks for each ticket's holder (`tickets[].names`); the name shows at the door and on the pass. |
| `code_reveal` | `auto` | Whose door codes rotate: `auto` (paid tickets), `on` or `off`. |
| `code_reveal_hours_before` | `3` | When the rotating code appears on the ticket page, before doors (or the start). |
| `venue_latitude`, `venue_longitude` | none | The venue's place, as decimal strings (`"51.5194"`), so wallet passes show on the lock screen nearby. |

A rotating code is `t2.<ticket>.<window>.<signature>`, new every 15 seconds; a screenshot stops
working within 30 seconds.

## Repeating events and passes

Send `repeat` with the first date to make a series: `every` is `week` or `month`, with `count`
(default 12) or `until`. Monthly goes by the weekday ("the second Tuesday"); `on: "day"` keeps the
day of the month. Each date keeps the first one's local start time and length.

```json
{
  "title": "Agents After Dark",
  "timezone": "Europe/London",
  "starts_at": "2026-12-08T19:00:00Z",
  "repeat": { "every": "month", "count": 6 }
}
```

Add dates later with `POST /v1/ticketing/events/{id}/dates` (one date, `dates`, or `repeat`; a date
that starts when one already does is skipped), move one with `POST …/dates/{date}`, and remove one
nobody has ordered for with `DELETE …/dates/{date}`.

A ticket type with `pass_dates` (two or more of the event's date ids) is a multi-day pass. Buyers
check out a pass with no `date`, in an order of its own. It takes a seat on each of its dates, and
its money is held until the last one has ended.

## Messages to attendees

Buyers can give `buyer.phone` and tick `buyer.sms_opt_in` or `buyer.whatsapp_opt_in` at checkout.
`POST /v1/ticketing/events/{id}/messages` with a `subject` and `body` emails every paid buyer in
the `segment` (`ticket_types`, `date`, `checked_in`), and texts or messages on WhatsApp only those
who agreed. Send it now or at `send_at`; each buyer gets it once per channel. The answer says who it
reaches (`audience`) and, once sent, what went (`delivered`). `POST /v1/ticketing/messages/{id}/cancel`
calls off a scheduled one.

Buyers who tick `buyer.marketing_opt_in` hear about your next public event when you first publish
it (`announce_to_past_attendees`, on by default), at most once a week, with a one-click unsubscribe.

## Pixels and sources

`POST /v1/ticketing/settings` with `pixels: { meta, tiktok, ga4 }` sets the ad pixels every event's
page loads; an event's own `pixels` replace them (`{}` for none). The page loads them only after
the buyer agrees to advertising cookies. Checkout takes `utm` (`utm_source`, `utm_medium`,
`utm_campaign`, `utm_term`, `utm_content`); `GET /v1/ticketing/reports/sales` groups orders by them.

## Next

- [Sell on your own website](/docs/events/embed/): the event and its checkout in a widget.
- [Webhooks](/docs/webhooks/): receive the events above.
- [MCP](/docs/mcp/): the same events and orders as tools for your AI agent.
