Tito API

Get the account

GET /account

The account's own identity: slug, display name, and — where the platform places accounts by region — the region its data currently lives in.

Requires events.view

Response fields

#

slug string

The account's own URL identifier.

#

name string

Display name.

#

region string

Where the account's data currently lives, on deployments that place accounts by region. Absent on a standalone instance with no placement — never an empty string.

#

search_indexing boolean

Whether this account has opened its public site to search engines. False until an organizer turns it on, which is where every account starts, and while it is false nothing on the site is listed anywhere: the account's event list, its series pages and every event page all carry a noindex instruction. It closes nothing and gates nothing. An event with search_indexing "inherit" — the default — follows this value, so moving it moves every such event with it.

#

home_page string

What "/" shows on the account's own host: events, event:<slug> or page:<path>. An unreadable stored value answers as events, the way the door itself reads it.

#

root_pages boolean

Whether the account's pages answer on the root domain as well. ABSENT on an instance with no root domain — there is nothing for it to be true or false about. Unset reads as true: the root domain's URLs are the default surface.

#

close_on string (RFC 3339) or null

When the account is due to be closed, 30 days after its owner asked for it in Account settings. Null when it isn't closing. Asking and keeping the account happen in the admin only: asking emails the owner and every admin.

Responses

• 200The account calling.
• 401No key, an unknown key, or a revoked key.
• 403The key does not carry the required capability.
• 500Internal error.

curl https://<yourslug>.go.tito.io/api/v1/account \
  -H "Authorization: Bearer titogo_sk_your_key"

// Node 18+, Deno, Bun, or a browser on the same origin
const res = await fetch("https://<yourslug>.go.tito.io/api/v1/account", {
  method: "GET",
  headers: {
    Authorization: "Bearer titogo_sk_your_key",
  },
});
const data = await res.json();

{
  "slug": "acme",
  "name": "Acme Events",
  "region": "uk",
  "search_indexing": false,
  "home_page": "events",
  "root_pages": true,
  "close_on": null
}

Change the account's general settings

PATCH /account

The account's own set-up: what it is called, whether search engines may list its site, what its front door shows, and — where there is a root domain — whether its pages answer there too. Only the keys present change.

Two of these make every public page STALE the moment they move, and both purge the cached pages as part of the write: search_indexing (the noindex instruction rides the cached shells) and home_page (it is what "/" serves). Setting either to what it already is purges nothing.

home_page is events (the account's event listing), event:<slug> or page:<path>, and the target has to exist and be public — a front door pointing at nothing is the one thing this will not store. It governs the account's OWN host; the root domain's /{slug} listing is the standardized surface and is untouched by it.

The admin clock is not here: it is a standalone-instance knob, and the coverage manifest records it as the gap rather than the API offering a field that does nothing on a hosted account.

Requires settings.manage

Request body

#

name string

At most 100 characters, and not blank.

#

search_indexing boolean

Opens or closes the whole public site to search engines. Moving it purges every public page.

#

home_page string

events, event:<slug> or page:<path>. The target must exist and be public. Moving it purges every public page.

#

root_pages boolean

Refused where there is no root domain.

Response fields

#

slug string

The account's own URL identifier.

#

name string

Display name.

#

region string

Where the account's data currently lives, on deployments that place accounts by region. Absent on a standalone instance with no placement — never an empty string.

#

search_indexing boolean

Whether this account has opened its public site to search engines. False until an organizer turns it on, which is where every account starts, and while it is false nothing on the site is listed anywhere: the account's event list, its series pages and every event page all carry a noindex instruction. It closes nothing and gates nothing. An event with search_indexing "inherit" — the default — follows this value, so moving it moves every such event with it.

#

home_page string

What "/" shows on the account's own host: events, event:<slug> or page:<path>. An unreadable stored value answers as events, the way the door itself reads it.

#

root_pages boolean

Whether the account's pages answer on the root domain as well. ABSENT on an instance with no root domain — there is nothing for it to be true or false about. Unset reads as true: the root domain's URLs are the default surface.

#

close_on string (RFC 3339) or null

When the account is due to be closed, 30 days after its owner asked for it in Account settings. Null when it isn't closing. Asking and keeping the account happen in the admin only: asking emails the owner and every admin.

Responses

• 200The account, in the shape GET /account answers with.
• 401No key, an unknown key, or a revoked key.
• 403The key does not carry the required capability.
• 404No such resource.
• 409root_pages was named on an instance with no root domain to put pages on (no_root_domain).
• 422A blank name, a name over 100 characters, a blank or unknown home_page, an explicit null, or an unknown field (invalid_body).
• 500Internal error.

curl -X PATCH https://<yourslug>.go.tito.io/api/v1/account \
  -H "Authorization: Bearer titogo_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name":"The Sea Church"}'

// Node 18+, Deno, Bun, or a browser on the same origin
const res = await fetch("https://<yourslug>.go.tito.io/api/v1/account", {
  method: "PATCH",
  headers: {
    Authorization: "Bearer titogo_sk_your_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "name": "The Sea Church"
}),
});
const data = await res.json();

{
  "slug": "acme",
  "name": "Acme Events",
  "region": "uk",
  "search_indexing": false,
  "home_page": "events",
  "root_pages": true,
  "close_on": null
}

List the data-protection log

GET /data-protection-log

Every data-protection action on the account, newest first: each person anonymized, and each event deleted or set to be deleted and kept. A line names the record's reference, never the person. Paged by after, an entry id from the previous page's next_after. An agent limited to some events cannot call this.

Requires erasure

Query parameters

after string

Cursor: the ref returned as the previous page's next_after. Omit for the first page.

limit integer

Page size. Default 50, max 200. Non-positive or unparseable values fall back to the default.

Response fields

#

entries array of DataProtectionLogEntry

#

entries[].id integer

#

entries[].action string

one of ticket.anonymizedorder.anonymizedinvitation.anonymizedbuyer.anonymizedwaitlist.anonymizedapplication.anonymizedevent.deletedevent.delete_requestedevent.delete_keptevent.anonymize_requestedevent.anonymize_keptevent.anonymizedaccount.close_requestedaccount.close_kept

#

entries[].subject_type string

one of ticketorderinvitationbuyereventwaitlistapplicationaccount

#

entries[].subject_ref string

The record's reference, or the event's id, or empty for the account itself. Never the person.

#

entries[].event string or null

The slug of the event the record belongs to, null for a customer or a deleted event.

#

entries[].actor string

Who did it: a team member's email address, or the API key.

#

entries[].at string (RFC 3339)

#

next_after string or null

Pass as after for the next page; null on the last.

Responses

• 200A page of the log.
• 401No key, an unknown key, or a revoked key.
• 403The key does not carry the required capability.
• 422after is not an entry id (invalid_after).
• 500Internal error.

curl https://<yourslug>.go.tito.io/api/v1/data-protection-log \
  -H "Authorization: Bearer titogo_sk_your_key"

// Node 18+, Deno, Bun, or a browser on the same origin
const res = await fetch("https://<yourslug>.go.tito.io/api/v1/data-protection-log", {
  method: "GET",
  headers: {
    Authorization: "Bearer titogo_sk_your_key",
  },
});
const data = await res.json();

{
  "entries": [
    {
      "id": 1,
      "action": "ticket.anonymized",
      "subject_type": "ticket",
      "subject_ref": "H7K2PX",
      "event": "example",
      "actor": "example",
      "at": "2026-10-14T09:00:00Z"
    }
  ],
  "next_after": "example"
}

Get the order-notification settings

GET /notifications

When an order is paid the organizer gets an email, throttled so a rush becomes one summary per period instead of an inbox flood. Notifications are OPT-OUT: on is the resting state and the switch is how they are turned off.

effective_email is the field that answers "is this working?" — where a notification would actually go right now, or "" for nothing sends, whether because the switch is off or because there is no address anywhere. The other three (on, email, default_email) are what it is computed from.

Requires settings.manage

Response fields

#

on boolean

The switch. Notifications are opt-out, so this is true until somebody turns it off.

#

email string

The STORED address; "" means the instance default applies. Kept even while the switch is off.

#

default_email string

The instance's own fallback address, "" where there is none. Read-only — it is the fleet's, not the account's.

#

effective_email string

Where a notification would actually go right now; "" means nothing sends.

#

period_seconds integer

The throttle: at most one email per period. 0 is no throttle — every order reports immediately.

#

locale string

The language the notification is written in, resolved: the stored one, else the admin language, else English.

Responses

• 200The notification settings.
• 401No key, an unknown key, or a revoked key.
• 403The key does not carry the required capability.
• 404No such resource.
• 500Internal error.

curl https://<yourslug>.go.tito.io/api/v1/notifications \
  -H "Authorization: Bearer titogo_sk_your_key"

// Node 18+, Deno, Bun, or a browser on the same origin
const res = await fetch("https://<yourslug>.go.tito.io/api/v1/notifications", {
  method: "GET",
  headers: {
    Authorization: "Bearer titogo_sk_your_key",
  },
});
const data = await res.json();

{
  "on": true,
  "email": "orders@example.com",
  "default_email": "",
  "effective_email": "orders@example.com",
  "period_seconds": 900,
  "locale": "en"
}

Change the order-notification settings

PATCH /notifications

Only the keys present change.

Switching notifications on starts the clock now. Orders that were paid while they were off are marked reported at the moment of switch-on, so on means "from now" rather than "and here is everything you missed" — a caller flipping this in a script would otherwise mail an organizer a digest of their own history.

email is checked for SYNTAX only, the same bargain PATCH /tickets/{ref} makes: the organizer's own form runs a deliverability check with domain suggestions because a person is standing there to read "did you mean gmail.com?", and a machine has nobody to ask. "" is a real answer meaning "use the instance default", and the stored address is KEPT while the switch is off so turning them back on does not lose it.

period_seconds of 0 is a real answer too — every order reports immediately — and is not the same as leaving the key out. A negative one is refused rather than silently defaulted.

Requires settings.manage

Request body

#

on boolean

Turning this on baselines the backlog — see the operation's own note.

#

email string

Syntax-checked only. "" means "use the instance default".

#

period_seconds integer

Seconds; 0 reports every order immediately. Negative is refused.

#

locale string

A language code this build has.

Response fields

#

on boolean

The switch. Notifications are opt-out, so this is true until somebody turns it off.

#

email string

The STORED address; "" means the instance default applies. Kept even while the switch is off.

#

default_email string

The instance's own fallback address, "" where there is none. Read-only — it is the fleet's, not the account's.

#

effective_email string

Where a notification would actually go right now; "" means nothing sends.

#

period_seconds integer

The throttle: at most one email per period. 0 is no throttle — every order reports immediately.

#

locale string

The language the notification is written in, resolved: the stored one, else the admin language, else English.

Responses

• 200The settings, in the shape GET /notifications answers with.
• 401No key, an unknown key, or a revoked key.
• 403The key does not carry the required capability.
• 404No such resource.
• 422on was true with no address stored and no instance default, which is a preference nothing can act on (no_address); or email is not an address, period_seconds is negative, locale is not a language this build has, or the body carried an explicit null or an unknown field (invalid_body).
• 500Internal error.

curl -X PATCH https://<yourslug>.go.tito.io/api/v1/notifications \
  -H "Authorization: Bearer titogo_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"on":true}'

// Node 18+, Deno, Bun, or a browser on the same origin
const res = await fetch("https://<yourslug>.go.tito.io/api/v1/notifications", {
  method: "PATCH",
  headers: {
    Authorization: "Bearer titogo_sk_your_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "on": true
}),
});
const data = await res.json();

{
  "on": true,
  "email": "orders@example.com",
  "default_email": "",
  "effective_email": "orders@example.com",
  "period_seconds": 900,
  "locale": "en"
}

List buyer kinds

GET /buyer-kinds

The account's kinds, by name, each with how many buyers have it. A kind is a label for finding and filtering buyers; nothing else depends on it. There is no paging: an account has a handful.

Requires orders.view

Response fields

#

buyer_kinds array of BuyerKindDetail

#

buyer_kinds[].id integer

#

buyer_kinds[].name string

#

buyer_kinds[].buyer_count integer

How many buyers have this kind.

Responses

• 200The kinds.
• 401No key, an unknown key, or a revoked key.
• 403The key does not carry the required capability.
• 500Internal error.

curl https://<yourslug>.go.tito.io/api/v1/buyer-kinds \
  -H "Authorization: Bearer titogo_sk_your_key"

// Node 18+, Deno, Bun, or a browser on the same origin
const res = await fetch("https://<yourslug>.go.tito.io/api/v1/buyer-kinds", {
  method: "GET",
  headers: {
    Authorization: "Bearer titogo_sk_your_key",
  },
});
const data = await res.json();

{
  "buyer_kinds": [
    {
      "id": 2,
      "name": "Partners",
      "buyer_count": 12
    }
  ]
}

Create a buyer kind

POST /buyer-kinds

Add a kind. The name is trimmed, and must not be blank or already belong to another kind, however it's cased. Answers with the kind as stored.

Requires settings.manage

Request body

#

name string required

Response fields

#

id integer

#

name string

#

buyer_count integer

How many buyers have this kind.

Responses

• 201The kind was created.
• 401No key, an unknown key, or a revoked key.
• 403The key does not carry the required capability.
• 422The body isn't {"name": "..."} (invalid_body), the name is blank (invalid_name), or another kind already has that name, however it's cased (name_taken). A name is trimmed and kept to 200 characters.
• 500Internal error.

curl -X POST https://<yourslug>.go.tito.io/api/v1/buyer-kinds \
  -H "Authorization: Bearer titogo_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name":"Partners"}'

// Node 18+, Deno, Bun, or a browser on the same origin
const res = await fetch("https://<yourslug>.go.tito.io/api/v1/buyer-kinds", {
  method: "POST",
  headers: {
    Authorization: "Bearer titogo_sk_your_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "name": "Partners"
}),
});
const data = await res.json();

{
  "id": 2,
  "name": "Partners",
  "buyer_count": 12
}

Remove a buyer kind

DELETE /buyer-kinds/{id}

Remove a kind. Every buyer with it is left with no kind, in the same step; no buyer is removed. Answers with how many buyers were moved.

Requires settings.manage

Path parameters

id integer required

Response fields

#

id integer

#

deleted boolean

#

buyers_reset integer

How many buyers were left with no kind.

Responses

• 200The kind was removed.
• 401No key, an unknown key, or a revoked key.
• 403The key does not carry the required capability.
• 404No such resource.
• 500Internal error.

