API Reference

A one-page reference for the Seaty API: every endpoint, the payment-method codes, the scopes, the error codes, and the rate limits.

Everything on one page. For the always-current interactive version, see https://developer.seaty.co.uk/docs.

Base URL: https://developer.seaty.co.uk/v1
Auth: Authorization: Bearer sk_live_...
Money: integer pence. Dates: ISO 8601 (UTC).

All endpoints

Reads (scope: `read`)

Method	Path	Description	Guide
GET	`/v1/events`	List your events	Events
GET	`/v1/events/{id}`	Get one event	Events
GET	`/v1/events/{id}/dates`	List an event's dates	Events
GET	`/v1/events/{id}/ticket-categories`	List ticket categories	Events
GET	`/v1/events/{id}/seating-plans`	List an event's seating plans	Seating
GET	`/v1/events/{id}/sections`	List an event's seating sections	Seating
GET	`/v1/dates/{id}`	Get one date	Dates
GET	`/v1/dates/{id}/orders`	List a date's orders	Dates
GET	`/v1/dates/{id}/summary`	Sales & attendance summary for a date	Dates
GET	`/v1/orders/{id}`	Get one order	Orders
GET	`/v1/orders/{id}/tickets`	List an order's tickets	Orders
GET	`/v1/orders/{id}/payments`	List an order's payments and refunds	Orders
GET	`/v1/orders/{id}/discounts`	List an order's discounts	Orders
GET	`/v1/attendees`	List distinct attendees	Attendees
GET	`/v1/venues`	List the venues used by your events	Venues
GET	`/v1/venues/{id}`	Get one venue	Venues

Writes

Method	Path	Scope	Description	Guide
POST	`/v1/events/{id}/balance-payments`	`write:balance_payments`	Record an external balance payment	Balance payments and refunds
POST	`/v1/events/{id}/balance-refunds`	`write:balance_payments`	Record an external balance refund	Balance payments and refunds
PATCH	`/v1/orders/{id}`	`write:orders`	Update an order's back-office admin note	Orders

Webhooks

Push, not pull. Subscribe in the dashboard (not via the API); Seaty sends a signed POST to your https URL when a subscribed event happens. See Webhooks for the envelope, signature verification and the event catalogue (balance.payment_recorded, balance.refund_recorded, order.placed, ticket.checked_in, request.made).

Payment-method codes (`type_id`)

Used on payments and when recording a balance payment or refund.

`type_id`	Method
1	Cash	settable
2	Cheque	settable
3	Card (taken outside Seaty)	settable
4	Bank transfer	settable
5	Card (taken through Seaty)	read-only

When recording a balance payment, only 1–4 are accepted. Code 5 (and any other internal code) can appear when reading payments but cannot be set through the API; such payments read back with method: "other".

Scopes

Scope	Allows
`read`	All read endpoints. Every key has this.
`write:balance_payments`	Recording balance payments and refunds. Only keys created with this permission.
`write:orders`	Updating an order's back-office admin note. Only keys created with this permission.

Error codes

Status	`code`	Meaning
400	`bad_request`	Malformed request.
401	`unauthorized`	Missing or invalid API key.
403	`forbidden`	Key is missing a required scope.
404	`not_found`	No such record in your organisation.
409	`conflict`	A balance payment with that idempotency key is already in progress.
422	`unprocessable_entity`	Valid request that could not be applied (e.g. payee has no order, or refund exceeds amount paid).
429	`rate_limited`	Too many requests; see `Retry-After`.
502	`upstream_error`	Temporary downstream problem; retry shortly.

Rate limits

	Per minute	Burst
Reads	60	30
Writes (balance payments, order notes)	30	10

Responses carry X-RateLimit-Limit and X-RateLimit-Remaining; a 429 carries Retry-After (seconds).

Pagination envelope

{
  "data": [ ... ],
  "links": { "first": "...", "last": "...", "prev": null, "next": "..." },
  "meta": { "current_page": 1, "per_page": 10, "from": 1, "to": 10, "total": 42, "path": "/v1/..." }
}

page (default 1) and per_page (default 10, max 100) control paging. links.next is null on the last page.

Need help? Email support@seaty.co.uk.