Skip to content

Events · Tickets​

Tickets (#2487): checkout (hold seats for 10 minutes, fill in, pay), the order and its receipt, cancelling and asking for a refund, the ticket (its code is the ticket), its Apple Wallet pass and calendar file, the waitlist, and a volunteer answering an invitation. One card payment on the platform account is split into one ordinary gift per linked Fundly by its share. Behind features.events. A rule's refusal is 409 not_allowed with details.reason.


Start checkout​

POST
/events/{id}/orders

Holds seats for 10 minutes: under the event's row lock, the seats left are counted (capacity, each ticket type, per day for "one day each") and a held order with one ticket per seat is written. Prices, the value of the dinner and the Fundly shares are copied onto it. Signed out (when the event takes guests without an account), buyer_name and buyer_email are required and the answer carries the order link's access_token, once. A buyer's earlier held order for the event is released. 5 a minute per address. With Idempotency-Key (#2709), a repeat with the same key and body answers the order the first made (a guest's access_token too) instead of holding seats twice; another body is 409 idempotency_conflict, a repeat while the first still runs 409 request_in_progress. No seat needs a name or an email (#2709): a reservation is one name and a party size.

Authorizations​

or
BearerAuth

In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.

Type
HTTP (bearer)

Parameters​

Header Parameters

Idempotency-Key

Optional (#2709): 16 to 200 of [A-Za-z0-9_.:-], a uuid. Kept two days, scoped to the endpoint, the event and the caller.

Type
string
Pattern
"^[A-Za-z0-9_.:-]{16,200}$"

Path Parameters

id*

The event's id.

Type
string
Required
Format
"uuid"

Request Body​

application/json
JSON
{
"lines": [
{
"ticket_type_id": "string",
"quantity": 0
}
],
"event_day_id": "string",
"access_code": "string",
"buyer_name": "string",
"buyer_email": "string",
"language": "string",
"ref": "string",
"show_attending": true
}

Responses​

Held.

application/json
JSON
{
"order": "string",
"access_token": "string",
"hold_minutes": 0
}

Playground​

Server
Headers
Variables
Key
Value
Body

Samples​


An order​

GET
/event-orders/{id}

The buyer's order (by account or the order link) or, for the event's hosts and staff, any of its orders.

Authorizations​

or
BearerAuth

In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.

Type
HTTP (bearer)

Parameters​

Header Parameters

X-Order-Token

The order link's token, for a buyer without an account.

Type
string

Path Parameters

id*

The order's id.

Type
string
Required
Format
"uuid"

Query Parameters

token

The order link's token (or send it as X-Order-Token), for a buyer without an account. The buyer's first ticket code works too.

Type
string

Responses​

The order.

application/json
JSON
"string"

Playground​

Server
Headers
Variables
Key
Value

Samples​


Fill in an order​

PATCH
/event-orders/{id}

While held: guests' names and emails, dietary needs, a gift, covering the card fee. Totals are recomputed; a PaymentIntent already made follows the new total.

Authorizations​

or
BearerAuth

In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.

Type
HTTP (bearer)

Parameters​

Header Parameters

X-Order-Token

The order link's token, for a buyer without an account.

Type
string

Path Parameters

id*

The order's id.

Type
string
Required
Format
"uuid"

Request Body​

application/json
JSON
{
"buyer_name": "string",
"buyer_email": "string",
"language": "string",
"show_attending": true,
"gift_cents": 0,
"cover_fee": true,
"tickets": [
{
"id": "string",
"guest_name": "string",
"guest_email": "string",
"dietary": "string",
"dietary_note": "string"
}
]
}

Responses​

The order.

application/json
JSON
"string"

Playground​

Server
Headers
Variables
Key
Value
Body

Samples​


Pay for an order​

POST
/event-orders/{id}/pay

Free: confirmed at once (requested when the hosts approve each reservation). Paid: a PaymentIntent on the platform account (no destination; metadata.kind = event_order, metadata.order_id; manual capture when approval is on, charged only when a host approves), and its client secret. The money is split into one ordinary gift per Fundly when the payment succeeds (the Stripe webhook). With the one sheet (#2581, while features.donate_sheet_v2 is on for the buyer) the body carries the way to pay: the order is priced with that method's fee, the PaymentIntent takes that method only and is confirmed by the server. A US bank debit that is processing issues the tickets at once and leaves the order clearing; a bank debit the bank returns later cancels the order. Bank is refused for an order the hosts approve and for an event less than 7 days away.

Authorizations​

or
BearerAuth

In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.

Type
HTTP (bearer)

Parameters​

Header Parameters

X-Order-Token

The order link's token, for a buyer without an account.

Type
string

Path Parameters

id*

The order's id.

Type
string
Required
Format
"uuid"

Request Body​

application/json
JSON
{
"confirmation_token_id": "string",
"payment_method_id": "string",
"save_payment_method": true,
"save_consent_version": "string",
"expected_total_cents": 0,
"return_url": "string"
}

Responses​

The order, and the payment to confirm (null when free).

application/json
JSON
{
"order": "string",
"payment": {
"client_secret": "string",
"payment_intent_id": "string",
"amount_cents": 0,
"capture": "string",
"status": "string",
"stripe_fee_cents": 0,
"net_amount_cents": 0,
"fee_kind": "string"
}
}

Playground​

Server
Headers
Variables
Key
Value
Body

Samples​


Settle an order right after its card payment​

POST
/event-orders/{id}/confirm-payment

Called by checkout right after the card is confirmed, so the ticket shows without waiting for the Stripe webhook. The server reads the order's own PaymentIntent from Stripe (never one the caller names) and, when it succeeded, records the order paid through the same idempotent path as the webhook (the order paid once, its money split once per Fundly); a card authorized for an order that needs the hosts' approval makes it a request. The webhook that arrives afterwards changes nothing. Any other payment state, or Stripe being unreachable, leaves the order as it is: keep reading GET /event-orders/{id}. The buyer only: by account or the order link's token.

Authorizations​

or
BearerAuth

In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.

Type
HTTP (bearer)

Parameters​

Header Parameters

X-Order-Token

The order link's token, for a buyer without an account.

Type
string

Path Parameters

id*

The order's id.

Type
string
Required
Format
"uuid"

Responses​

The order as it is now.

application/json
JSON
"string"

Playground​

Server
Headers
Variables
Key
Value

Samples​


Cancel an order​

POST
/event-orders/{id}/cancel

Withdraw a request (the card's hold is released), or cancel before the free-cancellation date (a free RSVP: until the event starts), refunded in full through each gift's refund path. The seats go back and the waitlist is offered them. The buyer only: by account, the order link's token, or buyer_code, the code of the order's first ticket (what the ticket email's link carries). Anyone else, and a wrong code, gets 404.

Authorizations​

or
BearerAuth

In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.

Type
HTTP (bearer)

Parameters​

Header Parameters

X-Order-Token

The order link's token, for a buyer without an account.

Type
string

Path Parameters

id*

The order's id.

Type
string
Required
Format
"uuid"

Request Body​

application/json
JSON
{
"buyer_code": "string"
}

Responses​

The order.

application/json
JSON
"string"

Playground​

Server
Headers
Variables
Key
Value
Body

Samples​


Ask the hosts for a refund​

POST
/event-orders/{id}/refund-request

After the free-cancellation date and until 30 days after the event: the hosts (or staff) refund or decline it. One open request per order. The buyer proves the order as for cancel (account, token or buyer_code).

Authorizations​

or
BearerAuth

In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.

Type
HTTP (bearer)

Parameters​

Header Parameters

X-Order-Token

The order link's token, for a buyer without an account.

Type
string

Path Parameters

id*

The order's id.

Type
string
Required
Format
"uuid"

Request Body​

application/json
JSON
{
"reason": "string",
"note": "string",
"buyer_code": "string"
}

Responses​

The order.

application/json
JSON
"string"

Playground​

Server
Headers
Variables
Key
Value
Body

Samples​


The receipt of an order​

GET
/event-orders/{id}/receipt

Who may see the order may see its receipt. It exists from the moment the order is paid: while a US bank payment is still in progress, payment.state is in_progress and payment.bank_arrival is the day the money is expected. receipt_email.sent_to lists where copies went for the buyer only.

Authorizations​

or
BearerAuth

In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.

Type
HTTP (bearer)

Parameters​

Header Parameters

X-Order-Token

The order link's token, for a buyer without an account.

Type
string

Path Parameters

id*

The order's id.

Type
string
Required
Format
"uuid"

Query Parameters

code

The order's party code (or its first ticket's code), the buyer's proof from the "You're going" email's View receipt (#2709).

Type
string
Pattern
"^[A-Za-z0-9_-]{22}$"
token

The order link's token (or send it as X-Order-Token), for a buyer without an account. The buyer's first ticket code works too.

Type
string

Responses​

The receipt.

application/json
JSON
"string"

Playground​

Server
Headers
Variables
Key
Value

Samples​


Email a copy of an order's receipt​

POST
/event-orders/{id}/receipt/email

The buyer mails a copy of the order's receipt to any address, at most 5 per order. The buyer only (not a host, not staff): by account, the order's token, or buyer_code. The copy carries the receipt and a link to the event's page, never a ticket. An order whose US bank payment is still in progress sends the receipt that says so. Rate limited at 5 requests/minute per IP.

Authorizations​

or
BearerAuth

In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.

Type
HTTP (bearer)

Parameters​

Header Parameters

X-Order-Token

The order link's token, for a buyer without an account.

Type
string

Path Parameters

id*

The order's id.

Type
string
Required
Format
"uuid"

Query Parameters

token

The order link's token (or send it as X-Order-Token), for a buyer without an account. The buyer's first ticket code works too.

Type
string

Request Body​

application/json
JSON
{
"email": "string",
"buyer_code": "string"
}

Responses​

Sent, or queued and on its way.

application/json
JSON
{
"sent_to": "string",
"queued": true,
"receipt_email": "string"
}

Playground​

Server
Headers
Variables
Key
Value
Body

Samples​


A ticket​

GET
/event-tickets/{code}

Whoever holds the code. Always the reservation's ticket layout (PartyTicket, kind: party, #2709). An order's party code answers the reservation. A legacy per-seat code answers the reservation too when it is the buyer's own seat or the reader is the buyer (its url carries the party code: the page moves there); any other seat (one a buyer sent a guest) answers that seat alone, with seat set and no party code, payment, receipt or actions. A request the hosts have not approved shows no code (code: null). Answers Referrer-Policy: no-referrer, never cached, never indexed.

Authorizations​

or
BearerAuth

In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.

Type
HTTP (bearer)

Parameters​

Path Parameters

code*

The ticket's code: 16 random bytes, base64url (22 characters). It is the ticket.

Type
string
Required
Pattern
"^[A-Za-z0-9_-]{22}$"

Responses​

The ticket.

application/json
JSON
"string"

Playground​

Server
Variables
Key
Value

Samples​


A party's QR as a PNG​

GET
/event-tickets/{code}/qr.png

The QR of an order's party code (#2709), for the "You're going" email (an image in mail cannot be a data URI). Only an order that admits someone has one; anything else is a 404. The same code is the same image: Cache-Control: public, max-age=86400.

Authorizations​

or
BearerAuth

In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.

Type
HTTP (bearer)

Parameters​

Path Parameters

code*

The ticket's code: 16 random bytes, base64url (22 characters). It is the ticket.

Type
string
Required
Pattern
"^[A-Za-z0-9_-]{22}$"

Responses​

The PNG.

image/png

Playground​

Server
Variables
Key
Value

Samples​


A ticket's Apple Wallet pass​

GET
/event-tickets/{code}/wallet

An eventTicket .pkpass with the ticket's QR code, the date, the venue and a reminder near it. Off (404) unless the server's EVENT_WALLET_ENABLED is on (#2709); nothing links to it while it is off. 503 wallet_unavailable until the Pass Type ID certificate set is configured.

Authorizations​

or
BearerAuth

In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.

Type
HTTP (bearer)

Parameters​

Path Parameters

code*

The ticket's code: 16 random bytes, base64url (22 characters). It is the ticket.

Type
string
Required
Pattern
"^[A-Za-z0-9_-]{22}$"

Responses​

The pass.

application/vnd.apple.pkpass

Playground​

Server
Variables
Key
Value

Samples​


The calendar file​

GET
/events/{id}/calendar.ics

One VEVENT per day, a stable UID and a SEQUENCE that grows with every change. A hidden address shows only with ?ticket= a ticket of the event.

Authorizations​

or
BearerAuth

In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.

Type
HTTP (bearer)

Parameters​

Path Parameters

id*

The event's id.

Type
string
Required
Format
"uuid"

Query Parameters

ticket
Type
string

Responses​

The file.

text/calendar
JSON
"string"

Playground​

Server
Variables
Key
Value

Samples​


Join the waitlist​

POST
/events/{id}/waitlist

A sold-out event with the waitlist on. When seats come back the next people in line whose seats fit get them for 24 hours. Signed out, name and email; the answer carries the place's token, once.

Authorizations​

or
BearerAuth

In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.

Type
HTTP (bearer)

Parameters​

Path Parameters

id*

The event's id.

Type
string
Required
Format
"uuid"

Request Body​

application/json
JSON
{
"ticket_type_id": "string",
"event_day_id": "string",
"quantity": 0,
"name": "string",
"email": "string",
"language": "string"
}

Responses​

On the list.

application/json
JSON
{
"entry": "string",
"token": "string"
}

Playground​

Server
Variables
Key
Value
Body

Samples​


Notify me when tickets go on sale​

POST
/events/{id}/sale-alert

While an event's tickets are not on sale yet (sale_status not_on_sale_yet), ask to be told when they are. Signed in, one click (the account; viewer.sale_alert then reads true); signed out, an email. One per person or email per event; asking again answers already. When sales open (the sales start passes, or a host or staff opens them) each one gets one email, and a member a bell notice, in the Events email category (one-click unsubscribe).

Authorizations​

or
BearerAuth

In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.

Type
HTTP (bearer)

Parameters​

Path Parameters

id*

The event's id.

Type
string
Required
Format
"uuid"

Request Body​

application/json
JSON
{
"email": "string",
"language": "string"
}

Responses​

Already on the list.

application/json
JSON
{
"state": "string"
}

Playground​

Server
Variables
Key
Value
Body

Samples​


Leave the waitlist​

DELETE
/events/{id}/waitlist/me

An offer given back goes to the next person in line.

Authorizations​

or
BearerAuth

In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.

Type
HTTP (bearer)

Parameters​

Header Parameters

X-Order-Token

The order link's token, for a buyer without an account.

Type
string

Path Parameters

id*

The event's id.

Type
string
Required
Format
"uuid"

Query Parameters

token

The order link's token (or send it as X-Order-Token), for a buyer without an account. The buyer's first ticket code works too.

Type
string

Responses​

Left.

Playground​

Server
Headers
Variables
Key
Value

Samples​


Claim a waitlist offer​

POST
/event-waitlist/{id}/claim

The offer becomes a held order to pay, kept until the offer runs out.

Authorizations​

or
BearerAuth

In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.

Type
HTTP (bearer)

Parameters​

Header Parameters

X-Order-Token

The order link's token, for a buyer without an account.

Type
string

Path Parameters

id*

The waitlist place's id.

Type
string
Required
Format
"uuid"

Responses​

The order.

application/json
JSON
"string"

Playground​

Server
Headers
Variables
Key
Value

Samples​


Confirm a volunteer invitation​

POST
/event-volunteers/{id}/confirm

The member a host invited to a role says yes. A full role takes no more.

Authorizations​

BearerAuth

In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.

Type
HTTP (bearer)

Parameters​

Path Parameters

id*

The volunteer row's id.

Type
string
Required
Format
"uuid"

Responses​

Confirmed.

application/json
JSON
{
"additionalProperties": "string"
}

Playground​

Server
Authorization
Variables
Key
Value

Samples​


Decline a volunteer invitation​

POST
/event-volunteers/{id}/decline

The member a host invited says no.

Authorizations​

BearerAuth

In the browser, authentication rides on the httpOnly session cookies set by /cognito/signin or the Google / Apple sign-in at /cognito/oauth/{provider}. For scripts and for Swagger UI testing, paste an API key (fh_live_…, created with POST /api-keys); a Cognito JWT is accepted too. Sign-in does not return a token in its body.

Type
HTTP (bearer)

Parameters​

Path Parameters

id*

The volunteer row's id.

Type
string
Required
Format
"uuid"

Responses​

Declined.

application/json
JSON
{
"additionalProperties": "string"
}

Playground​

Server
Authorization
Variables
Key
Value

Samples​


Powered by VitePress OpenAPI

Built with VitePress