curl -X DELETE https://<yourslug>.go.tito.io/api/v1/buyer-kinds/1 \
  -H "Authorization: Bearer titogo_sk_your_key"

// Node 18+, Deno, Bun, or a browser on the same origin
const res = await fetch("https://<yourslug>.go.tito.io/api/v1/buyer-kinds/1", {
  method: "DELETE",
  headers: {
    Authorization: "Bearer titogo_sk_your_key",
  },
});
const data = await res.json();

{
  "id": 2,
  "deleted": true,
  "buyers_reset": 12
}

One buyer kind

GET /buyer-kinds/{id}

One kind, with how many buyers have it.

Requires orders.view

Path parameters

id integer required

Response fields

#

id integer

#

name string

#

buyer_count integer

How many buyers have this kind.

Responses

• 200The kind.
• 401No key, an unknown key, or a revoked key.
• 403The key does not carry the required capability.
• 404No such resource.
• 500Internal error.

curl https://<yourslug>.go.tito.io/api/v1/buyer-kinds/1 \
  -H "Authorization: Bearer titogo_sk_your_key"

// Node 18+, Deno, Bun, or a browser on the same origin
const res = await fetch("https://<yourslug>.go.tito.io/api/v1/buyer-kinds/1", {
  method: "GET",
  headers: {
    Authorization: "Bearer titogo_sk_your_key",
  },
});
const data = await res.json();

{
  "id": 2,
  "name": "Partners",
  "buyer_count": 12
}

Rename a buyer kind

PATCH /buyer-kinds/{id}

Give a kind a new name, on the same rules as a new one. Every buyer with the kind has it under the new name at once.

Requires settings.manage

Path parameters

id integer required

Request body

#

name string required

Response fields

#

id integer

#

name string

#

buyer_count integer

How many buyers have this kind.

Responses

• 200The kind as it now stands.
• 401No key, an unknown key, or a revoked key.
• 403The key does not carry the required capability.
• 404No such resource.
• 422The body isn't {"name": "..."} (invalid_body), the name is blank (invalid_name), or another kind already has that name, however it's cased (name_taken). A name is trimmed and kept to 200 characters.
• 500Internal error.

curl -X PATCH https://<yourslug>.go.tito.io/api/v1/buyer-kinds/1 \
  -H "Authorization: Bearer titogo_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name":"Partners"}'

// Node 18+, Deno, Bun, or a browser on the same origin
const res = await fetch("https://<yourslug>.go.tito.io/api/v1/buyer-kinds/1", {
  method: "PATCH",
  headers: {
    Authorization: "Bearer titogo_sk_your_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "name": "Partners"
}),
});
const data = await res.json();

{
  "id": 2,
  "name": "Partners",
  "buyer_count": 12
}

The buyer register

GET /buyers

Newest first, searchable by organization, name or email — the same match the organizer's own list makes.

No capability token is served here. A buyer's order page and a quote page are each opened by a crypto-random token, and that token IS the credential — so the summaries below carry a ref and nothing that opens anything. A caller that needs a quote's buyer link asks GET /quotes/{ref}, where serving it is the point.

Requires orders.view

Query parameters

limit integer

Page size. Default 50, max 200. Non-positive or unparseable values fall back to the default.

after string

Keep the same search and sort when continuing from a cursor; an unknown cursor returns 422.

q string

Match organization, name or email as a substring.

sort string

Sort by newest registration, organization, or name. Keep this value when using after.

Response fields

#

buyers array of BuyerAccount

#

buyers[].ref string

#

buyers[].email string

#

buyers[].name string

#

buyers[].org string

#

buyers[].phone string

The buyer's phone number as it was typed, trimmed and cut to 64 characters. It isn't checked or reformatted. Empty when the buyer has none.

#

buyers[].quote_count integer

Quotes matching this buyer's id OR their email — an anonymous quote is still theirs.

#

buyers[].order_count integer

Orders matching their email, case-insensitively: buyers.email is lowercased on the way in and an order keeps the address as the buyer typed it, so a case-sensitive match once read a registered buyer as having no orders at all.

#

buyers[].part_of string or null

The ref of the buyer this one is part of, like a department's company, or null when it is part of nothing. One level: a buyer others are part of is never part of another.

#

buyers[].kind object or null

The kind a buyer is, or null for none. A kind is a label for finding and filtering buyers; nothing else depends on it. The whole kind is GET /buyer-kinds/{id}.

#

buyers[].kind.id integer

#

buyers[].kind.name string

#

buyers[].created_at string (RFC 3339) or null

#

buyers[].admin_url string

The organizer page, as an absolute URL: on the root admin origin, or on the instance's own address on a standalone instance.

#

buyers[].anonymized_at string (RFC 3339) or null

When the person on this record was anonymized, null while they are still on it. An anonymized record keeps its reference, its place and its money and has no name or address, which this tells apart from one nobody filled in.

#

next_after string or null

Last buyer ref when another page is available; null on the final page.

Responses

• 200A page of buyers.
• 401No key, an unknown key, or a revoked key.
• 403The key does not carry the required capability.
• 422Invalid sort (invalid_sort) or cursor (invalid_after).
• 500Internal error.

curl https://<yourslug>.go.tito.io/api/v1/buyers \
  -H "Authorization: Bearer titogo_sk_your_key"

// Node 18+, Deno, Bun, or a browser on the same origin
const res = await fetch("https://<yourslug>.go.tito.io/api/v1/buyers", {
  method: "GET",
  headers: {
    Authorization: "Bearer titogo_sk_your_key",
  },
});
const data = await res.json();

{
  "buyers": [
    {
      "ref": "b7x9k2",
      "email": "accounts@example.com",
      "name": "Alex Smith",
      "org": "Example Ltd",
      "phone": "+1 202 555 0143",
      "quote_count": 3,
      "order_count": 5,
      "part_of": "k3m8p1",
      "kind": {
        "id": 2,
        "name": "Partners"
      },
      "created_at": "2026-10-14T09:00:00Z",
      "admin_url": "https://example.com/hooks/tito",
      "anonymized_at": null
    }
  ],
  "next_after": "example"
}

Add a buyer

POST /buyers

Add one buyer, the same way a row of the buyer import adds one. The email is trimmed and lowercased, and becomes the buyer's primary contact and first person. Name, organization, phone number and billing identity are optional. Nobody is emailed. An address that is already a buyer's primary contact answers 409 buyer_exists, and the message names that buyer's ref. To add someone to an existing buyer, use POST /buyers/{ref}/people.

Requires orders.manage

Request body

#

email string required

The buyer's primary contact.

#

name string

The primary contact's name.

#

org string

The buyer's organization.

#

phone string

The buyer's phone number, stored as typed.

#

billing object

The new buyer's billing identity, any of the fields. country must be an ISO 3166-1 alpha-2 code or blank.

#

billing.name string

The legal entity an invoice is addressed to. Blank falls back to org when an invoice is rendered.

#

billing.line1 string

#

billing.line2 string

#

billing.city string

#

billing.postcode string

#

billing.subdivision string

County, state or region.

#

billing.country string

ISO 3166-1 alpha-2.

#

billing.vat_number string

#

billing.buyer_reference string

BT-10/Leitweg-ID-style routing reference the buyer gave.

#

billing.po_reference string

A purchase order number the buyer raised.

Response fields

#

ref string

#

email string

#

name string

#

org string

#

phone string

The buyer's phone number as it was typed, trimmed and cut to 64 characters. It isn't checked or reformatted. Empty when the buyer has none.

#

quote_count integer

Quotes matching this buyer's id OR their email — an anonymous quote is still theirs.

#

order_count integer

Orders matching their email, case-insensitively: buyers.email is lowercased on the way in and an order keeps the address as the buyer typed it, so a case-sensitive match once read a registered buyer as having no orders at all.

#

part_of string or null

The ref of the buyer this one is part of, like a department's company, or null when it is part of nothing. One level: a buyer others are part of is never part of another.

#

kind object or null

The kind a buyer is, or null for none. A kind is a label for finding and filtering buyers; nothing else depends on it. The whole kind is GET /buyer-kinds/{id}.

#

kind.id integer

#

kind.name string

#

created_at string (RFC 3339) or null

#

admin_url string

The organizer page, as an absolute URL: on the root admin origin, or on the instance's own address on a standalone instance.

#

anonymized_at string (RFC 3339) or null

When the person on this record was anonymized, null while they are still on it. An anonymized record keeps its reference, its place and its money and has no name or address, which this tells apart from one nobody filled in.

#

stripe_customer_id string

The Customer this buyer is on Stripe, empty until something mints one (the bank-transfer path does it lazily). An identifier, not a credential.

#

people array of BuyerPerson

Everyone who signs in as this buyer, the primary contact first.

#

people[].email string

#

people[].primary boolean

The buyer's primary contact: the address it is listed under, the one invoices and Stripe use. It can't be removed; make someone else primary first (POST /buyers/{ref}/primary).

#

people[].role string

What this person can do when the buyer's quotes need approval: a requester sends a quote for approval, an approver can reject one. Where approval isn't needed the two can do the same things.

one of requesterapprover

#

people[].sees_all boolean

Whether this person sees every one of the buyer's bookings and quotes when they sign in, or only the ones made with their own email address. Only the organizer can change it (POST /buyers/{ref}/people/{email}/sees).

#

domains array of string

The buyer's email domains, sorted, never null. Addresses at exactly these domains belong to the buyer before anybody signs in.

#

terms object or null

The named payment terms a buyer has of its own, or null when it has none. A buyer without terms of its own follows the terms of the buyer it is part of (inherited_terms on the buyer), or else each event's own bank transfer settings. The whole set is GET /payment-terms/{id}.

#

terms.id integer

#

terms.name string

#

inherited_terms object

What a buyer without terms of its own follows: the terms of the buyer it is part of. Null when it has its own, is part of nothing, or that buyer has none either.

#

inherited_terms.id integer

#

inherited_terms.name string

#

includes array of object

Every buyer that is part of this one.

#

includes[].ref string

#

includes[].name string

#

po_required boolean

This buyer's own approval setting: its quotes, and those of every buyer part of it, go to an approver before they can become orders. Always false on a buyer that is part of another, which follows that buyer's; approval says what applies. Set it with POST /buyers/{ref}/po-required.

#

approval object

Approval as it applies to this buyer: required or not, and the buyer whose approvers answer, which is the buyer this one is part of, or else itself.

#

approval.required boolean

#

approval.approver object

#

approval.approver.ref string

#

approval.approver.name string

#

block object

Whether the buyer is blocked from starting new orders and quotes, by its own block or the one on the buyer it is part of. Set it with POST /buyers/{ref}/block and lift it with DELETE /buyers/{ref}/block.

#

block.blocked boolean

#

block.message string

The words emailed to whoever at the buyer tries to order, as plain text, empty for the standard line.

#

block.blocked_at string (RFC 3339) or null

When the block was set, null when the buyer isn't blocked.

#

block.by object or null

The buyer whose block applies: this one, or the one it is part of. Null when the buyer isn't blocked.

#

block.by.ref string

#

block.by.name string

#

spend array of object

What this buyer has actually PAID, per currency: order totals less whatever was refunded off them. A buyer can span currencies across events, so it is a list. A partial refund leaves the order paid and is netted; a full one flips its status and nets to zero either way.

#

spend[].cents integer

#

spend[].currency string

#

quotes array of BuyerQuoteSummary

#

quotes[].ref string

#

quotes[].event_slug string

#

quotes[].status string

open, submitted (sent for approval), rejected (an approver turned it down), imported (converted to an order), expired or canceled.

#

quotes[].amount_cents integer

#

quotes[].currency string

#

quotes[].order_ref string or null

The order this quote became, null while it is still a quote.

#

quotes[].expires_at string (RFC 3339) or null

#

quotes[].created_at string (RFC 3339) or null

#

quotes[].admin_url string

The organizer page, as an absolute URL: on the root admin origin, or on the instance's own address on a standalone instance.

#

orders array of BuyerOrderSummary

#

orders[].ref string

#

orders[].event_slug string

#

orders[].status string

#

orders[].amount_cents integer

#

orders[].currency string

#

orders[].payment_method string

#

orders[].created_at string (RFC 3339) or null

#

orders[].admin_url string

The organizer page, as an absolute URL: on the root admin origin, or on the instance's own address on a standalone instance.

#

bank_transfer object or null

The newest wire-instruction snapshot, null until this buyer has one. Read from the stored row — no Stripe call — because the virtual IBAN is per-Customer, so that row IS the account they pay into. The IBAN is here deliberately: it is the account's own receiving account, printed on the invoice the buyer was already sent, not a secret that opens anything.

#

bank_transfer.reference string

#

bank_transfer.iban string

#

bank_transfer.bic string

#

bank_transfer.account_holder string

#

bank_transfer.bank_country string

#

bank_transfer.amount_cents integer

#

bank_transfer.currency string

#

bank_transfer.status string

awaiting, funded or canceled.

#

bank_transfer.due_at string (RFC 3339) or null

#

bank_details object or null

The bank details Stripe issued this buyer's current Stripe customer, kept on the buyer: the account the buyer pays every bank transfer into, and what its vendor form prints. Null until they are kept, either by POST /buyers/{ref}/bank-details or by the buyer's first Stripe bank transfer. Details kept for a Stripe customer the buyer is no longer linked to are never served. Read from the stored row, with no Stripe call.

#

bank_details.account_holder string

#

bank_details.iban string

#

bank_details.bic string

#

bank_details.bank_country string

Two-letter country code of the bank account.

#

bank_details.currency string

#

billing object

This customer's billing identity, as currently stored (never a computed fallback — a blank name here can still print as org on an invoice).

#

billing.name string

The legal entity an invoice is addressed to. Blank falls back to org when an invoice is rendered.

#

billing.line1 string

#

billing.line2 string

#

billing.city string

#

billing.postcode string

#

billing.subdivision string

County, state or region.

#

billing.country string

ISO 3166-1 alpha-2.

#

billing.vat_number string

#

billing.buyer_reference string

BT-10/Leitweg-ID-style routing reference the buyer gave.

#

billing.po_reference string

A purchase order number the buyer raised.

Responses

• 201The new buyer.
• 401No key, an unknown key, or a revoked key.
• 403The key does not carry the required capability.
• 409The address is already a buyer's primary contact (buyer_exists). The message names that buyer's ref.
• 422The body isn't {"email", "name", "org", "phone", "billing"} (invalid_body), the email is missing or not an email address (invalid_email), or billing.country isn't a valid ISO 3166-1 alpha-2 code (invalid_country).
• 500Internal error.

curl -X POST https://<yourslug>.go.tito.io/api/v1/buyers \
  -H "Authorization: Bearer titogo_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"email":"accounts@example.com"}'

// Node 18+, Deno, Bun, or a browser on the same origin
const res = await fetch("https://<yourslug>.go.tito.io/api/v1/buyers", {
  method: "POST",
  headers: {
    Authorization: "Bearer titogo_sk_your_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "email": "accounts@example.com"
}),
});
const data = await res.json();

{
  "ref": "b7x9k2",
  "email": "accounts@example.com",
  "name": "Alex Smith",
  "org": "Example Ltd",
  "phone": "+1 202 555 0143",
  "quote_count": 3,
  "order_count": 5,
  "part_of": "k3m8p1",
  "kind": {
    "id": 2,
    "name": "Partners"
  },
  "created_at": "2026-10-14T09:00:00Z",
  "admin_url": "https://example.com/hooks/tito",
  "anonymized_at": null,
  "stripe_customer_id": "cus_1MEXAMPLE",
  "people": [
    {
      "email": "accounts@example.com",
      "primary": true,
      "role": "approver",
      "sees_all": true
    }
  ],
  "domains": [
    "example.org"
  ],
  "terms": {
    "id": 3,
    "name": "Members"
  },
  "inherited_terms": {
    "id": 3,
    "name": "Members"
  },
  "includes": [
    {
      "ref": "p2q7r4",
      "name": "Example Ltd Design"
    }
  ],
  "po_required": false,
  "approval": {
    "required": true,
    "approver": {
      "ref": "k3m8p1",
      "name": "Example Ltd"
    }
  },
  "block": {
    "blocked": true,
    "message": "Please settle your outstanding invoices with our accounts team before booking again.",
    "blocked_at": "2026-10-21T11:30:00Z",
    "by": {
      "ref": "k3m8p1",
      "name": "Example Ltd"
    }
  },
  "spend": [
    {
      "cents": 150000,
      "currency": "eur"
    }
  ],
  "quotes": [
    {
      "ref": "H7K2PX",
      "event_slug": "demo",
      "status": "open",
      "amount_cents": 14900,
      "currency": "eur",
      "order_ref": "H7K2PX",
      "expires_at": "2026-10-14T09:00:00Z",
      "created_at": "2026-10-14T09:00:00Z",
      "admin_url": "https://example.com/hooks/tito"
    }
  ],
  "orders": [
    {
      "ref": "H7K2PX",
      "event_slug": "demo",
      "status": "paid",
      "amount_cents": 14900,
      "currency": "eur",
      "payment_method": "example",
      "created_at": "2026-10-14T09:00:00Z",
      "admin_url": "https://example.com/hooks/tito"
    }
  ],
  "bank_transfer": {
    "reference": "RF97TESTREF",
    "iban": "example",
    "bic": "example",
    "account_holder": "Ada Lovelace",
    "bank_country": "example",
    "amount_cents": 14900,
    "currency": "eur",
    "status": "awaiting",
    "due_at": "2026-10-14T09:00:00Z"
  },
  "bank_details": {
    "account_holder": "Stripe Payments Europe",
    "iban": "IE29AIBK93115212345678",
    "bic": "AIBKIE2D",
    "bank_country": "IE",
    "currency": "eur"
  },
  "billing": {
    "name": "St Brigid's NS Board of Management",
    "line1": "12 Main Street",
    "line2": "",
    "city": "Springfield",
    "postcode": "D02 AF30",
    "subdivision": "Co. Dublin",
    "country": "IE",
    "vat_number": "IE1234567T",
    "buyer_reference": "",
    "po_reference": ""
  }
}

Delete a buyer with no quotes or orders

DELETE /buyers/{ref}

Deletes the buyer, with the people and email domains on it. Only a buyer with no quotes, no orders and no Stripe Customer can be deleted, the same rule as the admin's Delete. Anything else answers 409 not_empty; anonymize it instead (POST /buyers/{ref}/anonymize). Buyers that were part of this one stay, each on its own. A blocked buyer's block goes with it.

Requires orders.manage

Path parameters

ref string required

Response fields

#

ref string

#

deleted boolean

Responses

• 200The buyer was deleted.
• 401No key, an unknown key, or a revoked key.
• 403The key does not carry the required capability.
• 404No such resource.
• 409The buyer has quotes, orders or a Stripe Customer (not_empty).
• 500Internal error.

curl -X DELETE https://<yourslug>.go.tito.io/api/v1/buyers/H7K2PX \
  -H "Authorization: Bearer titogo_sk_your_key"

// Node 18+, Deno, Bun, or a browser on the same origin
const res = await fetch("https://<yourslug>.go.tito.io/api/v1/buyers/H7K2PX", {
  method: "DELETE",
  headers: {
    Authorization: "Bearer titogo_sk_your_key",
  },
});
const data = await res.json();

{
  "ref": "b7x9k2",
  "deleted": true
}

Everything for one buyer

GET /buyers/{ref}

The support answer: what this buyer has spent, per currency and net of refunds, with their quotes and orders beside it and — for a buyer Stripe knows — the wire instructions they were given.

No capability token is served here. A buyer's order page and a quote page are each opened by a crypto-random token, and that token IS the credential — so the summaries below carry a ref and nothing that opens anything. A caller that needs a quote's buyer link asks GET /quotes/{ref}, where serving it is the point.

People and payment terms are the writes. people lists everyone who signs in as the buyer; POST /buyers/{ref}/people and DELETE /buyers/{ref}/people/{email} change it. terms is the payment terms the buyer's next invoices are issued under, null for each event's own settings; POST /buyers/{ref}/terms changes it. The rest of a buyer is read-only on every surface.

Requires orders.view

Path parameters

ref string required

Response fields

#

ref string

#

email string

#

name string

#

org string

#

phone string

The buyer's phone number as it was typed, trimmed and cut to 64 characters. It isn't checked or reformatted. Empty when the buyer has none.

#

quote_count integer

Quotes matching this buyer's id OR their email — an anonymous quote is still theirs.

#

order_count integer

Orders matching their email, case-insensitively: buyers.email is lowercased on the way in and an order keeps the address as the buyer typed it, so a case-sensitive match once read a registered buyer as having no orders at all.

#

part_of string or null

The ref of the buyer this one is part of, like a department's company, or null when it is part of nothing. One level: a buyer others are part of is never part of another.

#

kind object or null

The kind a buyer is, or null for none. A kind is a label for finding and filtering buyers; nothing else depends on it. The whole kind is GET /buyer-kinds/{id}.

#

kind.id integer

#

kind.name string

#

created_at string (RFC 3339) or null

#

admin_url string

The organizer page, as an absolute URL: on the root admin origin, or on the instance's own address on a standalone instance.

#

anonymized_at string (RFC 3339) or null

When the person on this record was anonymized, null while they are still on it. An anonymized record keeps its reference, its place and its money and has no name or address, which this tells apart from one nobody filled in.

#

stripe_customer_id string

The Customer this buyer is on Stripe, empty until something mints one (the bank-transfer path does it lazily). An identifier, not a credential.

#

people array of BuyerPerson

Everyone who signs in as this buyer, the primary contact first.

#

people[].email string

#

people[].primary boolean

The buyer's primary contact: the address it is listed under, the one invoices and Stripe use. It can't be removed; make someone else primary first (POST /buyers/{ref}/primary).

#

people[].role string

What this person can do when the buyer's quotes need approval: a requester sends a quote for approval, an approver can reject one. Where approval isn't needed the two can do the same things.

one of requesterapprover

#

people[].sees_all boolean

Whether this person sees every one of the buyer's bookings and quotes when they sign in, or only the ones made with their own email address. Only the organizer can change it (POST /buyers/{ref}/people/{email}/sees).

#

domains array of string

The buyer's email domains, sorted, never null. Addresses at exactly these domains belong to the buyer before anybody signs in.

#

terms object or null

The named payment terms a buyer has of its own, or null when it has none. A buyer without terms of its own follows the terms of the buyer it is part of (inherited_terms on the buyer), or else each event's own bank transfer settings. The whole set is GET /payment-terms/{id}.

#

terms.id integer

#

terms.name string

#

inherited_terms object

What a buyer without terms of its own follows: the terms of the buyer it is part of. Null when it has its own, is part of nothing, or that buyer has none either.

#

inherited_terms.id integer

#

inherited_terms.name string

#

includes array of object

Every buyer that is part of this one.

#

includes[].ref string

#

includes[].name string

#

po_required boolean

This buyer's own approval setting: its quotes, and those of every buyer part of it, go to an approver before they can become orders. Always false on a buyer that is part of another, which follows that buyer's; approval says what applies. Set it with POST /buyers/{ref}/po-required.

#

approval object

Approval as it applies to this buyer: required or not, and the buyer whose approvers answer, which is the buyer this one is part of, or else itself.

#

approval.required boolean

#

approval.approver object

#

approval.approver.ref string

#

approval.approver.name string

#

block object

Whether the buyer is blocked from starting new orders and quotes, by its own block or the one on the buyer it is part of. Set it with POST /buyers/{ref}/block and lift it with DELETE /buyers/{ref}/block.

#

block.blocked boolean

#

block.message string

The words emailed to whoever at the buyer tries to order, as plain text, empty for the standard line.

#

block.blocked_at string (RFC 3339) or null

When the block was set, null when the buyer isn't blocked.

#

block.by object or null

The buyer whose block applies: this one, or the one it is part of. Null when the buyer isn't blocked.

#

block.by.ref string

#

block.by.name string

#

spend array of object

What this buyer has actually PAID, per currency: order totals less whatever was refunded off them. A buyer can span currencies across events, so it is a list. A partial refund leaves the order paid and is netted; a full one flips its status and nets to zero either way.

#

spend[].cents integer

#

spend[].currency string

#

quotes array of BuyerQuoteSummary

#

quotes[].ref string

#

quotes[].event_slug string

#

quotes[].status string

open, submitted (sent for approval), rejected (an approver turned it down), imported (converted to an order), expired or canceled.

#

quotes[].amount_cents integer

#

quotes[].currency string

#

quotes[].order_ref string or null

The order this quote became, null while it is still a quote.

#

quotes[].expires_at string (RFC 3339) or null

#

quotes[].created_at string (RFC 3339) or null

#

quotes[].admin_url string

The organizer page, as an absolute URL: on the root admin origin, or on the instance's own address on a standalone instance.

#

orders array of BuyerOrderSummary

#

orders[].ref string

#

orders[].event_slug string

#

orders[].status string

#

orders[].amount_cents integer

#

orders[].currency string

#

orders[].payment_method string

#

orders[].created_at string (RFC 3339) or null

#

orders[].admin_url string

The organizer page, as an absolute URL: on the root admin origin, or on the instance's own address on a standalone instance.

#

bank_transfer object or null

The newest wire-instruction snapshot, null until this buyer has one. Read from the stored row — no Stripe call — because the virtual IBAN is per-Customer, so that row IS the account they pay into. The IBAN is here deliberately: it is the account's own receiving account, printed on the invoice the buyer was already sent, not a secret that opens anything.

#

bank_transfer.reference string

#

bank_transfer.iban string

#

bank_transfer.bic string

#

bank_transfer.account_holder string

#

bank_transfer.bank_country string

#

bank_transfer.amount_cents integer

#

bank_transfer.currency string

#

bank_transfer.status string

awaiting, funded or canceled.

#

bank_transfer.due_at string (RFC 3339) or null

#

bank_details object or null

The bank details Stripe issued this buyer's current Stripe customer, kept on the buyer: the account the buyer pays every bank transfer into, and what its vendor form prints. Null until they are kept, either by POST /buyers/{ref}/bank-details or by the buyer's first Stripe bank transfer. Details kept for a Stripe customer the buyer is no longer linked to are never served. Read from the stored row, with no Stripe call.

#

bank_details.account_holder string

#

bank_details.iban string

#

bank_details.bic string

#

bank_details.bank_country string

Two-letter country code of the bank account.

#

bank_details.currency string

#

billing object

This customer's billing identity, as currently stored (never a computed fallback — a blank name here can still print as org on an invoice).

#

billing.name string

The legal entity an invoice is addressed to. Blank falls back to org when an invoice is rendered.

#

billing.line1 string

#

billing.line2 string

#

billing.city string

#

billing.postcode string

#

billing.subdivision string

County, state or region.

#

billing.country string

ISO 3166-1 alpha-2.

#

billing.vat_number string

#

billing.buyer_reference string

BT-10/Leitweg-ID-style routing reference the buyer gave.

#

billing.po_reference string

A purchase order number the buyer raised.

Responses

• 200The buyer.
• 401No key, an unknown key, or a revoked key.
• 403The key does not carry the required capability.
• 404No such resource.
• 500Internal error.

curl https://<yourslug>.go.tito.io/api/v1/buyers/H7K2PX \
  -H "Authorization: Bearer titogo_sk_your_key"

// Node 18+, Deno, Bun, or a browser on the same origin
const res = await fetch("https://<yourslug>.go.tito.io/api/v1/buyers/H7K2PX", {
  method: "GET",
  headers: {
    Authorization: "Bearer titogo_sk_your_key",
  },
});
const data = await res.json();

{
  "ref": "b7x9k2",
  "email": "accounts@example.com",
  "name": "Alex Smith",
  "org": "Example Ltd",
  "phone": "+1 202 555 0143",
  "quote_count": 3,
  "order_count": 5,
  "part_of": "k3m8p1",
  "kind": {
    "id": 2,
    "name": "Partners"
  },
  "created_at": "2026-10-14T09:00:00Z",
  "admin_url": "https://example.com/hooks/tito",
  "anonymized_at": null,
  "stripe_customer_id": "cus_1MEXAMPLE",
  "people": [
    {
      "email": "accounts@example.com",
      "primary": true,
      "role": "approver",
      "sees_all": true
    }
  ],
  "domains": [
    "example.org"
  ],
  "terms": {
    "id": 3,
    "name": "Members"
  },
  "inherited_terms": {
    "id": 3,
    "name": "Members"
  },
  "includes": [
    {
      "ref": "p2q7r4",
      "name": "Example Ltd Design"
    }
  ],
  "po_required": false,
  "approval": {
    "required": true,
    "approver": {
      "ref": "k3m8p1",
      "name": "Example Ltd"
    }
  },
  "block": {
    "blocked": true,
    "message": "Please settle your outstanding invoices with our accounts team before booking again.",
    "blocked_at": "2026-10-21T11:30:00Z",
    "by": {
      "ref": "k3m8p1",
      "name": "Example Ltd"
    }
  },
  "spend": [
    {
      "cents": 150000,
      "currency": "eur"
    }
  ],
  "quotes": [
    {
      "ref": "H7K2PX",
      "event_slug": "demo",
      "status": "open",
      "amount_cents": 14900,
      "currency": "eur",
      "order_ref": "H7K2PX",
      "expires_at": "2026-10-14T09:00:00Z",
      "created_at": "2026-10-14T09:00:00Z",
      "admin_url": "https://example.com/hooks/tito"
    }
  ],
  "orders": [
    {
      "ref": "H7K2PX",
      "event_slug": "demo",
      "status": "paid",
      "amount_cents": 14900,
      "currency": "eur",
      "payment_method": "example",
      "created_at": "2026-10-14T09:00:00Z",
      "admin_url": "https://example.com/hooks/tito"
    }
  ],
  "bank_transfer": {
    "reference": "RF97TESTREF",
    "iban": "example",
    "bic": "example",
    "account_holder": "Ada Lovelace",
    "bank_country": "example",
    "amount_cents": 14900,
    "currency": "eur",
    "status": "awaiting",
    "due_at": "2026-10-14T09:00:00Z"
  },
  "bank_details": {
    "account_holder": "Stripe Payments Europe",
    "iban": "IE29AIBK93115212345678",
    "bic": "AIBKIE2D",
    "bank_country": "IE",
    "currency": "eur"
  },
  "billing": {
    "name": "St Brigid's NS Board of Management",
    "line1": "12 Main Street",
    "line2": "",
    "city": "Springfield",
    "postcode": "D02 AF30",
    "subdivision": "Co. Dublin",
    "country": "IE",
    "vat_number": "IE1234567T",
    "buyer_reference": "",
    "po_reference": ""
  }
}

Change a buyer's name, organization, phone number or billing identity

PATCH /buyers/{ref}

Sets the buyer's own name, organization, phone number and billing identity, any of them. An empty phone clears it; billing fields follow the same per-field set/clear/leave-alone rule. The primary contact's email is not changed here. An already-issued bank-transfer invoice keeps the name, organization and billing address it was issued with.

Requires orders.manage

Path parameters

ref string required

Request body

#

name string

#

org string

#

phone string

#

billing object

Any of the billing fields, patched one at a time: a field absent from billing leaves its column alone, present with a value sets it, present as "" clears it. country must be an ISO 3166-1 alpha-2 code or blank.

#

billing.name string

The legal entity an invoice is addressed to. Blank falls back to org when an invoice is rendered.

#

billing.line1 string

#

billing.line2 string

#

billing.city string

#

billing.postcode string

#

billing.subdivision string

County, state or region.

#

billing.country string

ISO 3166-1 alpha-2.

#

billing.vat_number string

#

billing.buyer_reference string

BT-10/Leitweg-ID-style routing reference the buyer gave.

#

billing.po_reference string

A purchase order number the buyer raised.

Response fields

#

ref string

#

email string

#

name string

#

org string

#

phone string

The buyer's phone number as it was typed, trimmed and cut to 64 characters. It isn't checked or reformatted. Empty when the buyer has none.

#

quote_count integer

Quotes matching this buyer's id OR their email — an anonymous quote is still theirs.

#

order_count integer

Orders matching their email, case-insensitively: buyers.email is lowercased on the way in and an order keeps the address as the buyer typed it, so a case-sensitive match once read a registered buyer as having no orders at all.

#

part_of string or null

The ref of the buyer this one is part of, like a department's company, or null when it is part of nothing. One level: a buyer others are part of is never part of another.

#

kind object or null

The kind a buyer is, or null for none. A kind is a label for finding and filtering buyers; nothing else depends on it. The whole kind is GET /buyer-kinds/{id}.

#

kind.id integer

#

kind.name string

#

created_at string (RFC 3339) or null

#

admin_url string

The organizer page, as an absolute URL: on the root admin origin, or on the instance's own address on a standalone instance.

#

anonymized_at string (RFC 3339) or null

When the person on this record was anonymized, null while they are still on it. An anonymized record keeps its reference, its place and its money and has no name or address, which this tells apart from one nobody filled in.

#

stripe_customer_id string

The Customer this buyer is on Stripe, empty until something mints one (the bank-transfer path does it lazily). An identifier, not a credential.

#

people array of BuyerPerson

Everyone who signs in as this buyer, the primary contact first.

#

people[].email string

#

people[].primary boolean

The buyer's primary contact: the address it is listed under, the one invoices and Stripe use. It can't be removed; make someone else primary first (POST /buyers/{ref}/primary).

#

people[].role string

What this person can do when the buyer's quotes need approval: a requester sends a quote for approval, an approver can reject one. Where approval isn't needed the two can do the same things.

one of requesterapprover

#

people[].sees_all boolean

Whether this person sees every one of the buyer's bookings and quotes when they sign in, or only the ones made with their own email address. Only the organizer can change it (POST /buyers/{ref}/people/{email}/sees).

#

domains array of string

The buyer's email domains, sorted, never null. Addresses at exactly these domains belong to the buyer before anybody signs in.

#

terms object or null

The named payment terms a buyer has of its own, or null when it has none. A buyer without terms of its own follows the terms of the buyer it is part of (inherited_terms on the buyer), or else each event's own bank transfer settings. The whole set is GET /payment-terms/{id}.

#

terms.id integer

#

terms.name string

#

inherited_terms object

What a buyer without terms of its own follows: the terms of the buyer it is part of. Null when it has its own, is part of nothing, or that buyer has none either.

#

inherited_terms.id integer

#

inherited_terms.name string

#

includes array of object

Every buyer that is part of this one.

#

includes[].ref string

#

includes[].name string

#

po_required boolean

This buyer's own approval setting: its quotes, and those of every buyer part of it, go to an approver before they can become orders. Always false on a buyer that is part of another, which follows that buyer's; approval says what applies. Set it with POST /buyers/{ref}/po-required.

#

approval object

Approval as it applies to this buyer: required or not, and the buyer whose approvers answer, which is the buyer this one is part of, or else itself.

#

approval.required boolean

#

approval.approver object

#

approval.approver.ref string

#

approval.approver.name string

#

block object

Whether the buyer is blocked from starting new orders and quotes, by its own block or the one on the buyer it is part of. Set it with POST /buyers/{ref}/block and lift it with DELETE /buyers/{ref}/block.

#

block.blocked boolean

#

block.message string

The words emailed to whoever at the buyer tries to order, as plain text, empty for the standard line.

#

block.blocked_at string (RFC 3339) or null

When the block was set, null when the buyer isn't blocked.

#

block.by object or null

The buyer whose block applies: this one, or the one it is part of. Null when the buyer isn't blocked.

#

block.by.ref string

#

block.by.name string

#

spend array of object

What this buyer has actually PAID, per currency: order totals less whatever was refunded off them. A buyer can span currencies across events, so it is a list. A partial refund leaves the order paid and is netted; a full one flips its status and nets to zero either way.

#

spend[].cents integer

#

spend[].currency string

#

quotes array of BuyerQuoteSummary

#

quotes[].ref string

#

quotes[].event_slug string

#

quotes[].status string

open, submitted (sent for approval), rejected (an approver turned it down), imported (converted to an order), expired or canceled.

#

quotes[].amount_cents integer

#

quotes[].currency string

#

quotes[].order_ref string or null

The order this quote became, null while it is still a quote.

#

quotes[].expires_at string (RFC 3339) or null

#

quotes[].created_at string (RFC 3339) or null

#

quotes[].admin_url string

The organizer page, as an absolute URL: on the root admin origin, or on the instance's own address on a standalone instance.

#

orders array of BuyerOrderSummary

#

orders[].ref string

#

orders[].event_slug string

#

orders[].status string

#

orders[].amount_cents integer

#

orders[].currency string

#

orders[].payment_method string

#

orders[].created_at string (RFC 3339) or null

#

orders[].admin_url string

The organizer page, as an absolute URL: on the root admin origin, or on the instance's own address on a standalone instance.

#

bank_transfer object or null

The newest wire-instruction snapshot, null until this buyer has one. Read from the stored row — no Stripe call — because the virtual IBAN is per-Customer, so that row IS the account they pay into. The IBAN is here deliberately: it is the account's own receiving account, printed on the invoice the buyer was already sent, not a secret that opens anything.

#

bank_transfer.reference string

#

bank_transfer.iban string

#

bank_transfer.bic string

#

bank_transfer.account_holder string

#

bank_transfer.bank_country string

#

bank_transfer.amount_cents integer

#

bank_transfer.currency string

#

bank_transfer.status string

awaiting, funded or canceled.

#

bank_transfer.due_at string (RFC 3339) or null

#

bank_details object or null

The bank details Stripe issued this buyer's current Stripe customer, kept on the buyer: the account the buyer pays every bank transfer into, and what its vendor form prints. Null until they are kept, either by POST /buyers/{ref}/bank-details or by the buyer's first Stripe bank transfer. Details kept for a Stripe customer the buyer is no longer linked to are never served. Read from the stored row, with no Stripe call.

#

bank_details.account_holder string

#

bank_details.iban string

#

bank_details.bic string

#

bank_details.bank_country string

Two-letter country code of the bank account.

#

bank_details.currency string

#

billing object

This customer's billing identity, as currently stored (never a computed fallback — a blank name here can still print as org on an invoice).

#

billing.name string

The legal entity an invoice is addressed to. Blank falls back to org when an invoice is rendered.

#

billing.line1 string

#

billing.line2 string

#

billing.city string

#

billing.postcode string

#

billing.subdivision string

County, state or region.

#

billing.country string

ISO 3166-1 alpha-2.

#

billing.vat_number string

#

billing.buyer_reference string

BT-10/Leitweg-ID-style routing reference the buyer gave.

#

billing.po_reference string

A purchase order number the buyer raised.

Responses

• 200The buyer as it now stands.
• 401No key, an unknown key, or a revoked key.
• 403The key does not carry the required capability.
• 404No such resource.
• 422The body carries none of name, org, phone and billing, or a key that isn't one of them (invalid_body), or billing.country isn't a valid ISO 3166-1 alpha-2 code (invalid_country).
• 500Internal error.

curl -X PATCH https://<yourslug>.go.tito.io/api/v1/buyers/H7K2PX \
  -H "Authorization: Bearer titogo_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name":"Alex Smith"}'

// Node 18+, Deno, Bun, or a browser on the same origin
const res = await fetch("https://<yourslug>.go.tito.io/api/v1/buyers/H7K2PX", {
  method: "PATCH",
  headers: {
    Authorization: "Bearer titogo_sk_your_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "name": "Alex Smith"
}),
});
const data = await res.json();

{
  "ref": "b7x9k2",
  "email": "accounts@example.com",
  "name": "Alex Smith",
  "org": "Example Ltd",
  "phone": "+1 202 555 0143",
  "quote_count": 3,
  "order_count": 5,
  "part_of": "k3m8p1",
  "kind": {
    "id": 2,
    "name": "Partners"
  },
  "created_at": "2026-10-14T09:00:00Z",
  "admin_url": "https://example.com/hooks/tito",
  "anonymized_at": null,
  "stripe_customer_id": "cus_1MEXAMPLE",
  "people": [
    {
      "email": "accounts@example.com",
      "primary": true,
      "role": "approver",
      "sees_all": true
    }
  ],
  "domains": [
    "example.org"
  ],
  "terms": {
    "id": 3,
    "name": "Members"
  },
  "inherited_terms": {
    "id": 3,
    "name": "Members"
  },
  "includes": [
    {
      "ref": "p2q7r4",
      "name": "Example Ltd Design"
    }
  ],
  "po_required": false,
  "approval": {
    "required": true,
    "approver": {
      "ref": "k3m8p1",
      "name": "Example Ltd"
    }
  },
  "block": {
    "blocked": true,
    "message": "Please settle your outstanding invoices with our accounts team before booking again.",
    "blocked_at": "2026-10-21T11:30:00Z",
    "by": {
      "ref": "k3m8p1",
      "name": "Example Ltd"
    }
  },
  "spend": [
    {
      "cents": 150000,
      "currency": "eur"
    }
  ],
  "quotes": [
    {
      "ref": "H7K2PX",
      "event_slug": "demo",
      "status": "open",
      "amount_cents": 14900,
      "currency": "eur",
      "order_ref": "H7K2PX",
      "expires_at": "2026-10-14T09:00:00Z",
      "created_at": "2026-10-14T09:00:00Z",
      "admin_url": "https://example.com/hooks/tito"
    }
  ],
  "orders": [
    {
      "ref": "H7K2PX",
      "event_slug": "demo",
      "status": "paid",
      "amount_cents": 14900,
      "currency": "eur",
      "payment_method": "example",
      "created_at": "2026-10-14T09:00:00Z",
      "admin_url": "https://example.com/hooks/tito"
    }
  ],
  "bank_transfer": {
    "reference": "RF97TESTREF",
    "iban": "example",
    "bic": "example",
    "account_holder": "Ada Lovelace",
    "bank_country": "example",
    "amount_cents": 14900,
    "currency": "eur",
    "status": "awaiting",
    "due_at": "2026-10-14T09:00:00Z"
  },
  "bank_details": {
    "account_holder": "Stripe Payments Europe",
    "iban": "IE29AIBK93115212345678",
    "bic": "AIBKIE2D",
    "bank_country": "IE",
    "currency": "eur"
  },
  "billing": {
    "name": "St Brigid's NS Board of Management",
    "line1": "12 Main Street",
    "line2": "",
    "city": "Springfield",
    "postcode": "D02 AF30",
    "subdivision": "Co. Dublin",
    "country": "IE",
    "vat_number": "IE1234567T",
    "buyer_reference": "",
    "po_reference": ""
  }
}

Anonymize a customer

POST /buyers/{ref}/anonymize

Remove a customer: its name, email address, organization, phone number and billing address, its people and email domains, its bank details and letters, and the buyer details on every order and quote it placed. The attendees on those orders are not changed: they are often other people. An agent limited to some events cannot call this. It happens at once and cannot be undone, the API's copy of the admin's Anonymize confirm step, which runs the same code. What stays: the record itself with its reference, status and place in every count, what was bought and paid and when, the payment reference, and every invoice, receipt and credit note already issued, exactly as issued. Copies of the person in sent emails, the record's history, its webhook deliveries, workflow runs and the API request log are cleared too. What Tito cannot reach is named in outside_tito: the payment provider's own record, connected services the person was sent to, and whatever your webhooks already delivered. Every call writes a line to the data-protection log (GET /data-protection-log) that names the record's reference and never the person. The link tags its orders arrived with go too, ad click ids and your own tags included, except utm_* campaign tags, which stay so the order still counts toward the link that sold it. Send no request body; any body is ignored. An order still waiting for a bank transfer is canceled first, so a payment that arrives later cannot fulfil it; one whose tickets were already issued is left as it is.

Requires erasure

Path parameters

ref string required

The customer's ref.

Response fields

#

anonymized boolean

one of true

#

kind string

one of ticketorderinvitationbuyerwaitlistapplication

#

ref string

The record's reference: a ticket, order, customer, waitlist entry or ticket request ref, or the invitation's id.

#

anonymized_at string (RFC 3339)

#

removed object

#

removed.tickets integer

Tickets whose holder was removed.

#

removed.orders integer

Orders whose buyer details were removed.

#

removed.quotes integer

Quotes whose buyer details were removed.

#

removed.answers integer

Answers to questions removed.

#

removed.files integer

Files sent with the answers, deleted.

#

removed.emails integer

Sent emails whose address and words were removed. The record that each was sent stays.

#

removed.contact boolean

Their entry in Contacts was deleted.

#

removed.waitlist boolean

Their name and address on the waitlist were removed.

#

removed.ticket_request boolean

Their name and address on their ticket request were removed.

#

removed.link_tags integer

Orders whose link tags were removed: every tag that isn't a utm_* campaign tag, ad click ids included.

#

removed.interest boolean

Their email address was taken off the mailing list, where they signed up to hear when tickets go on sale.

#

removed.card boolean

A card saved with a ticket request this withdrew, which Stripe was asked to delete.

#

kept object

#

kept.documents integer

Invoices, receipts and credit notes already issued, kept exactly as issued.

#

kept.other_records integer

Other orders, tickets and invitations with the same email address, which are not changed.

#

kept.customer string or null

The customer record an anonymized order is linked to, which is not changed.

#

kept.campaign_tags integer

Orders whose utm_* campaign tags were kept, so they still count toward the link that sold them.

#

kept.order string or null

The order a waitlist place was taken with, or that a ticket request's invitation was claimed with, which is not changed.

#

kept.ticket string or null

The ticket a workshop waitlist entry joined from, which is not changed.

#

kept.invitation integer or null

The invitation a ticket request was approved into, which is not changed.

#

outside_tito object

#

outside_tito.payment_provider string or null

The provider that keeps its own record of the payment, with the buyer's name and email address.

one of StripePayPal<nil>

#

outside_tito.services array of string

Connected services the person's details were sent to, which keep their own copy.

#

outside_tito.webhooks boolean

A webhook already delivered their details.

#

outside_tito.card boolean

A card saved with a ticket request that was already decided, which Stripe keeps.

Responses

• 200The customer is anonymized.
• 401No key, an unknown key, or a revoked key.
• 403The key does not carry the required capability.
• 404No such resource.
• 409The person on this record has already been anonymized (already_anonymized). Nothing changes.
• 500Internal error.

curl -X POST https://<yourslug>.go.tito.io/api/v1/buyers/H7K2PX/anonymize \
  -H "Authorization: Bearer titogo_sk_your_key"

// Node 18+, Deno, Bun, or a browser on the same origin
const res = await fetch("https://<yourslug>.go.tito.io/api/v1/buyers/H7K2PX/anonymize", {
  method: "POST",
  headers: {
    Authorization: "Bearer titogo_sk_your_key",
  },
});
const data = await res.json();

{
  "anonymized": true,
  "kind": "ticket",
  "ref": "H7K2PX",
  "anonymized_at": "2026-10-14T09:00:00Z",
  "removed": {
    "tickets": 1,
    "orders": 1,
    "quotes": 1,
    "answers": 1,
    "files": 1,
    "emails": 1,
    "contact": true,
    "waitlist": true,
    "ticket_request": true,
    "link_tags": 1,
    "interest": true,
    "card": true
  },
  "kept": {
    "documents": 1,
    "other_records": 1,
    "customer": "example",
    "campaign_tags": 1,
    "order": "H7K2PX",
    "ticket": "T9QW4M",
    "invitation": 1
  },
  "outside_tito": {
    "payment_provider": "Stripe",
    "services": [
      "example"
    ],
    "webhooks": true,
    "card": true
  }
}

Get a buyer's bank details from Stripe

POST /buyers/{ref}/bank-details

Ask Stripe for the bank details it issues this buyer's Stripe customer, the account the buyer pays bank transfers into, and keep them on the buyer. They then show on the buyer's page, print on its vendor form, and appear as bank_details on the buyer. A buyer with no Stripe customer yet is added to the account's Stripe first. No body.

Calling it for a buyer whose bank details are already kept for its current Stripe customer changes nothing and doesn't call Stripe. Nothing is kept if Stripe can't be reached or refuses. Asking Stripe can create the account details the first time, which is why this is a POST and nothing that reads a buyer ever calls it.

Stripe allows each account up to 1,000 of these account details. Once Tito keeps bank details for 900 buyers on an account, it stops asking Stripe for new ones (409 bank_details_limit), so the rest stay free for buyers paying by bank transfer at checkout. Bank details a buyer already has can still be asked for again.

Requires payment.manage

Path parameters

ref string required

Response fields

#

ref string

#

email string

#

name string

#

org string

#

phone string

The buyer's phone number as it was typed, trimmed and cut to 64 characters. It isn't checked or reformatted. Empty when the buyer has none.

#

quote_count integer

Quotes matching this buyer's id OR their email — an anonymous quote is still theirs.

#

order_count integer

Orders matching their email, case-insensitively: buyers.email is lowercased on the way in and an order keeps the address as the buyer typed it, so a case-sensitive match once read a registered buyer as having no orders at all.

#

part_of string or null

The ref of the buyer this one is part of, like a department's company, or null when it is part of nothing. One level: a buyer others are part of is never part of another.

#

kind object or null

The kind a buyer is, or null for none. A kind is a label for finding and filtering buyers; nothing else depends on it. The whole kind is GET /buyer-kinds/{id}.

#

kind.id integer

#

kind.name string

#

created_at string (RFC 3339) or null

#

admin_url string

The organizer page, as an absolute URL: on the root admin origin, or on the instance's own address on a standalone instance.

#

anonymized_at string (RFC 3339) or null

When the person on this record was anonymized, null while they are still on it. An anonymized record keeps its reference, its place and its money and has no name or address, which this tells apart from one nobody filled in.

#

stripe_customer_id string

The Customer this buyer is on Stripe, empty until something mints one (the bank-transfer path does it lazily). An identifier, not a credential.

#

people array of BuyerPerson

Everyone who signs in as this buyer, the primary contact first.

#

people[].email string

#

people[].primary boolean

The buyer's primary contact: the address it is listed under, the one invoices and Stripe use. It can't be removed; make someone else primary first (POST /buyers/{ref}/primary).

#

people[].role string

What this person can do when the buyer's quotes need approval: a requester sends a quote for approval, an approver can reject one. Where approval isn't needed the two can do the same things.

one of requesterapprover

#

people[].sees_all boolean

Whether this person sees every one of the buyer's bookings and quotes when they sign in, or only the ones made with their own email address. Only the organizer can change it (POST /buyers/{ref}/people/{email}/sees).

#

domains array of string

The buyer's email domains, sorted, never null. Addresses at exactly these domains belong to the buyer before anybody signs in.

#

terms object or null

The named payment terms a buyer has of its own, or null when it has none. A buyer without terms of its own follows the terms of the buyer it is part of (inherited_terms on the buyer), or else each event's own bank transfer settings. The whole set is GET /payment-terms/{id}.

#

terms.id integer

#

terms.name string

#

inherited_terms object

What a buyer without terms of its own follows: the terms of the buyer it is part of. Null when it has its own, is part of nothing, or that buyer has none either.

#

inherited_terms.id integer

#

inherited_terms.name string

#

includes array of object

Every buyer that is part of this one.

#

includes[].ref string

#

includes[].name string

#

po_required boolean

This buyer's own approval setting: its quotes, and those of every buyer part of it, go to an approver before they can become orders. Always false on a buyer that is part of another, which follows that buyer's; approval says what applies. Set it with POST /buyers/{ref}/po-required.

#

approval object

Approval as it applies to this buyer: required or not, and the buyer whose approvers answer, which is the buyer this one is part of, or else itself.

#

approval.required boolean

#

approval.approver object

#

approval.approver.ref string

#

approval.approver.name string

#

block object

Whether the buyer is blocked from starting new orders and quotes, by its own block or the one on the buyer it is part of. Set it with POST /buyers/{ref}/block and lift it with DELETE /buyers/{ref}/block.

#

block.blocked boolean

#

block.message string

The words emailed to whoever at the buyer tries to order, as plain text, empty for the standard line.

#

block.blocked_at string (RFC 3339) or null

When the block was set, null when the buyer isn't blocked.

#

block.by object or null

The buyer whose block applies: this one, or the one it is part of. Null when the buyer isn't blocked.

#

block.by.ref string

#

block.by.name string

#

spend array of object

What this buyer has actually PAID, per currency: order totals less whatever was refunded off them. A buyer can span currencies across events, so it is a list. A partial refund leaves the order paid and is netted; a full one flips its status and nets to zero either way.

#

spend[].cents integer

#

spend[].currency string

#

quotes array of BuyerQuoteSummary

#

quotes[].ref string

#

quotes[].event_slug string

#

quotes[].status string

open, submitted (sent for approval), rejected (an approver turned it down), imported (converted to an order), expired or canceled.

#

quotes[].amount_cents integer

#

quotes[].currency string

#

quotes[].order_ref string or null

The order this quote became, null while it is still a quote.

#

quotes[].expires_at string (RFC 3339) or null

#

quotes[].created_at string (RFC 3339) or null

#

quotes[].admin_url string

The organizer page, as an absolute URL: on the root admin origin, or on the instance's own address on a standalone instance.

#

orders array of BuyerOrderSummary

#

orders[].ref string

#

orders[].event_slug string

#

orders[].status string

#

orders[].amount_cents integer

#

orders[].currency string

#

orders[].payment_method string

#

orders[].created_at string (RFC 3339) or null

#

orders[].admin_url string

The organizer page, as an absolute URL: on the root admin origin, or on the instance's own address on a standalone instance.

#

bank_transfer object or null

The newest wire-instruction snapshot, null until this buyer has one. Read from the stored row — no Stripe call — because the virtual IBAN is per-Customer, so that row IS the account they pay into. The IBAN is here deliberately: it is the account's own receiving account, printed on the invoice the buyer was already sent, not a secret that opens anything.

#

bank_transfer.reference string

#

bank_transfer.iban string

#

bank_transfer.bic string

#

bank_transfer.account_holder string

#

bank_transfer.bank_country string

#

bank_transfer.amount_cents integer

#

bank_transfer.currency string

#

bank_transfer.status string

awaiting, funded or canceled.

#

bank_transfer.due_at string (RFC 3339) or null

#

bank_details object or null

The bank details Stripe issued this buyer's current Stripe customer, kept on the buyer: the account the buyer pays every bank transfer into, and what its vendor form prints. Null until they are kept, either by POST /buyers/{ref}/bank-details or by the buyer's first Stripe bank transfer. Details kept for a Stripe customer the buyer is no longer linked to are never served. Read from the stored row, with no Stripe call.

#

bank_details.account_holder string

#

bank_details.iban string

#

bank_details.bic string

#

bank_details.bank_country string

Two-letter country code of the bank account.

#

bank_details.currency string

#

billing object

This customer's billing identity, as currently stored (never a computed fallback — a blank name here can still print as org on an invoice).

#

billing.name string

The legal entity an invoice is addressed to. Blank falls back to org when an invoice is rendered.

#

billing.line1 string

#

billing.line2 string

#

billing.city string

#

billing.postcode string

#

billing.subdivision string

County, state or region.

#

billing.country string

ISO 3166-1 alpha-2.

#

billing.vat_number string

#

billing.buyer_reference string

BT-10/Leitweg-ID-style routing reference the buyer gave.

#

billing.po_reference string

A purchase order number the buyer raised.

Responses

• 200The buyer as it now stands, with its bank_details.
• 401No key, an unknown key, or a revoked key.
• 403The key does not carry the required capability.
• 404No such resource.
• 409The account has no Stripe connection (not_connected), no event takes bank transfers on the Stripe rail so Stripe issues its buyers no bank details (manual_rail), the account's Stripe has no customer with the buyer's stripe_customer_id (stripe_customer_missing), the buyer's Stripe customer changed while the request was in flight (stripe_customer_moved), or the account already keeps bank details for 900 buyers (bank_details_limit). Nothing is kept.
• 500Internal error.
• 502Stripe couldn't be asked, and nothing was kept (stripe_unavailable). Safe to retry. Stripe refusing this account's request answers stripe_refused instead; check the account's Stripe connection before retrying.

curl -X POST https://<yourslug>.go.tito.io/api/v1/buyers/H7K2PX/bank-details \
  -H "Authorization: Bearer titogo_sk_your_key"

// Node 18+, Deno, Bun, or a browser on the same origin
const res = await fetch("https://<yourslug>.go.tito.io/api/v1/buyers/H7K2PX/bank-details", {
  method: "POST",
  headers: {
    Authorization: "Bearer titogo_sk_your_key",
  },
});
const data = await res.json();

{
  "ref": "b7x9k2",
  "email": "accounts@example.com",
  "name": "Alex Smith",
  "org": "Example Ltd",
  "phone": "+1 202 555 0143",
  "quote_count": 3,
  "order_count": 5,
  "part_of": "k3m8p1",
  "kind": {
    "id": 2,
    "name": "Partners"
  },
  "created_at": "2026-10-14T09:00:00Z",
  "admin_url": "https://example.com/hooks/tito",
  "anonymized_at": null,
  "stripe_customer_id": "cus_1MEXAMPLE",
  "people": [
    {
      "email": "accounts@example.com",
      "primary": true,
      "role": "approver",
      "sees_all": true
    }
  ],
  "domains": [
    "example.org"
  ],
  "terms": {
    "id": 3,
    "name": "Members"
  },
  "inherited_terms": {
    "id": 3,
    "name": "Members"
  },
  "includes": [
    {
      "ref": "p2q7r4",
      "name": "Example Ltd Design"
    }
  ],
  "po_required": false,
  "approval": {
    "required": true,
    "approver": {
      "ref": "k3m8p1",
      "name": "Example Ltd"
    }
  },
  "block": {
    "blocked": true,
    "message": "Please settle your outstanding invoices with our accounts team before booking again.",
    "blocked_at": "2026-10-21T11:30:00Z",
    "by": {
      "ref": "k3m8p1",
      "name": "Example Ltd"
    }
  },
  "spend": [
    {
      "cents": 150000,
      "currency": "eur"
    }
  ],
  "quotes": [
    {
      "ref": "H7K2PX",
      "event_slug": "demo",
      "status": "open",
      "amount_cents": 14900,
      "currency": "eur",
      "order_ref": "H7K2PX",
      "expires_at": "2026-10-14T09:00:00Z",
      "created_at": "2026-10-14T09:00:00Z",
      "admin_url": "https://example.com/hooks/tito"
    }
  ],
  "orders": [
    {
      "ref": "H7K2PX",
      "event_slug": "demo",
      "status": "paid",
      "amount_cents": 14900,
      "currency": "eur",
      "payment_method": "example",
      "created_at": "2026-10-14T09:00:00Z",
      "admin_url": "https://example.com/hooks/tito"
    }
  ],
  "bank_transfer": {
    "reference": "RF97TESTREF",
    "iban": "example",
    "bic": "example",
    "account_holder": "Ada Lovelace",
    "bank_country": "example",
    "amount_cents": 14900,
    "currency": "eur",
    "status": "awaiting",
    "due_at": "2026-10-14T09:00:00Z"
  },
  "bank_details": {
    "account_holder": "Stripe Payments Europe",
    "iban": "IE29AIBK93115212345678",
    "bic": "AIBKIE2D",
    "bank_country": "IE",
    "currency": "eur"
  },
  "billing": {
    "name": "St Brigid's NS Board of Management",
    "line1": "12 Main Street",
    "line2": "",
    "city": "Springfield",
    "postcode": "D02 AF30",
    "subdivision": "Co. Dublin",
    "country": "IE",
    "vat_number": "IE1234567T",
    "buyer_reference": "",
    "po_reference": ""
  }
}

Unblock a buyer

DELETE /buyers/{ref}/block

Removes the buyer's own block, so its people can place orders and generate quotes again. A block on the buyer it is part of still applies, and the answer says so.

Requires orders.manage

Path parameters

ref string required

Response fields

#

block object

Whether the buyer is blocked from starting new orders and quotes, by its own block or the one on the buyer it is part of. Set it with POST /buyers/{ref}/block and lift it with DELETE /buyers/{ref}/block.

#

block.blocked boolean

#

block.message string

The words emailed to whoever at the buyer tries to order, as plain text, empty for the standard line.

#

block.blocked_at string (RFC 3339) or null

When the block was set, null when the buyer isn't blocked.

#

block.by object or null

The buyer whose block applies: this one, or the one it is part of. Null when the buyer isn't blocked.

#

block.by.ref string

#

block.by.name string

Responses

• 200The block as it now applies to the buyer.
• 401No key, an unknown key, or a revoked key.
• 403The key does not carry the required capability.
• 404No such resource.
• 500Internal error.

curl -X DELETE https://<yourslug>.go.tito.io/api/v1/buyers/H7K2PX/block \
  -H "Authorization: Bearer titogo_sk_your_key"

// Node 18+, Deno, Bun, or a browser on the same origin
const res = await fetch("https://<yourslug>.go.tito.io/api/v1/buyers/H7K2PX/block", {
  method: "DELETE",
  headers: {
    Authorization: "Bearer titogo_sk_your_key",
  },
});
const data = await res.json();

{
  "block": {
    "blocked": true,
    "message": "Please settle your outstanding invoices with our accounts team before booking again.",
    "blocked_at": "2026-10-21T11:30:00Z",
    "by": {
      "ref": "k3m8p1",
      "name": "Example Ltd"
    }
  }
}

Block a buyer from new orders and quotes

POST /buyers/{ref}/block

While a buyer is blocked, its people can't place a new order or generate a quote, whichever way they pay, free orders included. They can still pay for orders already placed, and you can still make orders for the buyer yourself. A buyer that is part of this one is blocked too. Someone is recognized as the buyer's when they're signed in as it, or check out with an address on its people or at one of its email domains. message is emailed to whoever tries, as plain text (formatting is set on the customer's page); leave it out or empty for the standard line. Posting again to a blocked buyer changes the message and keeps blocked_at.

Requires orders.manage

Path parameters

ref string required

Request body

#

message string

Response fields

#

block object

Whether the buyer is blocked from starting new orders and quotes, by its own block or the one on the buyer it is part of. Set it with POST /buyers/{ref}/block and lift it with DELETE /buyers/{ref}/block.

#

block.blocked boolean

#

block.message string

The words emailed to whoever at the buyer tries to order, as plain text, empty for the standard line.

#

block.blocked_at string (RFC 3339) or null

When the block was set, null when the buyer isn't blocked.

#

block.by object or null

The buyer whose block applies: this one, or the one it is part of. Null when the buyer isn't blocked.

#

block.by.ref string

#

block.by.name string

Responses

• 200The block as it now applies to the buyer.
• 401No key, an unknown key, or a revoked key.
• 403The key does not carry the required capability.
• 404No such resource.
• 409The buyer has been anonymized (anonymized).
• 422The body isn't an object with an optional message (invalid_body), or the message is over 1000 characters (message_too_long).
• 500Internal error.

curl -X POST https://<yourslug>.go.tito.io/api/v1/buyers/H7K2PX/block \
  -H "Authorization: Bearer titogo_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"message":"Please settle your outstanding invoices with our accounts team before booking again."}'

// Node 18+, Deno, Bun, or a browser on the same origin
const res = await fetch("https://<yourslug>.go.tito.io/api/v1/buyers/H7K2PX/block", {
  method: "POST",
  headers: {
    Authorization: "Bearer titogo_sk_your_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "message": "Please settle your outstanding invoices with our accounts team before booking again."
}),
});
const data = await res.json();

{
  "block": {
    "blocked": true,
    "message": "Please settle your outstanding invoices with our accounts team before booking again.",
    "blocked_at": "2026-10-21T11:30:00Z",
    "by": {
      "ref": "k3m8p1",
      "name": "Example Ltd"
    }
  }
}

Add an email domain to a buyer

POST /buyers/{ref}/domains

Put an email domain on a buyer: the part after the @, like example.org. Addresses at exactly that domain belong to the buyer before anybody signs in, so a signed-out checkout with one follows the buyer's approval rules. Only the exact domain matches, never a subdomain, so mail.example.org is a different one. The domain is stored lowercased, with any leading @ taken off. A domain can be on more than one buyer, like a board whose schools share its domain. Answers with the buyer's domains as they now stand, sorted. Something that isn't a domain answers 422 invalid_domain; a domain anyone can get an address at, like gmail.com or yahoo.ie, answers 422 public_provider; one already on this buyer answers 409 already_on; and a buyer that already has 20 answers 422 too_many.

Requires orders.manage

Path parameters

ref string required

Request body

#

domain string required

The domain to add, the part after the @.

Response fields

#

domains array of string

Responses

• 201The domain was added.
• 401No key, an unknown key, or a revoked key.
• 403The key does not carry the required capability.
• 404No such resource.
• 409That domain is already one of this buyer's (already_on).
• 422The body isn't {"domain":"..."} (invalid_body), the domain isn't one (invalid_domain), anyone can get an address at it (public_provider), or the buyer already has 20 (too_many).
• 500Internal error.

curl -X POST https://<yourslug>.go.tito.io/api/v1/buyers/H7K2PX/domains \
  -H "Authorization: Bearer titogo_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.org"}'

// Node 18+, Deno, Bun, or a browser on the same origin
const res = await fetch("https://<yourslug>.go.tito.io/api/v1/buyers/H7K2PX/domains", {
  method: "POST",
  headers: {
    Authorization: "Bearer titogo_sk_your_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "domain": "example.org"
}),
});
const data = await res.json();

{
  "domains": [
    "example.org"
  ]
}

Remove an email domain from a buyer

DELETE /buyers/{ref}/domains/{domain}

Take an email domain off a buyer. Addresses at it stop belonging to the buyer from the next checkout; quotes and orders already placed for the buyer stay with it. A domain that isn't one of the buyer's answers 404 not_on.

Requires orders.manage

Path parameters

ref string required

domain string required

Response fields

#

domains array of string

Responses

• 200The domain was removed.
• 401No key, an unknown key, or a revoked key.
• 403The key does not carry the required capability.
• 404No such buyer, or the domain isn't one of its (not_on).
• 500Internal error.

curl -X DELETE https://<yourslug>.go.tito.io/api/v1/buyers/H7K2PX/domains/{domain} \
  -H "Authorization: Bearer titogo_sk_your_key"

// Node 18+, Deno, Bun, or a browser on the same origin
const res = await fetch("https://<yourslug>.go.tito.io/api/v1/buyers/H7K2PX/domains/{domain}", {
  method: "DELETE",
  headers: {
    Authorization: "Bearer titogo_sk_your_key",
  },
});
const data = await res.json();

{
  "domains": [
    "example.org"
  ]
}

Give a buyer a kind

POST /buyers/{ref}/kind

Choose which of the account's kinds this buyer is. 0 leaves the buyer with no kind. A kind is a label for finding and filtering buyers; nothing else depends on it. A kind_id that names no kind answers 422 unknown_kind.

Requires orders.manage

Path parameters

ref string required

Request body

#

kind_id integer required

A kind id, or 0 for no kind.

Response fields

#

kind object or null

The kind a buyer is, or null for none. A kind is a label for finding and filtering buyers; nothing else depends on it. The whole kind is GET /buyer-kinds/{id}.

#

kind.id integer

#

kind.name string

Responses

• 200The buyer's kind as it now stands.
• 401No key, an unknown key, or a revoked key.
• 403The key does not carry the required capability.
• 404No such resource.
• 422The body isn't {"kind_id": n} (invalid_body), or no kind has that id (unknown_kind).
• 500Internal error.

curl -X POST https://<yourslug>.go.tito.io/api/v1/buyers/H7K2PX/kind \
  -H "Authorization: Bearer titogo_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"kind_id":2}'

// Node 18+, Deno, Bun, or a browser on the same origin
const res = await fetch("https://<yourslug>.go.tito.io/api/v1/buyers/H7K2PX/kind", {
  method: "POST",
  headers: {
    Authorization: "Bearer titogo_sk_your_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "kind_id": 2
}),
});
const data = await res.json();

{
  "kind": {
    "id": 2,
    "name": "Partners"
  }
}

Make a buyer part of another

POST /buyers/{ref}/part-of

Choose which buyer this one is part of, like a department under its company, or null for part of nothing. A buyer without payment terms of its own follows the terms of the buyer it is part of. It is one level: the chosen buyer must not be part of another itself (409 part_of_another), and a buyer that others are part of can't be part of another (409 has_buyers).

Requires orders.manage

Path parameters

ref string required

Request body

#

part_of string or null required

The ref of the buyer this one is part of, or null for part of nothing.

Response fields

#

part_of string or null

Responses

• 200What the buyer is now part of.
• 401No key, an unknown key, or a revoked key.
• 403The key does not carry the required capability.
• 404No such resource.
• 409The chosen buyer is part of another (part_of_another), or other buyers are part of this one (has_buyers).
• 422The body isn't {"part_of": ...} (invalid_body), part_of names no buyer (unknown_buyer), or names this buyer (part_of_itself).
• 500Internal error.

curl -X POST https://<yourslug>.go.tito.io/api/v1/buyers/H7K2PX/part-of \
  -H "Authorization: Bearer titogo_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"part_of":"k3m8p1"}'

// Node 18+, Deno, Bun, or a browser on the same origin
const res = await fetch("https://<yourslug>.go.tito.io/api/v1/buyers/H7K2PX/part-of", {
  method: "POST",
  headers: {
    Authorization: "Bearer titogo_sk_your_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "part_of": "k3m8p1"
}),
});
const data = await res.json();

{
  "part_of": "example"
}

Add a person to a buyer

POST /buyers/{ref}/people

Put an email address on a buyer, so that person can sign in as the buyer with their own address and see its quotes, orders and invoices. They can sign in straight away; nobody is emailed. Answers with the buyer's people as they now stand. An address that isn't one answers 422 invalid_email; one already on this buyer answers 409 already_on. An address may be on more than one buyer; when they sign in, they choose which. Give a role to choose what they can do when quotes need approval; a role that isn't one answers 422 invalid_role. To add somebody from the address book, send contact with their contact ref in place of email. That needs a key carrying contacts.view as well, or it answers 403 missing_capability, and a ref that is no contact, or Contacts switched off, answers 422 unknown_contact. Send one of email and contact, never both.

Requires orders.manage

Path parameters

ref string required

Request body

#

email string

The address to add. Send this or contact.

#

contact string

A contact's ref, to add that contact's address. Send this or email. Needs contacts.view as well as orders.manage.

#

role string

Optional. Without it the person is a requester where the buyer's quotes need approval, and an approver everywhere else.

one of requesterapprover

Response fields

#

people array of BuyerPerson

#

people[].email string

#

people[].primary boolean

The buyer's primary contact: the address it is listed under, the one invoices and Stripe use. It can't be removed; make someone else primary first (POST /buyers/{ref}/primary).

#

people[].role string

What this person can do when the buyer's quotes need approval: a requester sends a quote for approval, an approver can reject one. Where approval isn't needed the two can do the same things.

one of requesterapprover

#

people[].sees_all boolean

Whether this person sees every one of the buyer's bookings and quotes when they sign in, or only the ones made with their own email address. Only the organizer can change it (POST /buyers/{ref}/people/{email}/sees).

Responses

• 201The person was added.
• 401No key, an unknown key, or a revoked key.
• 403The key does not carry the required capability.
• 404No such resource.
• 409That address is already one of this buyer's people (already_on).
• 422The body isn't {"email":"..."} or {"contact":"..."} (invalid_body), the address isn't one (invalid_email), the contact ref is no contact (unknown_contact), or the role isn't requester or approver (invalid_role).
• 500Internal error.

curl -X POST https://<yourslug>.go.tito.io/api/v1/buyers/H7K2PX/people \
  -H "Authorization: Bearer titogo_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"email":"ada@example.com"}'

// Node 18+, Deno, Bun, or a browser on the same origin
const res = await fetch("https://<yourslug>.go.tito.io/api/v1/buyers/H7K2PX/people", {
  method: "POST",
  headers: {
    Authorization: "Bearer titogo_sk_your_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "email": "ada@example.com"
}),
});
const data = await res.json();

{
  "people": [
    {
      "email": "accounts@example.com",
      "primary": true,
      "role": "approver",
      "sees_all": true
    }
  ]
}

Remove a person from a buyer

DELETE /buyers/{ref}/people/{email}

Take an email address off a buyer. The person can no longer sign in as the buyer and is signed out at once; quotes and orders they already placed stay with the buyer. The primary contact, the address the buyer registered with, can't be removed and answers 409 primary_contact. An address that isn't one of the buyer's people answers 404 not_on. URL-encode the address in the path.

Requires orders.manage

Path parameters

ref string required

email string required

Response fields

#

people array of BuyerPerson

#

people[].email string

#

people[].primary boolean

The buyer's primary contact: the address it is listed under, the one invoices and Stripe use. It can't be removed; make someone else primary first (POST /buyers/{ref}/primary).

#

people[].role string

What this person can do when the buyer's quotes need approval: a requester sends a quote for approval, an approver can reject one. Where approval isn't needed the two can do the same things.

one of requesterapprover

#

people[].sees_all boolean

Whether this person sees every one of the buyer's bookings and quotes when they sign in, or only the ones made with their own email address. Only the organizer can change it (POST /buyers/{ref}/people/{email}/sees).

Responses

• 200The person was removed.
• 401No key, an unknown key, or a revoked key.
• 403The key does not carry the required capability.
• 404No such buyer, or the address isn't one of its people (not_on).
• 409The primary contact can't be removed (primary_contact).
• 500Internal error.

curl -X DELETE https://<yourslug>.go.tito.io/api/v1/buyers/H7K2PX/people/{email} \
  -H "Authorization: Bearer titogo_sk_your_key"

// Node 18+, Deno, Bun, or a browser on the same origin
const res = await fetch("https://<yourslug>.go.tito.io/api/v1/buyers/H7K2PX/people/{email}", {
  method: "DELETE",
  headers: {
    Authorization: "Bearer titogo_sk_your_key",
  },
});
const data = await res.json();

{
  "people": [
    {
      "email": "accounts@example.com",
      "primary": true,
      "role": "approver",
      "sees_all": true
    }
  ]
}

Change a person's role on a buyer

POST /buyers/{ref}/people/{email}/role

Make one of a buyer's people a requester or an approver. Where the buyer's quotes need approval, a requester sends a quote for approval and an approver can reject one. Answers with the buyer's people as they now stand.

Requires orders.manage

Path parameters

ref string required

email string required

Request body

#

role string required

one of requesterapprover

Response fields

#

people array of BuyerPerson

#

people[].email string

#

people[].primary boolean

The buyer's primary contact: the address it is listed under, the one invoices and Stripe use. It can't be removed; make someone else primary first (POST /buyers/{ref}/primary).

#

people[].role string

What this person can do when the buyer's quotes need approval: a requester sends a quote for approval, an approver can reject one. Where approval isn't needed the two can do the same things.

one of requesterapprover

#

people[].sees_all boolean

Whether this person sees every one of the buyer's bookings and quotes when they sign in, or only the ones made with their own email address. Only the organizer can change it (POST /buyers/{ref}/people/{email}/sees).

Responses

• 200The buyer's people.
• 401No key, an unknown key, or a revoked key.
• 403The key does not carry the required capability.
• 404No such buyer (not_found), or the address isn't one of its people (not_on).
• 422The body isn't {"role": ...} (invalid_body), or the role isn't requester or approver (invalid_role).
• 500Internal error.

curl -X POST https://<yourslug>.go.tito.io/api/v1/buyers/H7K2PX/people/{email}/role \
  -H "Authorization: Bearer titogo_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"role":"requester"}'

// Node 18+, Deno, Bun, or a browser on the same origin
const res = await fetch("https://<yourslug>.go.tito.io/api/v1/buyers/H7K2PX/people/{email}/role", {
  method: "POST",
  headers: {
    Authorization: "Bearer titogo_sk_your_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "role": "requester"
}),
});
const data = await res.json();

{
  "people": [
    {
      "email": "accounts@example.com",
      "primary": true,
      "role": "approver",
      "sees_all": true
    }
  ]
}

Change what a person sees on a buyer

POST /buyers/{ref}/people/{email}/sees

Choose whether one of a buyer's people sees every one of the buyer's bookings and quotes when they sign in (true), or only the ones made with their own email address (false, the default). Answers with the buyer's people as they now stand.

Requires orders.manage

Path parameters

ref string required

email string required

Request body

#

sees_all boolean required

Response fields

#

people array of BuyerPerson

#

people[].email string

#

people[].primary boolean

The buyer's primary contact: the address it is listed under, the one invoices and Stripe use. It can't be removed; make someone else primary first (POST /buyers/{ref}/primary).

#

people[].role string

What this person can do when the buyer's quotes need approval: a requester sends a quote for approval, an approver can reject one. Where approval isn't needed the two can do the same things.

one of requesterapprover

#

people[].sees_all boolean

Whether this person sees every one of the buyer's bookings and quotes when they sign in, or only the ones made with their own email address. Only the organizer can change it (POST /buyers/{ref}/people/{email}/sees).

Responses

• 200The buyer's people.
• 401No key, an unknown key, or a revoked key.
• 403The key does not carry the required capability.
• 404No such buyer (not_found), or the address isn't one of its people (not_on).
• 422The body isn't {"sees_all": true} or {"sees_all": false} (invalid_body).
• 500Internal error.

curl -X POST https://<yourslug>.go.tito.io/api/v1/buyers/H7K2PX/people/{email}/sees \
  -H "Authorization: Bearer titogo_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"sees_all":true}'

// Node 18+, Deno, Bun, or a browser on the same origin
const res = await fetch("https://<yourslug>.go.tito.io/api/v1/buyers/H7K2PX/people/{email}/sees", {
  method: "POST",
  headers: {
    Authorization: "Bearer titogo_sk_your_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "sees_all": true
}),
});
const data = await res.json();

{
  "people": [
    {
      "email": "accounts@example.com",
      "primary": true,
      "role": "approver",
      "sees_all": true
    }
  ]
}

Choose whether a buyer's quotes need approval

POST /buyers/{ref}/po-required

With po_required on, a quote made for this buyer, or for any buyer part of it, goes to this buyer's approvers before it can become an order. It is set on the buyer that approves: a buyer that is part of another follows that buyer's setting and can't have its own (409 part_of).

Requires orders.manage

Path parameters

ref string required

Request body

#

po_required boolean required

Response fields

#

po_required boolean

#

approval object

Approval as it applies to this buyer: required or not, and the buyer whose approvers answer, which is the buyer this one is part of, or else itself.

#

approval.required boolean

#

approval.approver object

#

approval.approver.ref string

#

approval.approver.name string

Responses

• 200The buyer's setting, and approval as it now applies.
• 401No key, an unknown key, or a revoked key.
• 403The key does not carry the required capability.
• 404No such resource.
• 409The buyer is part of another, whose setting applies to it (part_of).
• 422The body isn't {"po_required": true} or {"po_required": false} (invalid_body).
• 500Internal error.

curl -X POST https://<yourslug>.go.tito.io/api/v1/buyers/H7K2PX/po-required \
  -H "Authorization: Bearer titogo_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"po_required":true}'

// Node 18+, Deno, Bun, or a browser on the same origin
const res = await fetch("https://<yourslug>.go.tito.io/api/v1/buyers/H7K2PX/po-required", {
  method: "POST",
  headers: {
    Authorization: "Bearer titogo_sk_your_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "po_required": true
}),
});
const data = await res.json();

{
  "po_required": true,
  "approval": {
    "required": true,
    "approver": {
      "ref": "k3m8p1",
      "name": "Example Ltd"
    }
  }
}

Make a person a buyer's primary contact

POST /buyers/{ref}/primary

Make one of a buyer's people its primary contact: the address the buyer is listed under, the one its Stripe Customer carries, and the one a buyer import matches it by. The previous primary contact stays on as one of the buyer's people, and nobody is signed out. Making the current primary contact primary again changes nothing. Answers with the buyer's people as they now stand. An address that isn't one of the buyer's people answers 404 not_on; one that is already another buyer's primary contact answers 409 primary_taken, because an address can be the primary contact of one buyer only. A change that lands while this request is in flight answers 409 primary_moved. The previous primary contact's orders and quotes from before the buyer had people stay with the buyer. The buyer's name is the primary contact's own, so it is cleared; set the new contact's with PATCH /buyers/{ref}.

Requires orders.manage

Path parameters

ref string required

Request body

#

email string required

Response fields

#

people array of BuyerPerson

#

people[].email string

#

people[].primary boolean

The buyer's primary contact: the address it is listed under, the one invoices and Stripe use. It can't be removed; make someone else primary first (POST /buyers/{ref}/primary).

#

people[].role string

What this person can do when the buyer's quotes need approval: a requester sends a quote for approval, an approver can reject one. Where approval isn't needed the two can do the same things.

one of requesterapprover

#

people[].sees_all boolean

Whether this person sees every one of the buyer's bookings and quotes when they sign in, or only the ones made with their own email address. Only the organizer can change it (POST /buyers/{ref}/people/{email}/sees).

Responses

• 200The person is now the primary contact.
• 401No key, an unknown key, or a revoked key.
• 403The key does not carry the required capability.
• 404No such buyer, or the address isn't one of its people (not_on).
• 409The address is already another buyer's primary contact (primary_taken), or this buyer's primary contact changed while the request was in flight (primary_moved).
• 422The body isn't {"email":"..."} (invalid_body), or the address is blank (invalid_email).
• 500Internal error.

curl -X POST https://<yourslug>.go.tito.io/api/v1/buyers/H7K2PX/primary \
  -H "Authorization: Bearer titogo_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"email":"ada@example.com"}'

// Node 18+, Deno, Bun, or a browser on the same origin
const res = await fetch("https://<yourslug>.go.tito.io/api/v1/buyers/H7K2PX/primary", {
  method: "POST",
  headers: {
    Authorization: "Bearer titogo_sk_your_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "email": "ada@example.com"
}),
});
const data = await res.json();

{
  "people": [
    {
      "email": "accounts@example.com",
      "primary": true,
      "role": "approver",
      "sees_all": true
    }
  ]
}

Link a buyer to a Stripe customer

POST /buyers/{ref}/stripe-customer

Link the buyer to a customer that already exists in the account's connected Stripe account. Stripe issues the account details a buyer pays a bank transfer into per customer, so after this the buyer's next bank transfer goes to that customer's account details. Tito checks with Stripe that the customer exists and hasn't been deleted, and changes nothing if Stripe can't be reached (502 stripe_unavailable). The customer's email in Stripe is left as it is.

A customer can belong to one buyer only (409 stripe_customer_taken, naming the other buyer's ref). A buyer with a Stripe bank transfer still awaiting payment can't be linked to another customer until that transfer is paid or canceled (409 bank_transfer_open). Linking the customer the buyer already has changes nothing. There is no unlinking: an empty stripe_customer_id answers 422.

Requires payment.manage

Path parameters

ref string required

Request body

#

stripe_customer_id string required

The Stripe customer's id.

Response fields

#

ref string

#

email string

#

name string

#

org string

#

phone string

The buyer's phone number as it was typed, trimmed and cut to 64 characters. It isn't checked or reformatted. Empty when the buyer has none.

#

quote_count integer

Quotes matching this buyer's id OR their email — an anonymous quote is still theirs.

#

order_count integer

Orders matching their email, case-insensitively: buyers.email is lowercased on the way in and an order keeps the address as the buyer typed it, so a case-sensitive match once read a registered buyer as having no orders at all.

#

part_of string or null

The ref of the buyer this one is part of, like a department's company, or null when it is part of nothing. One level: a buyer others are part of is never part of another.

#

kind object or null

The kind a buyer is, or null for none. A kind is a label for finding and filtering buyers; nothing else depends on it. The whole kind is GET /buyer-kinds/{id}.

#

kind.id integer

#

kind.name string

#

created_at string (RFC 3339) or null

#

admin_url string

The organizer page, as an absolute URL: on the root admin origin, or on the instance's own address on a standalone instance.

#

anonymized_at string (RFC 3339) or null

When the person on this record was anonymized, null while they are still on it. An anonymized record keeps its reference, its place and its money and has no name or address, which this tells apart from one nobody filled in.

#

stripe_customer_id string

The Customer this buyer is on Stripe, empty until something mints one (the bank-transfer path does it lazily). An identifier, not a credential.

#

people array of BuyerPerson

Everyone who signs in as this buyer, the primary contact first.

#

people[].email string

#

people[].primary boolean

The buyer's primary contact: the address it is listed under, the one invoices and Stripe use. It can't be removed; make someone else primary first (POST /buyers/{ref}/primary).

#

people[].role string

What this person can do when the buyer's quotes need approval: a requester sends a quote for approval, an approver can reject one. Where approval isn't needed the two can do the same things.

one of requesterapprover

#

people[].sees_all boolean

Whether this person sees every one of the buyer's bookings and quotes when they sign in, or only the ones made with their own email address. Only the organizer can change it (POST /buyers/{ref}/people/{email}/sees).

#

domains array of string

The buyer's email domains, sorted, never null. Addresses at exactly these domains belong to the buyer before anybody signs in.

#

terms object or null

The named payment terms a buyer has of its own, or null when it has none. A buyer without terms of its own follows the terms of the buyer it is part of (inherited_terms on the buyer), or else each event's own bank transfer settings. The whole set is GET /payment-terms/{id}.

#

terms.id integer

#

terms.name string

#

inherited_terms object

What a buyer without terms of its own follows: the terms of the buyer it is part of. Null when it has its own, is part of nothing, or that buyer has none either.

#

inherited_terms.id integer

#

inherited_terms.name string

#

includes array of object

Every buyer that is part of this one.

#

includes[].ref string

#

includes[].name string

#

po_required boolean

This buyer's own approval setting: its quotes, and those of every buyer part of it, go to an approver before they can become orders. Always false on a buyer that is part of another, which follows that buyer's; approval says what applies. Set it with POST /buyers/{ref}/po-required.

#

approval object

Approval as it applies to this buyer: required or not, and the buyer whose approvers answer, which is the buyer this one is part of, or else itself.

#

approval.required boolean

#

approval.approver object

#

approval.approver.ref string

#

approval.approver.name string

#

block object

Whether the buyer is blocked from starting new orders and quotes, by its own block or the one on the buyer it is part of. Set it with POST /buyers/{ref}/block and lift it with DELETE /buyers/{ref}/block.

#

block.blocked boolean

#

block.message string

The words emailed to whoever at the buyer tries to order, as plain text, empty for the standard line.

#

block.blocked_at string (RFC 3339) or null

When the block was set, null when the buyer isn't blocked.

#

block.by object or null

The buyer whose block applies: this one, or the one it is part of. Null when the buyer isn't blocked.

#

block.by.ref string

#

block.by.name string

#

spend array of object

What this buyer has actually PAID, per currency: order totals less whatever was refunded off them. A buyer can span currencies across events, so it is a list. A partial refund leaves the order paid and is netted; a full one flips its status and nets to zero either way.

#

spend[].cents integer

#

spend[].currency string

#

quotes array of BuyerQuoteSummary

#

quotes[].ref string

#

quotes[].event_slug string

#

quotes[].status string

open, submitted (sent for approval), rejected (an approver turned it down), imported (converted to an order), expired or canceled.

#

quotes[].amount_cents integer

#

quotes[].currency string

#

quotes[].order_ref string or null

The order this quote became, null while it is still a quote.

#

quotes[].expires_at string (RFC 3339) or null

#

quotes[].created_at string (RFC 3339) or null

#

quotes[].admin_url string

The organizer page, as an absolute URL: on the root admin origin, or on the instance's own address on a standalone instance.

#

orders array of BuyerOrderSummary

#

orders[].ref string

#

orders[].event_slug string

#

orders[].status string

#

orders[].amount_cents integer

#

orders[].currency string

#

orders[].payment_method string

#

orders[].created_at string (RFC 3339) or null

#

orders[].admin_url string

The organizer page, as an absolute URL: on the root admin origin, or on the instance's own address on a standalone instance.

#

bank_transfer object or null

The newest wire-instruction snapshot, null until this buyer has one. Read from the stored row — no Stripe call — because the virtual IBAN is per-Customer, so that row IS the account they pay into. The IBAN is here deliberately: it is the account's own receiving account, printed on the invoice the buyer was already sent, not a secret that opens anything.

#

bank_transfer.reference string

#

bank_transfer.iban string

#

bank_transfer.bic string

#

bank_transfer.account_holder string

#

bank_transfer.bank_country string

#

bank_transfer.amount_cents integer

#

bank_transfer.currency string

#

bank_transfer.status string

awaiting, funded or canceled.

#

bank_transfer.due_at string (RFC 3339) or null

#

bank_details object or null

The bank details Stripe issued this buyer's current Stripe customer, kept on the buyer: the account the buyer pays every bank transfer into, and what its vendor form prints. Null until they are kept, either by POST /buyers/{ref}/bank-details or by the buyer's first Stripe bank transfer. Details kept for a Stripe customer the buyer is no longer linked to are never served. Read from the stored row, with no Stripe call.

#

bank_details.account_holder string

#

bank_details.iban string

#

bank_details.bic string

#

bank_details.bank_country string

Two-letter country code of the bank account.

#

bank_details.currency string

#

billing object

This customer's billing identity, as currently stored (never a computed fallback — a blank name here can still print as org on an invoice).

#

billing.name string

The legal entity an invoice is addressed to. Blank falls back to org when an invoice is rendered.

#

billing.line1 string

#

billing.line2 string

#

billing.city string

#

billing.postcode string

#

billing.subdivision string

County, state or region.

#

billing.country string

ISO 3166-1 alpha-2.

#

billing.vat_number string

#

billing.buyer_reference string

BT-10/Leitweg-ID-style routing reference the buyer gave.

#

billing.po_reference string

A purchase order number the buyer raised.

Responses

• 200The buyer as it now stands, with its stripe_customer_id.
• 401No key, an unknown key, or a revoked key.
• 403The key does not carry the required capability.
• 404No such resource.
• 409Another buyer has that customer (stripe_customer_taken), this buyer has a Stripe bank transfer awaiting payment (bank_transfer_open), the buyer's customer changed while the request was in flight (stripe_customer_moved), or the account has no Stripe connection (not_connected).
• 422The body isn't {"stripe_customer_id": "cus_..."} (invalid_body), the id isn't shaped like a Stripe customer id (invalid_stripe_customer_id), Stripe has no customer with that id on this account (unknown_stripe_customer), or it has been deleted in Stripe (stripe_customer_deleted).
• 500Internal error.
• 502Stripe couldn't be asked about the customer, and nothing was changed (stripe_unavailable). Safe to retry. Stripe refusing this account's request answers stripe_refused instead, and nothing was changed either; check the account's Stripe connection before retrying.

curl -X POST https://<yourslug>.go.tito.io/api/v1/buyers/H7K2PX/stripe-customer \
  -H "Authorization: Bearer titogo_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"stripe_customer_id":"cus_Q1w2E3r4T5y6U7"}'

// Node 18+, Deno, Bun, or a browser on the same origin
const res = await fetch("https://<yourslug>.go.tito.io/api/v1/buyers/H7K2PX/stripe-customer", {
  method: "POST",
  headers: {
    Authorization: "Bearer titogo_sk_your_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "stripe_customer_id": "cus_Q1w2E3r4T5y6U7"
}),
});
const data = await res.json();

{
  "ref": "b7x9k2",
  "email": "accounts@example.com",
  "name": "Alex Smith",
  "org": "Example Ltd",
  "phone": "+1 202 555 0143",
  "quote_count": 3,
  "order_count": 5,
  "part_of": "k3m8p1",
  "kind": {
    "id": 2,
    "name": "Partners"
  },
  "created_at": "2026-10-14T09:00:00Z",
  "admin_url": "https://example.com/hooks/tito",
  "anonymized_at": null,
  "stripe_customer_id": "cus_1MEXAMPLE",
  "people": [
    {
      "email": "accounts@example.com",
      "primary": true,
      "role": "approver",
      "sees_all": true
    }
  ],
  "domains": [
    "example.org"
  ],
  "terms": {
    "id": 3,
    "name": "Members"
  },
  "inherited_terms": {
    "id": 3,
    "name": "Members"
  },
  "includes": [
    {
      "ref": "p2q7r4",
      "name": "Example Ltd Design"
    }
  ],
  "po_required": false,
  "approval": {
    "required": true,
    "approver": {
      "ref": "k3m8p1",
      "name": "Example Ltd"
    }
  },
  "block": {
    "blocked": true,
    "message": "Please settle your outstanding invoices with our accounts team before booking again.",
    "blocked_at": "2026-10-21T11:30:00Z",
    "by": {
      "ref": "k3m8p1",
      "name": "Example Ltd"
    }
  },
  "spend": [
    {
      "cents": 150000,
      "currency": "eur"
    }
  ],
  "quotes": [
    {
      "ref": "H7K2PX",
      "event_slug": "demo",
      "status": "open",
      "amount_cents": 14900,
      "currency": "eur",
      "order_ref": "H7K2PX",
      "expires_at": "2026-10-14T09:00:00Z",
      "created_at": "2026-10-14T09:00:00Z",
      "admin_url": "https://example.com/hooks/tito"
    }
  ],
  "orders": [
    {
      "ref": "H7K2PX",
      "event_slug": "demo",
      "status": "paid",
      "amount_cents": 14900,
      "currency": "eur",
      "payment_method": "example",
      "created_at": "2026-10-14T09:00:00Z",
      "admin_url": "https://example.com/hooks/tito"
    }
  ],
  "bank_transfer": {
    "reference": "RF97TESTREF",
    "iban": "example",
    "bic": "example",
    "account_holder": "Ada Lovelace",
    "bank_country": "example",
    "amount_cents": 14900,
    "currency": "eur",
    "status": "awaiting",
    "due_at": "2026-10-14T09:00:00Z"
  },
  "bank_details": {
    "account_holder": "Stripe Payments Europe",
    "iban": "IE29AIBK93115212345678",
    "bic": "AIBKIE2D",
    "bank_country": "IE",
    "currency": "eur"
  },
  "billing": {
    "name": "St Brigid's NS Board of Management",
    "line1": "12 Main Street",
    "line2": "",
    "city": "Springfield",
    "postcode": "D02 AF30",
    "subdivision": "Co. Dublin",
    "country": "IE",
    "vat_number": "IE1234567T",
    "buyer_reference": "",
    "po_reference": ""
  }
}

Give a buyer payment terms

POST /buyers/{ref}/terms

Choose which payment terms this buyer's next invoices are issued under. 0 puts the buyer back on each event's own bank transfer settings. An invoice already issued keeps the terms it was issued under. A terms_id that names no payment terms answers 422 unknown_terms.

Requires orders.manage

Path parameters

ref string required

Request body

#

terms_id integer required

A payment terms id, or 0 for each event's own settings.

Response fields

#

terms object or null

The named payment terms a buyer has of its own, or null when it has none. A buyer without terms of its own follows the terms of the buyer it is part of (inherited_terms on the buyer), or else each event's own bank transfer settings. The whole set is GET /payment-terms/{id}.

#

terms.id integer

#

terms.name string

Responses

• 200The buyer's terms as they now stand.
• 401No key, an unknown key, or a revoked key.
• 403The key does not carry the required capability.
• 404No such resource.
• 422The body isn't {"terms_id": n} (invalid_body), or no payment terms have that id (unknown_terms).
• 500Internal error.

curl -X POST https://<yourslug>.go.tito.io/api/v1/buyers/H7K2PX/terms \
  -H "Authorization: Bearer titogo_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"terms_id":3}'

// Node 18+, Deno, Bun, or a browser on the same origin
const res = await fetch("https://<yourslug>.go.tito.io/api/v1/buyers/H7K2PX/terms", {
  method: "POST",
  headers: {
    Authorization: "Bearer titogo_sk_your_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "terms_id": 3
}),
});
const data = await res.json();

{
  "terms": {
    "id": 3,
    "name": "Members"
  }
}

List payment terms

GET /payment-terms

The account's named payment terms, by name, each with how many buyers have it. A buyer with none follows each event's own bank transfer settings. There is no paging: an account has a handful.

Requires orders.view

Response fields

#

payment_terms array of PaymentTerms

#

payment_terms[].id integer

#

payment_terms[].name string

Recorded on each invoice issued under these terms.

#

payment_terms[].anchor string

What days counts from. order counts forward from the order. event counts forward from the day the event ends (or starts, when it has no end); an order that comes in later than that counts from the order instead, so nobody is due before they booked. before_event counts back from the day the event starts; an order that comes in later than that is due at the end of the day it was placed. An event with no date at all can't have an invoice issued under either event anchor.

one of ordereventbefore_event

#

payment_terms[].days integer

Days to pay, 1 to 365.

#

payment_terms[].reminder_days string

Remind the buyer this many days before the due date, comma-separated. Empty for no reminders.

#

payment_terms[].overdue_days string

Chase the buyer this many days after the due date, comma-separated. Empty for no chasing.

#

payment_terms[].auto_cancel_days integer

Cancel the order this many days after the due date, putting its tickets back on sale. 0 is off.

#

payment_terms[].buyer_count integer

How many buyers' invoices are issued under these terms: those with them as their own, and those without terms of their own that are part of one that has them.

Responses

• 200The payment terms.
• 401No key, an unknown key, or a revoked key.
• 403The key does not carry the required capability.
• 500Internal error.

curl https://<yourslug>.go.tito.io/api/v1/payment-terms \
  -H "Authorization: Bearer titogo_sk_your_key"

// Node 18+, Deno, Bun, or a browser on the same origin
const res = await fetch("https://<yourslug>.go.tito.io/api/v1/payment-terms", {
  method: "GET",
  headers: {
    Authorization: "Bearer titogo_sk_your_key",
  },
});
const data = await res.json();

{
  "payment_terms": [
    {
      "id": 3,
      "name": "Members",
      "anchor": "event",
      "days": 7,
      "reminder_days": "7,1",
      "overdue_days": "1,7",
      "auto_cancel_days": 0,
      "buyer_count": 12
    }
  ]
}

Create payment terms

POST /payment-terms

Add a named set of payment terms. name, anchor and days are required. The reminder schedules are tidied the way an event's are (numbers, deduplicated, in order), and auto_cancel_days above 365 is held at 365. Answers with the terms as stored.

Requires settings.manage

Request body

#

name string required

#

anchor string required

one of ordereventbefore_event

#

days integer required

#

reminder_days string

#

overdue_days string

#

auto_cancel_days integer

Response fields

#

id integer

#

name string

Recorded on each invoice issued under these terms.

#

anchor string

What days counts from. order counts forward from the order. event counts forward from the day the event ends (or starts, when it has no end); an order that comes in later than that counts from the order instead, so nobody is due before they booked. before_event counts back from the day the event starts; an order that comes in later than that is due at the end of the day it was placed. An event with no date at all can't have an invoice issued under either event anchor.

one of ordereventbefore_event

#

days integer

Days to pay, 1 to 365.

#

reminder_days string

Remind the buyer this many days before the due date, comma-separated. Empty for no reminders.

#

overdue_days string

Chase the buyer this many days after the due date, comma-separated. Empty for no chasing.

#

auto_cancel_days integer

Cancel the order this many days after the due date, putting its tickets back on sale. 0 is off.

#

buyer_count integer

How many buyers' invoices are issued under these terms: those with them as their own, and those without terms of their own that are part of one that has them.

Responses

• 201The payment terms were created.
• 401No key, an unknown key, or a revoked key.
• 403The key does not carry the required capability.
• 422The body isn't an object of these fields (invalid_body), the name is blank (invalid_name), the anchor isn't order, event or before_event (invalid_anchor), or days is outside 1 to 365 (invalid_days).
• 500Internal error.

curl -X POST https://<yourslug>.go.tito.io/api/v1/payment-terms \
  -H "Authorization: Bearer titogo_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name":"Members","anchor":"event","days":7}'

// Node 18+, Deno, Bun, or a browser on the same origin
const res = await fetch("https://<yourslug>.go.tito.io/api/v1/payment-terms", {
  method: "POST",
  headers: {
    Authorization: "Bearer titogo_sk_your_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "name": "Members",
  "anchor": "event",
  "days": 7
}),
});
const data = await res.json();