Introduction

TicketConnect White-Label API lets you launch a fully branded ticketing product — events, paid tickets, QR check-in, resale, payouts — without building any of the hard parts yourself. You integrate the same way you'd integrate Stripe or SendGrid: REST + an API key + signed webhooks, all in plain business language.

The hard parts are handled for you. Every ticket is tamper-proof and anti-scalping is on by default (configurable per event). You work with events, tickets, fiat prices, customer emails, QR codes, and bank payouts — the platform does all the rest behind the scenes.

Running your own events instead? These docs are for licensees — teams embedding TicketConnect behind their own product. If you're an event organizer selling on the TicketConnect platform itself, switch to the For organizers docs.

What you can build

• Sell tickets for events in your own currency, paid by card.
• Issue, transfer, refund, and upgrade tickets programmatically.
• Deliver tickets as an opaque QR string your app renders however it likes.
• Sell high-demand on-sales fairly with a built-in waiting-room queue and published price schedules.
• Run a secondary marketplace with automatic royalties and anti-scalping.
• Validate tickets at the door online, in requests of up to 200 codes, and record check-ins through the attendance endpoint. Or scan with no network at all through the offline door protocol (/v1/scanner) and its SDK.
• Receive signed webhooks for every important event.
• Transfer proven platform-held Stripe funds to your connected account; bank payouts follow Stripe’s separate lifecycle.

Everything you call lives under the /v1 prefix and is automatically scoped to your account — you can only ever see and touch your own data.

Base URL

https://api.ticketconnect.example/v1

Replace the host with the environment you were given. Health, the OpenAPI document, and the interactive docs are public; everything else needs an API key.

Your first call

curl https://api.ticketconnect.example/v1/account \
  -H "Authorization: Bearer sk_test_your_key_here"

If that returns your account, you're ready. Head to the Quickstart to sell your first ticket end-to-end, or jump straight to the API reference.

Where to go next

Interactive reference

A live, try-it-out version of the full API (Swagger UI) is available at /v1/docs, backed by the machine-readable OpenAPI document at /v1/openapi.json — import it into Postman or use it for code generation.

Quickstart

This guide takes you end-to-end: you'll create an event, add a ticket tier, register a customer, take a card payment, issue a ticket, fetch its QR pass, and check it in at the door. Every step is a single REST call you can copy and paste.

Note: Run the whole tutorial with a test key (sk_test_…). Test mode hits the same code paths as production but is fully isolated from your live data. See Test & live modes.

Base URL for every call:

https://api.ticketconnect.example/v1

Conventions used throughout:

• Authenticate with Authorization: Bearer sk_test_….
• Money is always in your account's currency (fiat) and is computed server-side — you never send an amount.
• Mutating POSTs accept an optional Idempotency-Key header so retries are safe.
• Errors come back as { "error": { "type", "code", "message", "param", "request_id" } }.

Step 1 — Get your API key

Create a secret key in your dashboard. You'll get a key that starts with sk_test_ (sandbox) or sk_live_ (production). The key is shown once at creation, so store it somewhere safe.

For this tutorial you only need a test key. For the full breakdown of key formats, the Authorization: Bearer transport, and the scopes each call requires, read Authentication.

Warning: Treat your secret key like a password. Never commit it to source control or ship it in client-side code.

Step 2 — Confirm your key

A quick way to verify your key works and see which mode it's in.

Endpoint: GET /v1/account — requires a valid API key (no special scope).

cURL

curl https://api.ticketconnect.example/v1/account \
  -H "Authorization: Bearer sk_test_your_key_here"

Node (fetch)

const BASE = "https://api.ticketconnect.example/v1";
const KEY = "sk_test_your_key_here";

const res = await fetch(`${BASE}/account`, {
  headers: { Authorization: `Bearer ${KEY}` },
});
const account = await res.json();
console.log(account);

Example response:

{
  "id": "ten_8a1f...",
  "name": "Acme Tickets",
  "mode": "test",
  "status": "active",
  "currency": "USD"
}

The mode field tells you whether this key is test or live. The currency is your account's settlement currency — every price in this guide is in that currency.

Step 3 — Create an event

Endpoint: POST /v1/events — requires the events:write scope.

Only name and date are required. The other fields (venue, city, description, etc.) are optional.

cURL

curl https://api.ticketconnect.example/v1/events \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: evt-create-001" \
  -d '{
    "name": "Summer Sounds 2026",
    "date": "2026-08-15T19:00:00Z",
    "venue": "Riverside Arena",
    "city": "Austin",
    "country": "US"
  }'

Node (fetch)

const res = await fetch(`${BASE}/events`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "evt-create-001",
  },
  body: JSON.stringify({
    name: "Summer Sounds 2026",
    date: "2026-08-15T19:00:00Z",
    venue: "Riverside Arena",
    city: "Austin",
    country: "US",
  }),
});
const event = await res.json();
console.log(event.id); // evt_...

Example response (trimmed):

{
  "id": "evt_3f9c2a7b1e4d...",
  "name": "Summer Sounds 2026",
  "status": "draft",
  "date": "2026-08-15T19:00:00.000Z",
  "venue": "Riverside Arena",
  "city": "Austin",
  "country": "US",
  "currency": "USD",
  "ticketPools": [],
  "created_at": "2026-06-05T12:00:00.000Z"
}

Save the id (e.g. evt_3f9c2a7b1e4d...) — you'll use it as :id in the next steps.

Note: A new event starts in draft status with no ticket tiers yet. The date field accepts any value the standard date parser understands; an ISO 8601 timestamp is the safest choice.

Step 4 — Add a ticket tier

A tier defines a name, a fiat price, and how many tickets are available.

Endpoint: POST /v1/events/:id/tiers — requires the events:write scope.

Required fields: name (string), price (a non-negative number in your currency), and totalSupply (a positive integer). You may also send perks, upgradesEnabled, and advanced sale options (a published price_steps schedule, release_at / release_after_sold_out auto-release) — see the Events reference.

cURL

curl https://api.ticketconnect.example/v1/events/evt_3f9c2a7b1e4d.../tiers \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "General Admission",
    "price": 49.00,
    "totalSupply": 500,
    "upgradesEnabled": true
  }'

Node (fetch)

const eventId = "evt_3f9c2a7b1e4d...";

const res = await fetch(`${BASE}/events/${eventId}/tiers`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "General Admission",
    price: 49.0,
    totalSupply: 500,
    upgradesEnabled: true,
  }),
});
const event = await res.json();
console.log(event.ticketPools);

Example response (trimmed):

{
  "id": "evt_3f9c2a7b1e4d...",
  "name": "Summer Sounds 2026",
  "status": "draft",
  "currency": "USD",
  "ticketPools": [
    {
      "name": "General Admission",
      "price": 49,
      "totalSupply": 500,
      "issued": 0,
      "upgradesEnabled": true
    }
  ],
  "created_at": "2026-06-05T12:00:00.000Z"
}

The response is the full updated event. The tier you just added appears in ticketPools with issued: 0. You'll reference the tier later by its name (here, "General Admission").

Step 5 — Create a customer

A customer is just an email and a name, plus your own externalId so you can match the customer back to your system.

Endpoint: POST /v1/customers — requires the customers:write scope.

Required fields: externalId (your own id for this customer) and email. name is optional.

cURL

curl https://api.ticketconnect.example/v1/customers \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "user_42",
    "email": "fan@example.com",
    "name": "Jordan Rivera"
  }'

Node (fetch)

const res = await fetch(`${BASE}/customers`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    externalId: "user_42",
    email: "fan@example.com",
    name: "Jordan Rivera",
  }),
});
const customer = await res.json();
console.log(customer.id); // "user_42"

Example response:

{
  "id": "user_42",
  "email": "fan@example.com",
  "name": "Jordan Rivera",
  "status": "active",
  "created_at": "2026-06-05T12:01:00.000Z"
}

The customer's id is the externalId you supplied — use it as customer_id when issuing the ticket. The first time you reference a new customer the platform sets everything up behind the scenes, so the response is the same whether the customer is brand new or already on file.

Step 6 — Take payment

Because the tier above is priced above zero, the ticket must be paid for before it can be issued. Create a payment intent for the event and tier; the amount is computed server-side from the tier price, so you never send an amount.

Endpoint: POST /v1/payment_intents — requires the payments:write scope.

Required fields: event_id and tier. You may also pass customer_id.

cURL

curl https://api.ticketconnect.example/v1/payment_intents \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pi-summer-001" \
  -d '{
    "event_id": "evt_3f9c2a7b1e4d...",
    "tier": "General Admission",
    "customer_id": "user_42"
  }'

Node (fetch)

const res = await fetch(`${BASE}/payment_intents`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "pi-summer-001",
  },
  body: JSON.stringify({
    event_id: "evt_3f9c2a7b1e4d...",
    tier: "General Admission",
    customer_id: "user_42",
  }),
});
const intent = await res.json();
console.log(intent.id, intent.status);

Example response (trimmed):

{
  "object": "payment_intent",
  "id": "pi_1QabcDEF...",
  "amount": 49,
  "currency": "USD",
  "status": "requires_payment",
  "client_payload": { "client_secret": "pi_1QabcDEF..._secret_..." }
}

You collect the card payment on your side using client_payload (for example, with the standard payment SDK in your frontend). Once the payment succeeds, you'll pass the intent's id to the issuance call in the next step.

Note: In test mode, use the standard test card numbers to simulate a successful payment — no real money moves. See Test & live modes.

Step 7 — Issue the ticket

With a verified payment in hand, issue the ticket to your customer.

Endpoint: POST /v1/events/:id/tickets — requires the tickets:issue scope.

Required fields: customer_id, tier, and — for any paid tier — payment_intent_id. The platform re-verifies the payment, checks it matches this event and amount, and guards against using the same payment twice.

High-demand on-sale? If the event uses the on-sale waiting room (its queue field is non-null), the customer must be admitted by the queue before this call succeeds — otherwise it returns a 403 with a queue_error (not_admitted). Join and poll with POST /v1/events/:id/queue/join and GET /v1/events/:id/queue?customer_id=… (scope tickets:issue), then issue once status is admitted. Events without a queue are unaffected.

cURL

curl https://api.ticketconnect.example/v1/events/evt_3f9c2a7b1e4d.../tickets \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: issue-summer-001" \
  -d '{
    "customer_id": "user_42",
    "tier": "General Admission",
    "payment_intent_id": "pi_1QabcDEF..."
  }'

Node (fetch)

const eventId = "evt_3f9c2a7b1e4d...";

const res = await fetch(`${BASE}/events/${eventId}/tickets`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "issue-summer-001",
  },
  body: JSON.stringify({
    customer_id: "user_42",
    tier: "General Admission",
    payment_intent_id: "pi_1QabcDEF...",
  }),
});
const ticket = await res.json();
console.log(ticket.id); // tkt_...

Example response (trimmed):

{
  "id": "tkt_5b8e1c2d3f4a...",
  "event_id": "evt_3f9c2a7b1e4d...",
  "event_name": "Summer Sounds 2026",
  "status": "valid",
  "tier": "General Admission",
  "price": 49,
  "currency": "USD",
  "qr": {
    "data": "a1b2c3d4e5f6...",
    "format": "QR"
  },
  "created_at": "2026-06-05T12:02:00.000Z"
}

Every ticket is tamper-proof and anti-scalping is on by default — all handled for you (and configurable per event; see Marketplace and resale). The qr.data string is the opaque code your scanner reads at the door.

Tip: The same data is also delivered to your webhook as a ticket.issued event, so your systems can react in real time. See the Webhooks guide.

Step 8 — Get the ticket's QR / pass

You usually already have the ticket from Step 7, but you can fetch it any time to get its current status and delivery data.

Endpoint: GET /v1/tickets/:id — requires the tickets:read scope.

cURL

curl https://api.ticketconnect.example/v1/tickets/tkt_5b8e1c2d3f4a... \
  -H "Authorization: Bearer sk_test_your_key_here"

Node (fetch)

const ticketId = "tkt_5b8e1c2d3f4a...";

const res = await fetch(`${BASE}/tickets/${ticketId}`, {
  headers: { Authorization: `Bearer ${KEY}` },
});
const ticket = await res.json();
console.log(ticket.qr.data);

Example response (trimmed):

{
  "id": "tkt_5b8e1c2d3f4a...",
  "event_name": "Summer Sounds 2026",
  "status": "valid",
  "tier": "General Admission",
  "qr": {
    "data": "a1b2c3d4e5f6...",
    "format": "QR"
  },
  "created_at": "2026-06-05T12:02:00.000Z"
}

Render qr.data as a QR code and deliver it through your own app, email, or ticket page. No internal identifiers are ever returned.

Step 9 — Check in at the door

When the attendee arrives, validate the QR they present. Validation returns a verdict without consuming the ticket.

Endpoint: POST /v1/scan/validate — requires the scanning:write scope.

Required field: qr (the qr.data value from the ticket).

cURL

curl https://api.ticketconnect.example/v1/scan/validate \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "qr": "a1b2c3d4e5f6..." }'

Node (fetch)

const res = await fetch(`${BASE}/scan/validate`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ qr: "a1b2c3d4e5f6..." }),
});
const verdict = await res.json();
console.log(verdict.valid); // true

Example response (valid ticket):

{
  "valid": true,
  "status": "valid",
  "tier": "General Admission",
  "ticket_id": "tkt_5b8e1c2d3f4a..."
}

If the ticket has already been used or refunded, valid is false and reason explains why (for example "already_used" or "refunded").

Record the actual check-in. POST /v1/scan/validate only checks validity. To mark a ticket as attended, call POST /v1/tickets/:id/attendance (also scanning:write). It is safe to retry and reports already_used if the ticket was already checked in. To validate many codes at once while online, use POST /v1/scan/batch, which takes up to 200 codes in one call. For gates without a reliable connection, see Offline scanning.

Step 10 (optional) — Receive a webhook

Instead of polling, register a webhook endpoint and let TicketConnect push events to you — ticket.issued when a ticket is created, attendance.verified on check-in, and more. Webhooks are signed so you can verify them with existing SDKs.

Manage endpoints with POST /v1/webhook_endpoints (requires the webhooks:manage scope). See the full walkthrough in the Webhooks guide.

You did it

You just sold and scanned a ticket end-to-end:

1. Confirmed your key with GET /v1/account.
2. Created an event and a ticket tier.
3. Registered a customer.
4. Took a card payment and issued a tamper-proof ticket.
5. Fetched its QR pass and validated it at the door.

Next steps

• Authentication — keys, the Bearer transport, and the full scopes table.
• Test & live modes — go live safely after testing in the sandbox.
• How it works — the mental model behind events, tickets, and payments.
• Webhooks guide — receive real-time, signed events.
• API reference — every endpoint, parameter, and response.

Authentication

Every server-to-server request to the TicketConnect White-Label API is authenticated with a secret API key, sent as a bearer token. Keys are scoped so each one can do only what you allow — and every endpoint documents the scope it requires. A second, narrower kind of key — the publishable key — exists solely for the browser-facing hosted checkout surface (see below).

https://api.ticketconnect.example/v1

Secret keys

Your secret key authenticates server-to-server calls. Keys come in two flavours, distinguished by their prefix:

Test and live keys hit the same code paths, but their data never mixes. See Test & live modes for the full picture.

Warning: A secret key can create events, take payments, and issue tickets. Treat it like a password. Use it only from your backend — never embed it in a mobile app, single-page app, or anything that runs on a user's device.

Keys are shown once

When you create a key, the full value is returned exactly once, at creation. After that, TicketConnect stores only a hashed version and can never show you the plaintext again. Copy it immediately into a secrets manager or environment variable.

If you lose a key, you can't recover it — create a new one and revoke the old.

Self-serve key management

You can mint, list, and revoke keys through the API itself — no dashboard round-trip needed for rotation:

• POST /v1/account/keys mints a new key (the plaintext is in that response, once). A minted key's scopes must be a subset of the calling key's, and a test-mode key can never mint a live-mode key — no privilege escalation. Minting a live-mode key additionally requires live mode to be activated on the account; until then the request is rejected with mode_unavailable.
• GET /v1/account/keys lists your keys (prefix, label, scopes, timestamps); revoked keys stay listed as an audit trail. Secrets are never returned.
• DELETE /v1/account/keys/{prefix} revokes a key immediately. The calling key can never revoke itself, so a rotation always overlaps.

All three require the keys:manage scope, and active keys are capped at 25 per account. See the Account reference for the full endpoint details.

Publishable keys

Alongside secret keys, you can be issued publishable keys with a pk_ prefix (pk_test_… / pk_live_…). They exist for one purpose: the browser-facing hosted checkout surface. A publishable key:

• is safe to expose in a browser — it is always confined to the checkout:read and checkout:write scopes, regardless of what is stored on the key;
• only works on the /v1/checkout/… endpoints — every secret endpoint rejects a publishable key with a 401;
• carries the same test/live mode split in its prefix as a secret key.

The reverse also holds: secret (sk_) keys are rejected on the publishable checkout surface, so a leaked page can never be escalated. See the Payments reference for the checkout endpoints themselves.

The Authorization header

Send your key as a bearer token in the Authorization header on every request:

Authorization: Bearer sk_test_your_key_here

cURL

curl https://api.ticketconnect.example/v1/account \
  -H "Authorization: Bearer sk_test_your_key_here"

Node (fetch)

const res = await fetch("https://api.ticketconnect.example/v1/account", {
  headers: { Authorization: "Bearer sk_test_your_key_here" },
});
const account = await res.json();
console.log(account.mode); // "test" or "live"

A good first call is GET /v1/account — it confirms the key is valid and tells you which mode it operates in.

If your HTTP client makes the Authorization header awkward to set, the API also accepts the same key in an x-api-key header. Prefer the Bearer transport — it is what every example in these docs uses.

Note: A few endpoints are public and need no key at all: GET /v1/health (uptime checks), GET /v1/openapi.json (the machine-readable spec, useful for codegen before you have a key), and GET /v1/docs (the interactive Swagger UI). Everything else requires authentication.

Key safety & rotation

• Store keys as secrets. Use environment variables or a secrets manager — never source control.
• Use one key per environment. Keep test and live keys separate, and ideally scope keys per integration so you can revoke one without breaking others.
• Rotate regularly, and immediately if a key may have leaked. Mint a new key with POST /v1/account/keys, deploy it, then revoke the old one with DELETE /v1/account/keys/{prefix}. Because keys are stored hashed, revocation is the only remediation for a compromised key.
• Grant least privilege. Give each key only the scopes it needs (see below). A scanning app at the door, for example, needs scanning:write and nothing more.

Scopes

Each key carries a set of scopes that define exactly which operations it can perform. If a key is missing a scope an operation needs, the request is rejected with the standard error envelope and an HTTP 403:

{
  "error": {
    "type": "authorization_error",
    "code": "forbidden",
    "message": "Missing required scope: events:write",
    "request_id": "8f2c1a4e-…"
  }
}

The full set of scopes and what each unlocks:

Read access is implied by write where it makes sense. A payments:write key can read back the payments it created, and payouts:claim includes everything payouts:read can do. When in doubt, the per-endpoint documentation in the API reference states the exact scope required.

Next steps

• Test & live modes — integrate in the sandbox first, then go live.
• Quickstart — sell and scan a ticket end-to-end.
• API reference — every endpoint and its required scope.

Test & live modes

TicketConnect gives you two fully separate environments, selected entirely by which key you use. There is no separate sandbox URL and no flag to flip — the key's prefix decides the mode.

Note: Live mode must be activated on your account before it can be used. Until it is, sk_live_ keys cannot be created, and any live key presented to the API is rejected with a 403 — never silently downgraded to test. Test mode is always available.

https://api.ticketconnect.example/v1

The base URL is the same for both. Send a test key and you're in the sandbox; send a live key and you're in production.

Same code paths, isolated data

A test key exercises the same API contract as a live key. Provider credentials, Connect accounts, chain configuration, and original payment proof must also match the selected mode:

• Test events, tiers, customers, tickets, payments, and payouts live in a separate sandbox and never appear in your live data (and vice versa).
• Payments in test mode are simulated — use the standard test card numbers to trigger success or failure. No real money ever moves.
• Webhooks, reports, balances, and scanning all work the same way in test, scoped to your test data only.

Warning: The two worlds never cross. A sk_test_ key cannot read or modify live data, and a sk_live_ key cannot see anything you created in test. An id created in one mode is meaningless in the other.

Telling which mode a key is in

There are two reliable ways:

1. The prefix. sk_test_… is test; sk_live_… is live.
2. Ask the API. GET /v1/account returns a mode field:

cURL

curl https://api.ticketconnect.example/v1/account \
  -H "Authorization: Bearer sk_test_your_key_here"

Node (fetch)

const res = await fetch("https://api.ticketconnect.example/v1/account", {
  headers: { Authorization: "Bearer sk_test_your_key_here" },
});
const { mode } = await res.json();
console.log(mode); // "test"

{
  "id": "ten_8a1f...",
  "name": "Acme Tickets",
  "mode": "test",
  "status": "active",
  "currency": "USD"
}

Best practices

• Build in test first. Wire up your entire flow — create an event, take a payment, issue a ticket, scan it — using a sk_test_ key before you touch live. Run the Quickstart end-to-end in test.
• Key your config by mode. Store sk_test_ and sk_live_ keys in separate environment variables and select the right one per deployment. Never hardcode a key or let a live key leak into a staging build.
• Test the unhappy paths too. Use test cards to simulate declined payments, and exercise refunds, already-used scans, and missing-scope errors so your error handling is solid before launch.
• Verify webhooks in test. Register a test webhook endpoint and confirm you receive and verify signed events before relying on them in production. See the Webhooks guide.
• Activate and configure live mode. Enable live access, configure live provider credentials, and complete live Connect onboarding. Then select the live key and check GET /v1/account reports "mode": "live". Missing or mismatched provider configuration is rejected; the API does not borrow live credentials for a test request.

Provider credentials and Connect account IDs are mode-specific. PayPal uses its sandbox endpoint in test and production endpoint in live. Crypto proof binds the original chain, token, recipient, and successful receipt to the requested mode. An old account ID or payment without provable mode cannot authorize a live money operation.

A successful sandbox test checks your integration contract. It does not confirm live provider capabilities, funded balances, or bank settlement.

Next steps

• Quickstart — run the full flow in test mode.
• Authentication — key formats, the Bearer transport, and scopes.
• API reference — every endpoint in detail.

How it works

The White-Label API gives you one job: call REST over /v1. Everything that makes a ticket trustworthy and every cent of settlement happens behind that boundary, automatically. You think in events, tickets, prices, and customers — nothing else.

You make a normal HTTPS request with a bearer key; we do the hard parts and return plain JSON. No SDK is required, though the OpenAPI document makes one easy to generate.

The object model

Everything you create lives in a simple hierarchy, plus a few free-standing resources that hang off it.

Account  (you — the partner)
  └─ Events               a show, match, conference, etc.
        └─ Tiers           price levels within an event (GA, VIP, …)
              └─ Tickets   issued to a customer, each tamper-proof

Organizations  read-only organizer directory your account can browse
Customers      email-first people who hold tickets
Payments       card charges that gate issuance and upgrades
Queues         on-sale waiting rooms for high-demand events
Listings       secondary-market resale entries for tickets
Payouts        fiat transfers of your balance to your bank

Built-in guarantees

Several hard problems are handled by the platform itself — there is nothing to integrate, configure, or operate on your side. You get the benefits without the complexity:

• Tamper-proof tickets — every ticket is verifiable and cannot be forged or duplicated.
• Built-in anti-scalping — resale rules are enforced automatically on the marketplace.
• Automatic resale royalties — you keep earning on the secondary market with no extra work.
• Plain fiat, end to end — prices, charges, refunds, and payouts are all in your account's currency.

Note: You work entirely in business language: events, tiers, fiat prices, customer emails, QR codes, and bank payouts. The tamper-proof layer is an implementation detail you never have to learn.

Test vs live

Every account has an isolated test mode (sk_test_…) and live mode (sk_live_…); test data never mixes with live. See Test & live modes.

Customers

A customer is the person who holds a ticket. Customers are email-first: you create one with your own externalId and an email (plus an optional name), and from then on you reference it by its id — which is simply the externalId you supplied. That is the entire model you need to know.

Tip: No account or credential is ever requested from a customer or returned to you. A customer is just { id, email, name, status } plus the tickets they hold.

Creating a customer

Send your own externalId and an email (a name is optional). You get back a customer whose id is that same externalId — use it everywhere else (issuance, transfers, lookups).

curl

curl https://api.ticketconnect.example/v1/customers \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "user_42",
    "email": "ada@example.com",
    "name": "Ada Lovelace"
  }'

Response

{
  "id": "user_42",
  "email": "ada@example.com",
  "name": "Ada Lovelace",
  "status": "active",
  "created_at": "2026-06-05T12:01:00.000Z"
}

Requires the customers:write scope. This endpoint accepts an Idempotency-Key header so retries are safe.

Provisioning happens transparently

Creating the customer is the only setup step. The moment you POST /v1/customers, the platform quietly does everything needed to make that customer's future tickets tamper-proof and deliverable behind the scenes:

• It is idempotent — creating the same externalId again returns the existing customer unchanged; nothing is set up twice, and retries are safe.
• It is invisible — none of the internal setup is exposed in your request or response, and it never asks the customer for anything.
• It is required before issuance — a ticket can only be issued to a customer that already exists; referencing an unknown customer_id at issuance returns a 404.

In short: create the customer first, then issue tickets. The platform handles the rest.

The relationship to tickets

Every ticket belongs to exactly one customer at a time. You reference the customer's id as customer_id when issuing, and retrieve the customer record itself at any time:

curl https://api.ticketconnect.example/v1/customers/user_42 \
  -H "Authorization: Bearer sk_test_your_key_here"

When you transfer a ticket, it simply moves from one customer to another — the ticket's identity and tamper-proof guarantees are unchanged.

Reference

See the full Customers API reference for field details.

Money & currencies

Public prices, payment amounts, balances, and payouts use the currency's major unit. 49.50 USD means $49.50; 1000 JPY means ¥1000. Internally, payments and allocations use whole native minor units: USD 49.50 is 4950 cents, while JPY 1000 is 1000 yen.

The server derives the amount and currency from the event, tier, quantity, and applicable discount. A request cannot replace that price or change the currency: a supplied currency must match the server's currency. Fractional minor units, non-finite amounts, and unsupported payment rails are rejected.

Payment proof and allocations

A paid ticket requires a completed payment with the correct account, mode, currency, and sufficient amount. The platform reserves each allocation atomically with ticket stock. A payment can fund supported partial or batch allocations, but their combined amount cannot exceed the original confirmed collection. Issuance and upgrades share this budget.

Your account's payment provider supplies the client payment details. Stripe uses a client secret, PayPal uses an approval URL, and an external provider records your assertion that you collected payment elsewhere. The v1 crypto adapter supports its verified USD/USDC rail; it does not convert arbitrary fiat currencies into USDC.

A completed external, PayPal, or crypto payment can prove a purchase without funding the platform's Stripe payout balance. Payment completion and money available for a Stripe transfer are separate facts.

Refunds

Refunds use the original payment allocations, currency, and mode. The original purchase and each paid upgrade are separate sources; changing a tier price later does not change the refund budget. The total refunded from a source cannot exceed its confirmed paid amount.

A refund reservation reverses the booked seller net and fee history before provider effects. Only a confirmed refund completes the allocation. Pending receipts stay held for recovery; missing provenance, failed or canceled receipts, depleted refundable balances, and unsupported resale clawbacks require review. See Transfer, refund & upgrade.

Available balance and transfers

GET /v1/balance reports available, proven platform-held Stripe funds after fees, refunds, and payout reservations. It excludes externally collected funds, PayPal and crypto collections, unknown legacy credits, and money already routed to a connected account.

POST /v1/payouts transfers that balance to your mode-specific Stripe Connect account. transferred confirms the Stripe transfer; it does not confirm a deposit in your bank account. Stripe's connected-account bank payout follows its own lifecycle. See Payouts.

The ledger balance is not Stripe’s net available-cash report. Processor costs are a platform expense requiring separate liquidity; a provider can refuse a transfer when its actual available balance is insufficient.

Idempotency

Send one Idempotency-Key for each logical mutation and reuse it with the same request whenever you retry. Use it on every payment, issuance, upgrade, refund, and payout integration call. POST /v1/payouts requires a non-empty key of at most 255 characters; endpoints that retain optional headers should still receive a key from your integration.

How it works

The platform atomically claims the key before an effect starts. The claim is scoped to your account and mode and includes the request method, path, and body hash.

• A completed retry returns the stored status and response.
• The same key with a different request returns 409 idempotency_key_reuse.
• An operation already running can return 409 idempotency_in_progress; money operations with a durable reservation can instead return their pending state.
• A crash or ambiguous provider response keeps the original operation held for recovery. Sending a fresh key does not resolve that uncertainty.

Completed response snapshots expire after approximately 24 hours. Unresolved claims do not expire as completed responses do. Durable financial operation records and unique payment allocations remain authoritative after the response cache expires.

For an unknown Stripe transfer or refund with no receipt ID, automatic retries stop before the provider's idempotency retention can expire: the platform uses a 23-hour ceiling from the original attempt and holds the operation for review. A known Stripe or PayPal refund receipt is recovered by GET, including after that ceiling, without creating another refund.

Choose one key per operation

A random UUID is a convenient choice. Store it with your order or refund record before sending the request.

KEY=$(uuidgen)
curl https://api.ticketconnect.example/v1/events/evt_123/tickets \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Idempotency-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{ "customer_id": "user_42", "tier": "General Admission" }'

If the request times out, retry this exact request with the stored key. Do not generate a replacement key for the retry.

Supported endpoints

The header is honored on mutating POST endpoints including customers, events, tiers, ticket issuance, payment intents, ticket refunds and upgrades, attendance, and payouts. Unsupported endpoints may ignore it; the header does not add replay protection to an endpoint that has no idempotent handler.

A provider receipt marked failed, canceled, or pending is not a completed refund. Preserve the original key and follow the returned state. See Errors, Payments, and Payouts.

Errors

Every error response uses a single, predictable envelope — the same shape across the entire API. Branch your handling on the machine-readable type and code; show or log the message; quote the request_id to support.

The error envelope

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "tier is required.",
    "param": "tier"
  }
}

Error types

Common codes

Note: New code values can be added over time within an existing type. Always handle the type you recognize and treat unknown codes within it gracefully rather than failing hard.

HTTP status mapping

The HTTP status and the error.type agree, so you can react to either:

Using request_id for support

Every response — success or error — carries a correlation id in the x-request-id response header; authentication, authorization, rate-limit, and unexpected platform errors also include it in the envelope as error.request_id. When something goes wrong, capture and log it. If you contact support, quoting the id lets us locate the exact request instantly — no guessing required.

# Log the correlation id from any response.
curl -si https://api.ticketconnect.example/v1/events/evt_does_not_exist \
  -H "Authorization: Bearer sk_test_your_key_here" \
  | grep -i x-request-id

Example error responses

401 Authentication

{
  "error": {
    "type": "authentication_error",
    "code": "unauthorized",
    "message": "Invalid API key",
    "request_id": "1b9d33a0-…"
  }
}

409 Idempotency

{
  "error": {
    "type": "idempotency_error",
    "code": "idempotency_key_reuse",
    "message": "This Idempotency-Key was used with a different request."
  }
}

429 Rate limit

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limited",
    "message": "Rate limit exceeded",
    "request_id": "4e8a90fb-…"
  }
}

See Idempotency for the 409 case in context.

Pagination

List endpoints return results in pages using cursor pagination. You control the page size with limit and walk forward with starting_after, using the id of the last item you received as the cursor for the next page.

The list envelope

Every list endpoint returns the same shape:

{
  "object": "list",
  "data": [
    { "id": "evt_300", "...": "..." },
    { "id": "evt_299", "...": "..." }
  ],
  "has_more": true
}

Query parameters

Results are ordered newest-first. To fetch the next page, take the id of the last item in data and pass it as starting_after. Keep going while has_more is true.

Which endpoints support it

Cursor pagination applies to every list endpoint, including:

• GET /v1/events
• GET /v1/tickets
• GET /v1/marketplace/listings
• GET /v1/discounts
• GET /v1/payouts
• GET /v1/events/deliveries (webhook deliveries)

Some list endpoints also accept filters (for example event_id on GET /v1/tickets); filters compose with pagination.

Paging through every result

curl

#!/usr/bin/env bash
KEY="sk_test_your_key_here"
BASE="https://api.ticketconnect.example/v1/events?limit=100"
after=""

while :; do
  url="$BASE"
  [ -n "$after" ] && url="$BASE&starting_after=$after"

  page=$(curl -s "$url" -H "Authorization: Bearer $KEY")

  echo "$page" | jq -c '.data[]'

  has_more=$(echo "$page" | jq -r '.has_more')
  [ "$has_more" != "true" ] && break

  after=$(echo "$page" | jq -r '.data[-1].id')
done

Node

const KEY = "sk_test_your_key_here";
const BASE = "https://api.ticketconnect.example/v1/events";

async function* listAllEvents() {
  let startingAfter;

  while (true) {
    const url = new URL(BASE);
    url.searchParams.set("limit", "100");
    if (startingAfter) url.searchParams.set("starting_after", startingAfter);

    const res = await fetch(url, {
      headers: { Authorization: `Bearer ${KEY}` },
    });
    const page = await res.json();

    for (const item of page.data) yield item;

    if (!page.has_more) break;
    startingAfter = page.data[page.data.length - 1].id;
  }
}

for await (const event of listAllEvents()) {
  console.log(event.id);
}

Note: Use the largest limit (100) when bulk-syncing to minimize round trips, and a smaller limit for interactive, user-facing lists.

Issue a ticket

Issuing a ticket is how you put a real, scannable ticket in a customer's hands. You tell TicketConnect which event, which tier, and which customer, and (for paid tiers) attach the payment that funds it. The platform creates a tamper-proof ticket and returns it with everything you need to deliver it.

Use this guide when you've already built your event catalog and you're ready to sell. If you haven't created an event, a tier, or a customer yet, do that first — they're prerequisites for every issuance.

Before you start

You'll need:

• An API key with the tickets:issue scope (and payments:write if you also create the payment yourself — see Take a payment).
• An event that exists under your account.
• A ticket tier on that event (name, fiat price, supply).
• A customer record that is fully provisioned (status: "active"). A customer created moments ago may still be pending; issuance to a non-provisioned customer is rejected.

Base URL for every call:

https://api.ticketconnect.example/v1

Step 1 — Take payment for the ticket

Paid tiers require a verified payment before a ticket can be issued. Create a payment intent for the event and tier; the amount is computed server-side from the tier price, so you never pass an amount yourself.

curl https://api.ticketconnect.example/v1/payment_intents \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "evt_summerfest",
    "tier": "General Admission",
    "customer_id": "user_a1b2c3"
  }'

{
  "object": "payment_intent",
  "id": "pi_3PxyzABC",
  "provider": "stripe",
  "client_payload": { "client_secret": "pi_3PxyzABC_secret_..." },
  "amount": 49.00,
  "currency": "USD",
  "status": "requires_payment"
}

Collect the card details and complete the payment on the client using the returned client_payload (for Stripe, its client_secret), exactly as you would with Stripe. Once the payment status is succeeded, you're ready to issue. Full details, including test cards, are in Take a payment.

Free and comp tickets skip this step. If the tier price is 0, you can issue without a payment_intent_id.

Step 2 — Issue the ticket

Call the issuance endpoint with the customer, the tier, and the payment that funds it.

High-demand on-sale? Get the customer admitted first. If the event runs an on-sale waiting room (its event object has a non-null queue), issuance is gated on queue admission: join the queue with POST /v1/events/:id/queue/join, poll GET /v1/events/:id/queue?customer_id=... until status is admitted (with a live access_expires_at), then issue. Issuing before admission returns 403 with error type queue_error and code not_admitted. Events without a waiting room are unaffected.

Endpoint: POST /v1/events/:id/tickets · Scope: tickets:issue

curl https://api.ticketconnect.example/v1/events/evt_summerfest/tickets \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: issue_order_88231" \
  -d '{
    "customer_id": "user_a1b2c3",
    "tier": "General Admission",
    "payment_intent_id": "pi_3PxyzABC"
  }'

{
  "id": "tkt_4f8a9c0d1e2f",
  "event_id": "evt_summerfest",
  "event_name": "Summer Fest 2026",
  "status": "valid",
  "tier": "General Admission",
  "price": 49.00,
  "currency": "USD",
  "perks": { "entry": "main_gate" },
  "qr": {
    "data": "8f2c1a...e7",
    "format": "QR"
  },
  "created_at": "2026-06-05T14:22:00.000Z"
}

A 201 response means the ticket is issued. The customer now holds it.

What the returned ticket contains

To turn this into something a customer can use — rendered in your app, email, or the hosted checkout — see Deliver tickets.

Reserved seating: seatmap → hold → issue

If the event has a published seat map, its seated tiers are sold by the seat, and issuing on such a tier without a hold is rejected with 400 seat_required. The flow adds one step in front of payment:

1. Read the map. GET /v1/events/:id/seatmap (scope events:read) returns the layout, live availability (sold / held / blocked seat ids), and per-tier pricing — render it and let the customer pick seats.
2. Hold the seats. POST /v1/events/:id/seats/hold with { "seat_ids": ["S1-A-1", "S1-A-2"] } (scope tickets:issue, up to 10 seats) atomically claims them for 10 minutes and returns a hold_id. If someone got there first you get 409 seats_unavailable naming the contested seats.
3. Take the payment. The payment must cover the tier price × the number of held seats. Card entry running long? POST /v1/events/:id/seats/hold/:holdId/extend resets the clock to 10 minutes from now.
4. Issue with the hold. Call POST /v1/events/:id/tickets as usual, plus "hold_id": "..." — one ticket is issued per held seat, each bound to its seat, and the response becomes a batch:

{
  "tickets": [
    { "id": "tkt_...", "tier": "Stalls", "seat": "A-1", "qr": { "data": "...", "format": "QR" } },
    { "id": "tkt_...", "tier": "Stalls", "seat": "A-2", "qr": { "data": "...", "format": "QR" } }
  ]
}

Pass "quantity": 2 alongside hold_id as a safety check — issuance fails with 400 quantity_mismatch unless it equals the number of held seats (any quantity other than 1 requires a hold_id). If the customer walks away, release the hold with DELETE /v1/events/:id/seats/hold/:holdId (or just let it lapse). An expired hold fails issuance with 409 hold_expired — re-hold and retry. See Reserved seating for the full endpoint contracts.

How issuance protects you

The endpoint enforces several rules so you can't accidentally oversell or double-charge:

• Payment must be verified, matching, and unused. For a paid tier, the payment_intent_id you pass is checked server-side against the expected amount, currency, event, and your account. A payment that doesn't match, or that has already funded a ticket, is rejected.
• No double-spend. A single payment can fund at most one ticket. Reusing a payment returns 409 payment_already_used.
• No overselling. Supply for each tier is claimed atomically. If the last seat is taken by a concurrent issue, you get 409 sold_out and no ticket is created.
• Waiting-room admission. On events with an on-sale queue, a ticket is only issued to a customer who currently holds a live admission window — see the hint in Step 2.
• Per-person purchase caps. If the event sets a per-person ticket limit (max_tickets_per_identity), issuance past the cap — including free and comp tickets — returns 403 purchase_limit_reached.

Always send an Idempotency-Key. If a network hiccup makes you retry an issuance, the same key returns the original ticket instead of creating a second one (and double-claiming supply). Keys are honored for 24 hours.

Common errors

See also

• Take a payment — create and confirm the card payment.
• Deliver tickets — get the QR into your customer's hands.
• Transfer, refund & upgrade — lifecycle operations.
• API reference: issue a ticket

Take a payment

A paid ticket needs a verified payment from your account's configured provider. Create a payment intent for an event and tier, complete the provider's payment flow, and attach that reference when issuing or upgrading a ticket. Stripe returns a client secret, PayPal an approval URL, and external payments require your server-side confirmation.

If you've integrated Stripe before, this will feel familiar: a server-created intent, a client-side confirmation, and a status you can poll. The key difference is that TicketConnect computes the amount for you — you never send a price, so a client can't tamper with what gets charged.

Before you start

You'll need:

• An API key with the payments:write scope to create payments.
• An event with at least one priced tier.

Reading a payment back (GET /v1/payments/:id) is allowed with either payments:write or payments:read.

Base URL:

https://api.ticketconnect.example/v1

Step 1 — Create a payment intent

Endpoint: POST /v1/payment_intents · Scope: payments:write

Tell the API which event and tier the customer is buying. The amount is derived server-side from that tier's fiat price.

curl https://api.ticketconnect.example/v1/payment_intents \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pay_order_88231" \
  -d '{
    "event_id": "evt_summerfest",
    "tier": "General Admission",
    "customer_id": "user_a1b2c3"
  }'

{
  "object": "payment_intent",
  "id": "pi_3PxyzABC",
  "provider": "stripe",
  "client_payload": { "client_secret": "pi_3PxyzABC_secret_..." },
  "amount": 49.00,
  "currency": "USD",
  "status": "requires_payment"
}

The amount is server-authoritative. There is no amount field in the request body, and any extra keys are ignored. The charge always equals the tier price on your event, in the server's event/account currency; a supplied currency must match. This is what stops a manipulated client from underpaying.

The client_payload carries the details your client needs to confirm the card (for the Stripe provider, a client_secret). Pass it to the TicketConnect client integration the same way you'd hand a client secret to Stripe's SDK, and confirm the card in the browser or app.

Step 2 — Confirm the card

Card confirmation happens on the client, with the customer's card details — they never touch your server. After the customer submits their card, the payment moves toward succeeded.

Test cards

In test mode (sk_test_... keys), use your payment provider's standard test cards to simulate outcomes — a card that always succeeds, one that always declines, one that triggers authentication, and so on. Test-mode payments are fully isolated from live data, so you can run a full issuance end-to-end without charging anyone.

Step 3 — Retrieve a payment

Check a payment's current status at any time.

Endpoint: GET /v1/payments/:id · Scope: payments:read or payments:write

curl https://api.ticketconnect.example/v1/payments/pi_3PxyzABC \
  -H "Authorization: Bearer sk_test_..."

{
  "object": "payment_intent",
  "id": "pi_3PxyzABC",
  "amount": 49.00,
  "currency": "USD",
  "status": "succeeded"
}

A payment is only ever visible to the account that created it; requesting a payment that belongs to another account returns 404 resource_missing.

How a payment ties into issuance and upgrades

A payment on its own doesn't put a ticket in anyone's hands — it's the funding proof you attach to the next step:

• Issuance. Pass the payment as payment_intent_id to POST /v1/events/:id/tickets. The payment must be succeeded, match the tier amount, currency, account, and mode. Its combined allocations across tickets and upgrades cannot exceed the original confirmed collection. See Issue a ticket.
• Upgrades. When a customer moves to a more expensive tier, you create a payment for the price difference and attach it to the upgrade call. See Transfer, refund & upgrade.

Waiting-room events: charge after admission. If the event runs an on-sale queue (its event object has a non-null queue), admission is enforced when the ticket is issued — not when the intent is created. Join the queue and poll GET /v1/events/:id/queue?customer_id=... until status is admitted before you take the payment; otherwise the charge can succeed and issuance still return 403 not_admitted until the customer is admitted.

Reserved seating: hold the seats before you charge. On events with a published seat map, hold the customer's seats first (POST /v1/events/:id/seats/hold — seats stay yours for 10 minutes), then take the payment, then issue with the returned hold_id. Pass quantity: <held seats> when creating the payment intent — the server charges tier price × quantity, matching what issuance will verify. If card entry runs long, extend the hold (POST /v1/events/:id/seats/hold/:holdId/extend) so the seats don't lapse mid-payment. See Issue a ticket for the full flow.

Payment completion does not always fund a Stripe payout. External, PayPal, and crypto collections remain on their original rail; only proven platform-held Stripe funds contribute to the v1 payout balance. A payout transfers to your Stripe Connect account and does not confirm a bank deposit. See Money & currencies.

Use an Idempotency-Key on every create. Retrying a payment-intent creation with the same key returns the original intent instead of creating a duplicate charge. Completed response snapshots last about 24 hours; unresolved financial operations retain their original claim for recovery. See Idempotency.

Common errors

See also

• Issue a ticket — turn a successful payment into a ticket.
• Transfer, refund & upgrade — charge the difference on an upgrade.
• API reference: payments

Deliver tickets

Once a ticket is issued, you need to put it somewhere the customer can use it at the door. Every issued ticket carries an opaque QR string — the delivery contract — that you render as a QR code wherever fits your product: your own app, an email, a printed PDF.

Use this guide after you've issued a ticket (see Issue a ticket). Everything here reads from a single endpoint: GET /v1/tickets/:id.

The delivery options

The raw QR string is always available the moment a ticket is issued, and it is the same code the hosted ticket page and the hosted checkout display.

Before you start

You'll need:

• An API key with the tickets:read scope.
• An issued ticket id (tkt_...).

Base URL:

https://api.ticketconnect.example/v1

Step 1 — Fetch the ticket

Endpoint: GET /v1/tickets/:id · Scope: tickets:read

curl https://api.ticketconnect.example/v1/tickets/tkt_4f8a9c0d1e2f \
  -H "Authorization: Bearer sk_test_..."

{
  "id": "tkt_4f8a9c0d1e2f",
  "event_id": "evt_summerfest",
  "event_name": "Summer Fest 2026",
  "status": "valid",
  "tier": "General Admission",
  "qr": {
    "data": "8f2c1a...e7",
    "format": "QR"
  },
  "created_at": "2026-06-05T14:22:00.000Z"
}

The qr.data field is your raw QR string, and qr.format tells you how to render it (e.g. QR).

Step 2 — Present the ticket to your customer

Option A — Render the QR string yourself

Take qr.data and render it as a QR code with any standard library in your stack, then show it in your app, your email, or a printed PDF. This is the most flexible option and works everywhere.

qr.data is an opaque string. It's a random value that uniquely identifies the ticket for scanning — it carries no personal or sensitive data, and it isn't a price, a customer id, or anything you should parse. Just render it.

Option B — Let the hosted checkout show it

If the ticket was bought through the hosted checkout page (GET /v1/checkout/:eventId?key=pk_...), the buyer sees the rendered QR code on-screen the moment the purchase completes — no front-end work on your side. It's the same qr.data you can fetch later with GET /v1/tickets/:id, so you can re-deliver it through your own channels at any time.

Option C — Send a hosted ticket page link

Mint a signed link to a ready-made mobile ticket page and deliver that — in an email, an SMS, or a "view your ticket" button:

curl https://api.ticketconnect.example/v1/tickets/tkt_4f8a9c0d1e2f/delivery_link \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "expires_in_days": 30 }'

{
  "object": "delivery_link",
  "url": "https://api.ticketconnect.example/v1/t/dGt0XzRmOGE5YzBkLi4u...",
  "expires_at": "2026-08-10T14:22:00.000Z"
}

Links are bound to the QR code they were minted for. A transfer rotates the ticket's code, so every previously minted delivery link stops working — the old holder's link can never show the new holder's code. Mint a fresh link after a transfer. Revoking the signing secret (TICKET_LINK_SECRET) invalidates all outstanding links at once.

The page shows your logo, the event details, the holder's name and masked email, a live status badge, and the rendered entry QR — self-contained, mobile first, no login. It is live: a refund or revocation flips the badge the moment it happens, so the page is always truthful even while the link stays valid. Links expire after expires_in_days (1–90, default 30); expired or tampered links all render one identical 404 page. Minting needs only the tickets:read scope. See the API reference for the full contract.

No pass file through this API. /v1 does not expose an Apple/Google pass file for a ticket — the hosted ticket page is the ready-made delivery surface, and qr.data remains the delivery contract for everything you build yourself. Holders who keep the ticket in a ticket wallet on the TicketConnect rails can save it to Apple/Google Wallet from there — but only for events with live_codes off: a wallet pass is a static barcode, and the platform refuses one where a live, refreshing code is enforced (that refusal is what makes the anti-screenshot layer real).

At the door

Whichever way the customer receives it, your scanners validate it through the same endpoints. The ticket's status reflects its lifecycle — a freshly issued ticket is valid, and it becomes used after check-in. A refunded ticket surfaces as refunded here (a transfer keeps the ticket valid — same ticket, new owner), and a revoked ticket keeps its status but carries revoked: true and fails every scan. A quick GET /v1/tickets/:id always tells you whether a ticket is good to admit.

Holders may also present the ticket from a ticket wallet. A customer who keeps their ticket in a wallet on the TicketConnect rails (Gettix, our flagship licensee, is the reference holder experience) shows a live code that refreshes every few seconds instead of your static one. Your scanning endpoints validate both — send whatever was scanned, verbatim, and read the verdict (see Scanning & check-in). Your qr.data stays valid alongside it. One consequence to know about: once the holder has opened the ticket in a wallet, the ticket is locked to them — POST /v1/tickets/:id/transfer then returns 409 ticket_not_transferable. Live codes are on by default and togglable per event (live_codes on the events API).

See also

• Issue a ticket — create the ticket you're delivering.
• Transfer, refund & upgrade — what happens to delivery after a lifecycle change.
• API reference: retrieve a ticket

Transfer, refund & upgrade

Issuing a ticket isn't the end of its life. Customers change plans, want a better seat, or need their money back. This guide covers the three lifecycle operations you'll reach for most: transferring a ticket to another customer, refunding it, and upgrading it to a higher tier.

All of these operations use the same scope and act on a ticket id (tkt_...).

Before you start

You'll need:

• An API key with the tickets:manage scope — required for every operation in this guide.
• An issued ticket id.
• For upgrades that cost money, a payment for the price difference (scope payments:write; see Take a payment).

Base URL:

https://api.ticketconnect.example/v1

Every operation returns the updated ticket, and each mutating call accepts an Idempotency-Key header for safe retries.

Transfer a ticket

Reassign a ticket to a different customer — for example, when the original buyer gives it to a friend.

Endpoint: POST /v1/tickets/:id/transfer · Scope: tickets:manage

Pass the recipient as to_customer_id. The recipient must be an existing, provisioned customer under your account.

curl https://api.ticketconnect.example/v1/tickets/tkt_4f8a9c0d1e2f/transfer \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: transfer_88231" \
  -d '{ "to_customer_id": "user_99887766" }'

{
  "id": "tkt_4f8a9c0d1e2f",
  "event_id": "evt_summerfest",
  "event_name": "Summer Fest 2026",
  "status": "valid",
  "tier": "General Admission",
  "qr": { "data": "8f2c1a...e7", "format": "QR" },
  "created_at": "2026-06-05T14:22:00.000Z"
}

The ticket now belongs to the new customer — and the QR code rotates: the response (and the ticket.transferred webhook) carries a fresh qr.data, and the previous code stops scanning immediately. That kills any screenshot the previous holder kept, and it also invalidates any hosted delivery links minted before the transfer — mint a new one for the new holder.

The recipient must exist first. If to_customer_id doesn't match a provisioned customer, you get 404 customer_not_found. Create the customer before transferring.

A ticket opened in a holder's ticket wallet can't be transferred. Once the holder has opened the ticket in a wallet built on the TicketConnect rails (any holder experience built on those rails — Gettix, our flagship licensee, is the reference one), it is locked to them and POST /v1/tickets/:id/transfer returns 409 ticket_not_transferable (the same code a used or refunded ticket gets). Refunds are unaffected — a refunded ticket fails every scan regardless.

Refund a ticket

Cancel a ticket and reverse the customer's payment.

Endpoint: POST /v1/tickets/:id/refund · Scope: tickets:manage

curl https://api.ticketconnect.example/v1/tickets/tkt_4f8a9c0d1e2f/refund \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: refund_88231" \
  -X POST

{
  "id": "tkt_4f8a9c0d1e2f",
  "event_name": "Summer Fest 2026",
  "status": "refunded",
  "tier": "General Admission",
  "qr": { "data": "8f2c1a...e7", "format": "QR" },
  "created_at": "2026-06-05T14:22:00.000Z"
}

The platform reserves the refund and blocks entry before asking the provider to return money. It refunds the original purchase and each paid upgrade as separate allocations in their original currency and mode. It reverses the original booked seller net and fees rather than the ticket's current displayed price.

The ticket becomes refunded and emits ticket.refunded only when every required refund is confirmed. A pending Stripe or PayPal refund keeps its receipt ID and is recovered by GET, without another refund POST. A failed or canceled receipt, missing original proof, unsupported external refund, or depleted refundable funds stays held for review; it is not reported as refunded.

Retry with the original Idempotency-Key and identical request. A completed replay returns the original result. A separate request for an already refunded ticket can return 409 already_refunded.

Upgrade a ticket to a higher tier

Move a ticket up to a more expensive tier, charging the customer the fiat difference. The ticket keeps its id and its QR code — only the tier, perks, and price change.

Step 1 — List the available upgrade options

Endpoint: GET /v1/tickets/:id/upgrade-options · Scope: tickets:manage

This returns the higher tiers the ticket can move into — those that are priced above the current tier, have upgrades enabled, and still have supply — each with its price, the fiat price difference (delta), remaining supply, and perks.

curl https://api.ticketconnect.example/v1/tickets/tkt_4f8a9c0d1e2f/upgrade-options \
  -H "Authorization: Bearer sk_test_..."

{
  "current_tier": "General Admission",
  "options": [
    {
      "name": "VIP",
      "price": 149.00,
      "delta": 100.00,
      "available": 42,
      "perks": { "lounge": true }
    }
  ]
}

Step 2 — Pay the difference

If the upgrade has a positive price difference (the option's delta), take a payment for that amount first (see Take a payment), and keep the resulting payment_intent_id. The upgrade reserves its exact native-unit difference against the same original payment budget used for issuance. Allocations cannot exceed the verified collection, and an already consumed allocation cannot be claimed twice.

Step 3 — Upgrade

Endpoint: POST /v1/tickets/:id/upgrade · Scope: tickets:manage

Pass the target_tier and the payment that covers the difference.

curl https://api.ticketconnect.example/v1/tickets/tkt_4f8a9c0d1e2f/upgrade \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: upgrade_88231" \
  -d '{
    "target_tier": "VIP",
    "payment_intent_id": "pi_9QabcDEF"
  }'

{
  "id": "tkt_4f8a9c0d1e2f",
  "event_name": "Summer Fest 2026",
  "status": "valid",
  "tier": "VIP",
  "price": 149.00,
  "currency": "USD",
  "perks": { "lounge": true },
  "qr": { "data": "8f2c1a...e7", "format": "QR" },
  "created_at": "2026-06-05T14:22:00.000Z"
}

The ticket is now on the higher tier, with the new perks and price, and the same QR code the customer already has.

Upgrades can work even after check-in. As long as the target tier allows upgrades, a ticket can be moved up even if it's already been used — handy for on-site "upgrade to VIP at the door" flows. The price difference is computed server-side from the tiers, never trusted from the request.

Common upgrade errors

See also

• Issue a ticket — create the ticket you're managing.
• Take a payment — fund the difference on an upgrade.
• Deliver tickets — delivering the (freshly rotated) QR after a transfer.
• API reference: ticket lifecycle

Scanning & Check-in

When the doors open you need a fast, reliable way to decide one thing for every person walking up: let them in, or not? The scanning endpoints answer exactly that. You send the QR string read off a ticket and get back a clear verdict — valid, already used, refunded, or not found — plus the ticket's tier so your staff know which section it's for.

Every ticket is tamper-proof, so you can trust the verdict without any extra checks of your own. That covers both shapes of code a holder can present: the opaque QR string you deliver yourself, and the live, refreshing code shown for tickets held in a holder's ticket wallet — the platform verifies the latter cryptographically on your behalf. None of that machinery is visible to you: you send the scanned string, you get a verdict.

Scopes

All three endpoints on this page require the scanning:write scope.

Validate vs. mark attendance

There are two ways to check someone in, and they map to two different endpoints:

• Validate (online): POST /v1/scan/validate (and its batch sibling) looks a ticket up by its QR string and returns a verdict. It is the right call when your scanner has a live connection. It does not mark the ticket as used — it only reports whether the ticket is currently valid.
• Mark attendance: POST /v1/tickets/{id}/attendance is what actually records the check-in and flips the ticket to used. This is the state-changing step.

For a venue with a steady connection, the simplest flow is: read the QR, call attendance by ticket id, and admit on a used result.

If your scanners have spotty connectivity (patchy Wi-Fi at the gate, a remote field), don't queue codes for later validation. POST /v1/scan/batch judges codes by their current validity, so it can't tell you whether a queued live code was valid at the moment it was scanned. Use the offline door protocol instead: a scanner device armed through /v1/scanner decides at the gate with no network, verifying signed wallet codes cryptographically and matching your opaque qr.data against its armed ticket list. It uploads device-signed scans when it reconnects. The @ticketconnect/offline-scanner SDK implements the device side, and Gettix's staff mode (Gettix is our flagship licensee) runs on the same protocol. See Offline scanning.

Validate a single ticket at the door

Send the QR string exactly as your scanner read it. Don't parse, trim, or re-encode it — a live wallet code is longer and looks like a JSON blob; it must arrive verbatim.

curl https://api.ticketconnect.example/v1/scan/validate \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "qr": "QR_STRING_FROM_THE_TICKET"
  }'

A valid ticket returns:

{
  "valid": true,
  "status": "valid",
  "tier": "General Admission",
  "ticket_id": "tkt_8f2c..."
}

A ticket that has already been scanned in returns a verdict you can show your staff directly:

{
  "valid": false,
  "reason": "already_used",
  "tier": "General Admission",
  "ticket_id": "tkt_8f2c..."
}

The possible reason values for an invalid result are not_found, refunded, revoked, already_used, and — for live wallet codes — code_expired, live_code_required, and invalid_qr (see below). A not_found result carries no ticket_id.

Note: POST /v1/scan/validate is read-only — it never changes the ticket. Use it to preview a verdict, then call the attendance endpoint to actually check the person in.

Live codes from wallet-held tickets

Some holders keep their ticket in a ticket wallet — any holder experience built on the TicketConnect rails, Gettix, our flagship licensee, being the reference one — instead of (or besides) whatever you delivered. The wallet shows a live code that refreshes every few seconds — an anti-screenshot measure — and your scanning endpoints validate it exactly like any other code: send the scanned string verbatim, get a verdict. The platform checks the code's authenticity and freshness cryptographically before the usual lifecycle verdict.

Three extra reason values exist only for these codes, and each maps to a clear instruction for door staff:

Freshness comes before lifecycle: a stale code on an already-used ticket reads code_expired, not already_used. Have the holder refresh, re-scan, and trust the second verdict.

The static QR string you deliver (qr.data) is unaffected by any of this — it keeps validating by itself, side by side with the wallet's live code.

Live codes are on by default for every event you create and togglable per event: set live_codes: false at creation or flip it later with PATCH /v1/events/{id} (see the events API reference). With live codes off, wallet-held tickets show a static code and none of the extra reason values above can occur.

Batch validation

To check many codes at once while online, send them in one call. Pass an array of QR strings in qrs (up to 200 per request). Each code is judged on its current validity, so live codes must still be fresh when the request arrives. Batch validation is not an offline mode. To scan without a connection, use the offline door protocol, where devices push up to 1000 signed scans per request when they reconnect.

curl https://api.ticketconnect.example/v1/scan/batch \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "qrs": [
      "QR_STRING_1",
      "QR_STRING_2",
      "QR_STRING_3"
    ]
  }'

You get one verdict per QR, in a results array:

{
  "results": [
    { "qr": "QR_STRING_1", "valid": true,  "status": "valid", "tier": "VIP", "ticket_id": "tkt_a1..." },
    { "qr": "QR_STRING_2", "valid": false, "reason": "already_used", "tier": "VIP", "ticket_id": "tkt_b2..." },
    { "qr": "QR_STRING_3", "valid": false, "reason": "not_found" }
  ]
}

Warning: A single batch may contain at most 200 entries. Larger backlogs should be split into multiple requests. Like validate, batch is a read-only check: it reports verdicts but does not mark tickets used.

Mark attendance by ticket id

This is the call that records the check-in. Use the ticket's id (not the QR string), which you have from issuance, from a list, or from a validate response.

curl https://api.ticketconnect.example/v1/tickets/tkt_8f2c.../attendance \
  -X POST \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json"

A first successful check-in returns:

{ "id": "tkt_8f2c...", "status": "used" }

Idempotent re-scans

Door scanning is messy — the same person gets scanned twice, a request times out and the device retries, two lanes scan the same group. The attendance endpoint is built for this:

• Calling it again on a ticket that is already checked in is a safe no-op. Instead of an error, you get a 200 with status: "already_used":

  JSONCopy

  { "id": "tkt_8f2c...", "status": "already_used" }
  

• For exactly-once semantics on a flaky connection, send an Idempotency-Key header. A replay with the same key returns the original response rather than processing the check-in twice.

  TerminalCopy

  curl https://api.ticketconnect.example/v1/tickets/tkt_8f2c.../attendance \
    -X POST \
    -H "Authorization: Bearer sk_test_..." \
    -H "Idempotency-Key: door-lane-2-scan-90183" \
    -H "Content-Type: application/json"
  

A successful check-in also triggers an attendance.verified webhook, so any back-office dashboards stay in sync automatically.

Note: A ticket that doesn't exist (or isn't yours) returns 404 with a resource_missing error. A refunded ticket is reported as invalid by validate; don't mark it attended.

Multi-day events

By default a ticket admits once: after it is marked attended, every later scan is already_used. For a festival or any event that runs over several days, give the event admission days — the instants at which each day starts — and a ticket admits once per day:

curl https://api.ticketconnect.example/v1/events \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Three Days",
    "date": "2026-11-13T17:00:00Z",
    "end_date": "2026-11-15T22:00:00Z",
    "admission_days": ["2026-11-13T05:00:00Z", "2026-11-14T05:00:00Z", "2026-11-15T05:00:00Z"]
  }'

• The day of a scan is decided by its time alone: it belongs to the last admission day that has started. A scan before the first one counts as the first day.
• Put the boundaries where your event is quiet. 05:00Z above is 06:00 in Warsaw, so a night that runs past midnight stays one day.
• A tier is a pass valid every day unless you give it valid_days when you add it — [0] makes a first-day ticket.
• validate answers already_used only for a ticket admitted today, and wrong_day for a tier that is not valid today. Attendance records one check-in per day; the attendance.verified webhook carries admission_day.
• Transfers, resale and refunds follow the first check-in, as for any ticket: a pass that has been used on day one can no longer be passed on.

Without admission_days nothing changes, even when the event has an end_date: the end date only keeps scanning open for the whole run.

See also

• Offline scanning: scan with no network, using the /v1/scanner protocol and SDK.
• Webhooks — receive attendance.verified in real time.
• Marketplace & resale — secondary listings.
• API reference — full endpoint details.

Offline scanning

Venue Wi-Fi fails at the worst moment: thousands of phones in one room, a basement club, a field with one bar of signal. An online gate (Scanning & Check-in) stops when the network does. TicketConnect's door protocol keeps it running: a scanner device downloads what it needs before doors open, decides at the gate with no network at all, and uploads a signed log of every admission when it reconnects.

The protocol is public on /v1 under /v1/scanner/*, and the @ticketconnect/offline-scanner SDK implements the device side for you. Gettix's staff mode (Gettix is our flagship licensee, built on TicketConnect) runs on this same protocol. Every endpoint is documented in the Scanner protocol reference.

Which codes can be scanned offline

The offline gate accepts both shapes of code a holder can present:

• TicketConnect-signed wallet codes. This is the signed code shown by a holder's ticket wallet on the TicketConnect rails (Gettix is the reference wallet), including its live, refreshing variant. The device verifies it cryptographically with the event key, and checks live codes for freshness.
• Your opaque qr.data. This is the code you deliver through /v1. It carries no signature. Instead, the ticket feed includes a barcode_sha256 for each ticket: the SHA-256 of the barcode, never the barcode itself. Any scanned string that doesn't start with { is treated as an opaque code: the device hashes it exactly as read and looks the hash up in its armed ticket list. An unknown hash is ticket_not_found. Opaque codes skip the live-code check, just as they do on the online gate.

Caveat: an opaque code is only as fresh as the last ticket sync. While online, the device refreshes its ticket list every 60 seconds. If a transfer rotates a ticket's barcode after the device's last refresh, the new code is unknown to that gate, and the old one still matches, until the next refresh. A signed wallet code doesn't have this gap because it is verified on its own merits. That makes wallet codes the stronger option at an offline door.

Trust model in plain language

No single piece of the gate relies on the network or on trusting the phone:

• Session tokens, minted server-side. Your backend calls POST /v1/scanner/sessions with its secret sk_ key and passes the resulting scanner session token to the device. Never ship an sk_ key to a device. This is the same pattern as Stripe Terminal connection tokens. A session covers one staff member and one event, and the event comes from the token itself, so no device route takes an event id. A session for event A cannot read or write event B. The token lasts at most 12 hours and never outlives the event's grace cutoff. The SDK keeps it in your secure key-value store, never in the scan database.
• Sessions carry only door capabilities. A scanner session can scan tickets and redeem perks, nothing else. Selling, staff management and stats are always off in it, and it is refused (401) everywhere except the /v1/scanner device endpoints.
• Live permissions. On every request, a session's effective permissions are what the token grants and what the staff member currently has. Turning off can_scan_tickets or can_redeem_perks, deactivating or suspending the staff member, unassigning them from the event, suspending your account, or revoking the API key that minted the session takes effect within about 60 seconds. The device then gets 401, or its pushed rows come back rejected with reason staff_lacks_permission.
• Per-event signing keys. Every event has its own Ed25519 key pair. Ticket codes are signed with the private key, which never leaves the server. Devices verify them with the event's public key from the manifest.
• Device keys and device certificates. The device generates an Ed25519 key for each staff member who signs in on it and registers the public half. Arming fails until registration succeeds. The platform returns a platform-signed device certificate scoped to that event, listing the device's capabilities (scan, perk or both, following the staff member's permissions). It expires at the event's grace cutoff or after 7 days, whichever comes first. Nearby scanners check each other's certificates against the platform key (which the SDK pins on first sight and never lets change) and drop packet types the certificate doesn't grant, so a phone can't pose as a gate and a perk-only phone can't mark tickets used. A staff member can hold at most 10 active devices per event.
• A local used-set that only moves forward. Admitting a ticket marks it used and appends the device-signed scan record in one transaction, so a crash can't admit someone without leaving the signed record that reconciles it. A server refresh can mark a ticket used but never makes it unused again, because the server may not have heard about a local or gossiped admission yet.
• Signed reconciliation, earliest wins. When a device syncs, the server checks that each row belongs to the session's staff member and one of their own devices, then verifies its Ed25519 signature against that device's registered key. Each row is stored as pending, its effect is applied, and only then is it final. Resending an identical row returns its stored outcome (or finishes it, if an earlier attempt was cut off) and changes nothing else, so retries are safe. If two gates admitted the same ticket within the 10-second gossip window, the earlier scan wins and the later one is superseded. Scans of the same ticket more than 10 seconds apart are both flagged suspect_duplicate for your review.
• Revocation of tickets and devices. Revoke a ticket (POST /v1/tickets/{id}/revoke) and it leaves the valid-ticket feed and appears in the revoked-ticket feed. Revoke a lost phone (POST /v1/staff/{id}/devices/{device_id}/revoke) and its signed scans are rejected at reconciliation, while armed peers drop its gossip. Deactivating, suspending or deleting a staff member, or removing their can_scan_tickets or can_redeem_perks, revokes all of their devices. Unassigning them from an event revokes their devices for that event only; the devices keep working at their other events. Revocation is permanent but not retroactive: rows the device signed up to 60 seconds after the revocation are still processed (and flagged for your review), and only later rows are rejected as device_revoked. The same applies to scans and redemptions made before a permission was removed. On device_revoked or device_conflict during registration, the SDK generates a new device identity and registers again.
• A grace cutoff. The scanning window closes at event end + 24 hours. After that, new sessions return 410 event_ended, the server rejects late scans with event_ended, and the SDK refuses to scan.
• Live rotating codes. On events with live codes, a holder's code refreshes every 30 seconds and is signed with a key only that ticket has. The device verifies it with the per-ticket public key delivered in the ticket feed (rot_pub_key). The rotation master key never leaves the server, so an armed phone can't forge a live code.

Arming sequence

Arm each device while it is still online, before doors open. arm() in the SDK does all of this; a custom client must follow the same order:

1. Session: get a token from your backend (which called POST /v1/scanner/sessions).
2. Manifest: GET /v1/scanner/manifest returns the event id (check that it matches), the event public key, the platform certificate key, the event end and grace cutoff, the live-code settings, the session's permissions and — on a multi-day event with daily admission — an admission object: day_starts (when each admission day starts) and tiers (lowercased tier name → the day indexes it is valid on).
3. Device: load the device key for this staff member (or generate one), then POST /v1/scanner/devices to register it and receive a device certificate. Pin the platform certificate key once. Registration is required: if it fails, arm() rejects and the gate stays not_armed. On 409 device_conflict or 403 device_revoked the SDK creates a new identity and retries once.
4. Revoked devices: read the full list for this event from GET /v1/scanner/devices/revoked.
5. Valid tickets: page through all of GET /v1/scanner/tickets.
6. Revoked tickets: page through the full list from GET /v1/scanner/tickets/revoked.
7. Perk grants: page through GET /v1/scanner/perk-grants.
8. Used-set: pull what other gates already admitted, using GET /v1/scanner/scans and GET /v1/scanner/perk-redemptions.

Scan decision order

scanTicket(qr) runs these checks in order and stops at the first failure. Everything here runs on the device.

An opaque code (anything that doesn't start with {) replaces checks 4 to 7 with the barcode_sha256 lookup: an unknown hash is ticket_not_found, and a known one continues at check 8.

On an event with daily admission, "used" means used today. When a new admission day starts the device re-opens the tickets admitted on earlier days (once, and durably), and from then on ignores earlier days' entries from the ticket feed, the scan pull and gossip. The server reconciles the same way: two scans of one ticket collide only when they fall on the same admission day.

Success returns { ok: true, ticketId, seatNumber, … } (qr is null for an opaque code). After an admission the device broadcasts a gossip packet and starts a best-effort sync. redeemPerk(qr) follows the same pattern, with permission_denied when the session lacks redeem_perks.

Sync order

startSync() runs a sync immediately and then every 15 seconds. Each run goes in this order, so local admissions reach the server before any server state is applied:

1. Push pending scans: POST /v1/scanner/scans.
2. Push pending perk redemptions: POST /v1/scanner/perk-redemptions.
3. Refresh valid tickets (at most once every 60 seconds).
4. Pull the revoked-ticket delta (every run).
5. Pull the revoked-device delta (every run).
6. Refresh perk grants (at most once every 60 seconds).
7. Pull other gates' scans, then their perk redemptions.

If either push fails with a network error, 408, 429 or a 5xx, the rows stay pending and that run skips both refreshes (steps 3 and 6), because the server's view would lag the unpushed rows. The revocation pulls still run. Any other whole-batch 4xx (for example 400) is final: the batch's rows are marked rejected with the error code, local used state is kept, and a push_rejected alert with final: true is raised through onAlert. Per-row outcomes are final too, except staff_mismatch, which should never happen: that row stays pending and raises a push_rejected alert with final: false. A row rejected with staff_lacks_permission also makes the SDK re-read the manifest, so the gate starts answering permission_denied. Refreshes can only add "used" state, never remove it. While a perk grant has unconfirmed local or gossiped redemptions, the device keeps the lower of the server's and its own remaining uses.

When the token has 5 minutes or less left, or a request returns 401, the SDK asks your SessionProvider for a new session. The gate disarms until the next arm if the manifest names a different staff member, or the device shows up as revoked.

Shared phones. Each row belongs to the staff member who signed it, and a sync pushes only the current staff member's rows. If someone else signs in on the same phone, the previous staff member's unsynced scans and redemptions stay queued on the device until that person signs in on it again while online (countPendingOfOtherStaff() reports how many; Gettix shows a notice on its scanner screens). If a staff member loses every scanner permission, no session can be minted for them, so their queued rows wait until a permission is restored.

Peer gossip (optional)

Gates that can reach each other can share admissions within seconds, with no server involved. After an admission, a device sends a small signed packet that carries the scan, its signature and the sender's device certificate. A receiver accepts it only after these checks, in order:

1. The packet's size and event are right, and it is a v: 2 packet with a certificate. Anything else is dropped.
2. The sender is not on the event's revoked-device list.
3. Flood control, keyed on the sender's network source when the transport reports one (else on the claimed device id). Senders without a verified certificate get 20 packets/s per key before any cryptography, within a 200/s total. Senders with a verified certificate get 20 packets/s per (device id, source), within a 200 verifications/s CPU guard. One spoofed key can use at most 20 of those 200, so junk traffic can't crowd out real gates.
4. The certificate matches the sender, is for this event, is unexpired, grants the packet type (scan or perk), and is signed by the pinned platform key.
5. The row signature verifies. Only then does the packet count against the sender's 20/s budget and mark itself as seen, so a forged copy can't block the genuine one.

The receiver then records the scan in its own used-set, atomically. Nothing about peers is persisted: each gossip session verifies a peer's certificate on its first packet. A device without a certificate doesn't broadcast.

Gossip is transport-agnostic. You supply one or more PeerTransports: UDP on the venue LAN, an iOS/Android phone-to-phone mesh, BLE, or anything else that moves strings. Pass the packet's source (for example the UDP sender address or the mesh peer name) so flood budgets can't be exhausted by someone spoofing a gate's id. The packet format (gossip v2 packets, v3 certificates) and the canonical signed strings are specified in the SDK README (sections Gossip protocol and Canonical strings). The canonical strings are also listed in the Scanner protocol reference.

Limits

SDK quick start

1. Install

The SDK is the package @ticketconnect/offline-scanner (v0.2.0). It is distributed as the tarball ticketconnect-offline-scanner-0.2.0.tgz:

npm install ./ticketconnect-offline-scanner-0.2.0.tgz

v0.2.0 adds daily admission for multi-day events. A gate on v0.1.0 keeps working at such an event but treats a ticket as used for good, so it refuses re-entry on later days.

It ships ESM, CommonJS and TypeScript declarations. Its runtime dependencies are @noble/curves and @noble/hashes, and it doesn't use React, React Native, Expo or Node-only APIs, so it runs in React Native, the browser or Node.

2. Mint sessions on your server

Add an endpoint to your backend that your staff app calls after the staff member signs in. It is the only place your sk_ key is used. The key needs the scanning:write scope.

// Your backend (Node / Express). The sk_ key never leaves this server.
app.post("/scanner-session", requireStaffLogin, async (req, res) => {
  const r = await fetch("https://api.ticketconnect.example/v1/scanner/sessions", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.TICKETCONNECT_SECRET_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      staff_id: req.user.ticketconnectStaffId, // from POST /v1/staff
      event_id: req.body.event_id,
    }),
  });
  const body = await r.json();
  if (!r.ok) return res.status(r.status).json(body); // 404 / 403 / 409 / 410
  // body: { object: "scanner_session", token, expires_at, event_id, staff_id }
  res.json({ token: body.token, expires_at: body.expires_at });
});

The staff member must be active, assigned to the event (POST /v1/staff/{id}/assignments), and have can_scan_tickets or can_redeem_perks.

3. Implement the ports

The engine does not do its own I/O. The host app supplies:

MemoryScannerStore and MemoryKeyValueStore are included for tests and prototypes. Replace them with durable, secure implementations in production.

4. Arm, scan, sync, gossip

import {
  createOfflineScanner,
  MemoryScannerStore,
  MemoryKeyValueStore,
  type SessionProvider,
} from "@ticketconnect/offline-scanner";

const session: SessionProvider = {
  async mint() {
    const res = await fetch("https://your-backend.example/scanner-session", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ event_id: "evt_42" }),
    });
    if (!res.ok) throw new Error(`session mint failed: ${res.status}`);
    const body = await res.json(); // { token, expires_at }
    return { token: body.token, expiresAt: body.expires_at };
  },
};

// One engine per event, shared by your ticket and perk screens.
const scanner = createOfflineScanner({
  eventId: "evt_42",
  baseUrl: "https://api.ticketconnect.example", // paths are appended as /v1/scanner/...
  session,
  store: new MemoryScannerStore(),      // production: durable, transactional store
  keyValue: new MemoryKeyValueStore(),  // production: Keychain / Keystore
  random: { bytes: (n) => crypto.getRandomValues(new Uint8Array(n)) },
  transports: [],                       // add your PeerTransport(s) for gossip
  device: { platform: "ios", appVersion: "1.0.0" },
});

// Arm while online. ensureArmed() reuses a stored session when it is still fresh.
await scanner.arm();

// Keep reconciling in the background: runs now, then every 15 s.
scanner.startSync();
const offAlerts = scanner.onAlert((alert) => {
  if (alert.outcome === "push_rejected") {
    console.error("server refused rows", alert.code, alert.final ? "rejected for good" : "kept queued");
    return;
  }
  console.warn("possible duplicate entry", alert.ticketId);
});

// Optional phone-to-phone gossip. Returns false if the device isn't armed.
await scanner.startGossip();

// At the gate. Works with no network.
const result = await scanner.scanTicket(qrText);
if (result.ok) {
  admit(result.ticketId, result.seatNumber);
} else {
  refuse(result.reason); // "already_used" | "revoked" | "permission_denied" | "rot_stale" | …
}

// Perks use the same engine.
const perk = await scanner.redeemPerk(perkQrText);

// Teardown.
await scanner.stopGossip();
scanner.stopSync();
offAlerts();

Debouncing belongs in your camera handler, not the engine. The Gettix reference ignores the same payload for 10 seconds and any read within 200 ms of the previous one.

What the SDK does not include

• Camera and scanning UI. You decode the QR and pass the string to scanTicket, then design your own result screens.
• A native mesh transport. The SDK handles packet format, flood control and all cryptography, while the host supplies the transports. Gettix's staff mode is the reference implementation of the ports: an SQLite store, secure storage, UDP on the LAN, and a phone-to-phone mesh over MultipeerConnectivity on iOS and Nearby Connections on Android. That code is part of the Gettix app and is not included in the SDK.
• Durable storage. The in-memory stores are for tests and prototypes.
• Session minting and staff sign-in. These live in your backend and app (step 2).
• Gate sales and wristbands. There are no /v1 POS endpoints.

See also

• Scanner protocol reference: every /v1/scanner endpoint with requests, responses and errors.
• Scanning & Check-in: the online gate.
• Staff reference: create staff, assign events, and manage their devices.

Marketplace & Resale

TicketConnect runs a built-in secondary market so your customers can resell tickets they can no longer use — safely, at a fair price, and with you earning a royalty on every resale. This guide covers how to read that market from the API: list the active resale listings for an event and fetch a single listing.

You don't operate the resale checkout. Listing a ticket for resale, taking the buyer's payment, transferring the ticket, and splitting the proceeds are all handled by the platform. From the API you read the live listings; the purchase and settlement happen on the platform side.

Scopes

The read endpoints on this page require the marketplace:read scope.

How resale works (at a glance)

• Fiat pricing. Every listing is priced in your settlement currency. You see one number — the resale price — just like any other amount in the API.
• Verified royalty settlement. The configured royalty is part of the frozen resale split. Each required leg must have original payment proof and a confirmed settlement on its rail; unknown legs remain pending. A resale royalty does not automatically become platform-held Stripe funds in your v1 payout balance.
• Anti-scalping, on by default. Every event ships with anti-scalping enforced and a resale ceiling of 150% of face value. Both the bounds (floor/ceiling), the resale-open window, and whether resale or anti-scalping is on at all are per-event settings you control when you create or update the event (marketplace_settings on Events) — the same controls organizers get in the panel. Enforcement itself is automatic and can't be bypassed by a reseller; you tune the policy, the platform applies it.

Because of all this, the listing objects you read are intentionally lean: a listing id, the ticket it belongs to, and the fiat price. No internal seller or settlement details are ever exposed.

List listings

Returns your resale listings, newest first, cursor-paginated via limit and starting_after. Each listing carries its status, so you can pick out the active ones.

curl "https://api.ticketconnect.example/v1/marketplace/listings?limit=20" \
  -H "Authorization: Bearer sk_test_..."

{
  "object": "list",
  "data": [
    {
      "id": "list_9a3f1c2e4b6d8f0a1b2c3d4e5f60718",
      "ticket_id": "tkt_8f2c...",
      "price": 75.00,
      "currency": "USD",
      "status": "active",
      "created_at": "2026-06-05T12:00:00.000Z"
    }
  ],
  "has_more": false
}

To page through more results, use starting_after on the next request:

curl "https://api.ticketconnect.example/v1/marketplace/listings?limit=20&starting_after=list_9a3f1c2e4b6d8f0a1b2c3d4e5f60718" \
  -H "Authorization: Bearer sk_test_..."

Note: A listing's status tells you where it is in its life. Once a listing sells, it stops being active and you'll receive a marketplace.sale.completed webhook — see Webhooks. Use ticket_id to tie a listing back to the ticket (GET /v1/tickets/:id) and, through it, the event.

Retrieve a single listing

curl https://api.ticketconnect.example/v1/marketplace/listings/list_9a3f1c2e4b6d8f0a1b2c3d4e5f60718 \
  -H "Authorization: Bearer sk_test_..."

{
  "id": "list_9a3f1c2e4b6d8f0a1b2c3d4e5f60718",
  "ticket_id": "tkt_8f2c...",
  "price": 75.00,
  "currency": "USD",
  "status": "active",
  "created_at": "2026-06-05T12:00:00.000Z"
}

A listing id that doesn't exist (or isn't yours) returns 404 with a resource_missing error.

See also

• Webhooks — listen for marketplace.sale.completed and ticket.transferred.
• Payouts — which proven funds are available for Stripe transfers.
• API reference — full endpoint details.

Discounts

Discount codes let you run promotions: a flat amount off, or a percentage off, redeemable at checkout. This guide covers the full lifecycle — create, list, retrieve, update, and delete — and how a code is applied when a customer buys a ticket.

Scopes

Every discount endpoint requires the events:write scope.

The discount object

{
  "id": "64fa1b2c9e7d654321fedcba",
  "code": "SUMMER10",
  "type": "percentage",
  "value": 10,
  "max_uses": 500,
  "used_count": 0,
  "expires_at": "2026-09-01T00:00:00.000Z",
  "active": true,
  "created_at": "2026-06-05T12:00:00.000Z"
}

Create a percentage discount

value is a percentage between 0 and 100. The example below is 10% off, capped at 500 redemptions, expiring on a fixed date.

curl https://api.ticketconnect.example/v1/discounts \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "code": "SUMMER10",
    "type": "percentage",
    "value": 10,
    "max_uses": 500,
    "expires_at": "2026-09-01T00:00:00.000Z"
  }'

{
  "id": "64fa1b2c9e7d654321fedcba",
  "code": "SUMMER10",
  "type": "percentage",
  "value": 10,
  "max_uses": 500,
  "used_count": 0,
  "expires_at": "2026-09-01T00:00:00.000Z",
  "active": true,
  "created_at": "2026-06-05T12:00:00.000Z"
}

Create a fixed-amount discount

For a fixed discount, value is an amount in your settlement currency. This is $15 off:

curl https://api.ticketconnect.example/v1/discounts \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "code": "WELCOME15",
    "type": "fixed",
    "value": 15
  }'

{
  "id": "64fa77c1e9b7d654321fedcb",
  "code": "WELCOME15",
  "type": "fixed",
  "value": 15,
  "max_uses": null,
  "used_count": 0,
  "expires_at": null,
  "active": true,
  "created_at": "2026-06-05T12:05:00.000Z"
}

Note: You can scope a code to a single event by passing its id in the event_ids array on create (only the first entry is used — one code, one event). Omit it for an account-wide code. If you don't pass a code, the API generates a unique one (e.g. DISC-A1B2C3D4E5F6) and returns it. Codes are matched uppercase at redemption, so create codes in uppercase.

How discounts apply at checkout

A discount changes the amount your customer pays — nothing more:

• The customer enters the code at checkout.
• The platform validates it — active, not expired, under max_uses, not already redeemed by that customer (each customer can use a given code once), and applicable to the event — and applies it to the order.
• A percentage code subtracts that percentage from the order total. fixed codes can be created and managed through the API, but checkout currently applies percentage codes only.
• The amount is always recomputed server-side from the event/tier price — a client can never dictate the final price — and used_count is incremented on redemption.

Warning: Amounts are server-authoritative. The discount only adjusts the order total the platform calculates; you never send a final price from the client.

List discounts

Cursor-paginated via limit (and starting_after).

curl "https://api.ticketconnect.example/v1/discounts?limit=20" \
  -H "Authorization: Bearer sk_test_..."

Retrieve a discount

curl https://api.ticketconnect.example/v1/discounts/64fa1b2c9e7d654321fedcba \
  -H "Authorization: Bearer sk_test_..."

Update a discount

PATCH accepts value, max_uses, expires_at, and active. (To deactivate a code without deleting it, set active: false.) The value is validated against the discount's existing type — a percentage still must be 0–100.

curl https://api.ticketconnect.example/v1/discounts/64fa1b2c9e7d654321fedcba \
  -X PATCH \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "max_uses": 1000,
    "active": false
  }'

The full updated discount object is returned.

Delete a discount

curl https://api.ticketconnect.example/v1/discounts/64fa1b2c9e7d654321fedcba \
  -X DELETE \
  -H "Authorization: Bearer sk_test_..."

{ "id": "64fa1b2c9e7d654321fedcba", "deleted": true }

A missing or non-owned id returns 404 with a resource_missing error on any of the retrieve/update/delete operations.

See also

• Webhooks — payment.succeeded fires on a completed checkout.
• API reference — full endpoint details.

Webhooks

Webhooks push real-time notifications to your server whenever something happens in your account — a ticket is issued, a payment succeeds, a resale completes, a payout is sent. Instead of polling the API, you register a URL once and we POST a signed JSON event to it every time.

If you've used Stripe webhooks, this will feel identical: signed payloads you can verify with an HMAC, automatic retries with backoff, and a delivery log you can inspect and replay.

The payout route emits payout.transferred after a confirmed Stripe transfer to the connected account. The legacy payout.paid subscription remains accepted for compatibility; it is not bank-paid confirmation emitted by this route. Pending or review-held transfers do not emit completion.

Scopes

All webhook-management endpoints require the webhooks:manage scope.

1. Register an endpoint

Register the HTTPS URL on your server that should receive events. You may optionally subscribe to a subset of event types via enabled_events; omit it (or pass ["*"]) to receive all events.

curl https://api.ticketconnect.example/v1/webhook_endpoints \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.yourapp.com/ticketconnect",
    "enabled_events": ["ticket.issued", "payment.succeeded", "payout.transferred"]
  }'

{
  "id": "663b1c9e2a7d654321fedcba",
  "url": "https://hooks.yourapp.com/ticketconnect",
  "enabled_events": ["ticket.issued", "payment.succeeded", "payout.transferred"],
  "status": "active",
  "secret": "whsec_Hk9...redacted..."
}

The signing secret is returned exactly once, here at creation. It is never shown again in list or other responses. Store it securely — you need it to verify every incoming webhook. If you lose it, delete the endpoint and create a new one.

Your URL is validated at registration. It must be http(s) — and https in production — and it must resolve to a publicly routable address. URLs that point at private, link-local, or otherwise internal address space are rejected with a 400 invalid_webhook_url error. The same check re-runs on every delivery, so a URL that later starts resolving to an internal address has its deliveries marked failed rather than retried.

List endpoints

curl https://api.ticketconnect.example/v1/webhook_endpoints \
  -H "Authorization: Bearer sk_test_..."

The secret is not included in list responses.

Delete an endpoint

curl https://api.ticketconnect.example/v1/webhook_endpoints/663b1c9e2a7d654321fedcba \
  -X DELETE \
  -H "Authorization: Bearer sk_test_..."

{ "id": "663b1c9e2a7d654321fedcba", "deleted": true }

Ping your endpoint

Before wiring real traffic, send yourself a test ping. The ping travels through the exact same delivery machinery as production events — same Webhook-Signature and Webhook-Id headers, same 10-second timeout — so it is an end-to-end check of your signature verification. The response is synchronous:

curl https://api.ticketconnect.example/v1/webhook_endpoints/663b1c9e2a7d654321fedcba/ping \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "message": "hello from staging" }'

{
  "id": "evt_8c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f",
  "endpoint_id": "663b1c9e2a7d654321fedcba",
  "type": "ping",
  "delivered": true,
  "response_code": 200,
  "error": null
}

Your endpoint receives a normal envelope with type: "ping" and data: { message } (message is optional, up to 256 characters; a default is supplied when omitted). Pings are never retried — a failed attempt is reported immediately in the response (delivered: false, plus error or a non-2xx response_code). Like any real delivery, a failed ping counts toward the endpoint's auto-disable failure streak, and every ping shows up in the deliveries log.

2. Event types

These are the event types the platform emits. Subscribe to the ones you care about via enabled_events, or omit it to receive them all.

Note: Every issuance produces ticket.issued immediately, followed shortly by exactly one of ticket.confirmed or ticket.confirmation_failed. On ticket.confirmation_failed the ticket itself keeps working (only refunded or used tickets fail a scan) — no customer action is needed, but if you see these recur, contact support. All event payloads are plain business data (ids, amounts, currency) — no settlement or platform internals ever appear.

3. The event payload

Every delivery is a POST with a JSON body in this envelope:

{
  "id": "evt_4f8a2c1e9b7d6543210fedcba9876543",
  "type": "payout.transferred",
  "created": 1749124800,
  "data": {
    "amount": 250.00,
    "currency": "USD",
    "reference": "tr_1Q9..."
  }
}

• id — unique event id (prefixed evt_). Use it for idempotent handling.
• type — one of the event types above.
• created — Unix timestamp (seconds) when the event was generated.
• data — the event-specific payload.

Each request also carries these headers:

4. Verify the signature

The Webhook-Signature header is Stripe-compatible. Its value looks like:

Webhook-Signature: t=1749124800,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

To verify, recompute the HMAC and compare:

1. Parse t (timestamp) and v1 (signature hex) from the header.
2. Build the signed payload string: `${t}.${rawBody}` — the timestamp, a literal ., then the raw, unparsed request body.
3. Compute HMAC-SHA256(secret, signedPayload) and hex-encode it.
4. Compare it to v1 using a constant-time comparison.
5. Optionally, reject the request if t is too far from the current time (a tolerance window) to guard against replay.

Verify against the raw request body, exactly as received — before any JSON parsing or re-serialization. If your framework reparses and re-stringifies the body, the bytes change and the signature will not match.

Verification snippet (Node.js)

const crypto = require('crypto');

/**
 * Verify a TicketConnect webhook signature.
 * @param {string} secret    - your endpoint's whsec_... signing secret
 * @param {string} header    - the Webhook-Signature header value
 * @param {string} rawBody   - the raw request body (string/Buffer, unparsed)
 * @param {number} [toleranceSec] - optional max age, in seconds
 */
function verifyWebhook(secret, header, rawBody, toleranceSec) {
  if (!header) return false;

  let timestamp = null;
  let signature = null;
  for (const part of header.split(',')) {
    const idx = part.indexOf('=');
    if (idx === -1) continue;
    const key = part.slice(0, idx).trim();
    const value = part.slice(idx + 1).trim();
    if (key === 't') timestamp = Number(value);
    else if (key === 'v1') signature = value;
  }
  if (timestamp === null || Number.isNaN(timestamp) || !signature) return false;

  if (toleranceSec !== undefined) {
    const now = Math.floor(Date.now() / 1000);
    if (Math.abs(now - timestamp) > toleranceSec) return false;
  }

  const expectedHex = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');

  const expectedBuf = Buffer.from(expectedHex, 'hex');
  let providedBuf;
  try {
    providedBuf = Buffer.from(signature, 'hex');
  } catch {
    return false;
  }
  if (expectedBuf.length !== providedBuf.length) return false;
  return crypto.timingSafeEqual(expectedBuf, providedBuf);
}

Wire it up in an Express handler. Note the use of the raw body parser:

const express = require('express');
const app = express();

app.post(
  '/ticketconnect',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const rawBody = req.body; // Buffer, untouched
    const sig = req.header('Webhook-Signature');

    if (!verifyWebhook(process.env.TC_WEBHOOK_SECRET, sig, rawBody, 300)) {
      return res.status(400).send('invalid signature');
    }

    const event = JSON.parse(rawBody.toString());
    // ... handle event.type ...

    res.status(200).send('ok'); // ack fast
  }
);

Because the scheme is Stripe-compatible, you can also verify with existing Stripe-style SDK helpers — just point them at the Webhook-Signature header and your whsec_ secret.

5. Responding, retries, and backoff

Your endpoint should return a 2xx status as soon as it has safely received the event. Anything else (a non-2xx, a timeout, or a connection error) is treated as a failed delivery and retried.

• Timeout: each delivery attempt waits up to 10 seconds for your 2xx. Acknowledge first, then do slow work asynchronously.

• Retries: failed deliveries are retried on a fixed backoff schedule, up to 7 total attempts (the initial send plus 6 retries):

  Retry	Delay after previous attempt
  1	1 minute
  2	5 minutes
  3	30 minutes
  4	2 hours
  5	10 hours
  6	24 hours

  After the last attempt, the delivery is marked failed.

• Auto-disable: if an endpoint racks up 20 consecutive failures, it is automatically disabled and stops receiving events until you fix and re-create (or re-enable) it.

Warning: Return your 2xx quickly — within the 10-second window — and offload heavy processing to a background job. A slow handler looks like a failed delivery and gets retried.

6. Idempotent handling on your side

Retries (and manual replays) mean your endpoint can receive the same event more than once. Make your handler idempotent:

• Use the event id (the evt_... value, also in the Webhook-Id header) as a dedupe key.
• On receipt, check whether you've already processed that id; if so, return 200 and do nothing else.
• Only then apply the side effect (update a record, send an email, etc.).

This guarantees that a redelivered payment.succeeded doesn't double-fulfil an order.

7. Inspect deliveries

Every delivery attempt is logged. List recent ones (cursor-paginated via limit) to debug your endpoint:

curl "https://api.ticketconnect.example/v1/events/deliveries?limit=20" \
  -H "Authorization: Bearer sk_test_..."

{
  "object": "list",
  "data": [
    {
      "id": "665c2a1f9e7d654321fedcba",
      "event_id": "evt_4f8a...",
      "type": "payout.transferred",
      "status": "delivered",
      "attempts": 1,
      "last_response_code": 200,
      "created_at": "2026-06-05T12:00:00.000Z"
    }
  ],
  "has_more": false
}

status is one of pending, delivered, or failed. last_response_code is the HTTP status your endpoint returned on the most recent attempt.

8. Replay a delivery

Fixed an outage on your side? Re-send a past delivery to your registered endpoint:

curl https://api.ticketconnect.example/v1/events/deliveries/665c2a1f9e7d654321fedcba/replay \
  -X POST \
  -H "Authorization: Bearer sk_test_..."

{ "id": "665c2a1f9e7d654321fedcba", "status": "pending", "replayed": true }

The delivery is re-queued and dispatched shortly after. (Because a replay can re-deliver an event you already handled, idempotent handling — section 6 — matters here too.)

See also

• Scanning & check-in — emits attendance.verified.
• Payouts — emits payout.transferred.
• Marketplace & resale — emits marketplace.sale.completed.
• API reference — full endpoint details.

Payouts

The payout API transfers available platform-held Stripe funds to your Stripe Connect account. It reports transferred once Stripe confirms that transfer. A deposit in your bank account is a separate Stripe connected-account payout and is not confirmed by this API.

Scopes

Use a read-only key for dashboards and a payouts:claim key for the service that moves funds.

1. Complete Connect onboarding

curl https://api.ticketconnect.example/v1/connect/account \
  -X POST -H "Authorization: Bearer sk_test_..."

{
  "account_id": "acct_1Q...",
  "onboarding_url": "https://connect.stripe.com/setup/e/acct_1Q.../..."
}

Redirect the user to onboarding_url. A later call resumes the same account with a fresh link. Test and live Connect accounts are stored separately; a test account or an unverified legacy account ID cannot receive a live transfer.

Read GET /v1/connect/account to check capabilities:

{
  "connected": true,
  "charges_enabled": true,
  "payouts_enabled": true,
  "details_submitted": true
}

Before onboarding, the response is { "connected": false }. Capability flags describe account readiness, not a completed bank payout.

2. Read the available balance

curl https://api.ticketconnect.example/v1/balance \
  -H "Authorization: Bearer sk_test_..."

{ "object": "balance", "available": 1284.50, "currency": "USD" }

This balance includes only proven platform-held Stripe credits after booked fees, refund debits, and outstanding payout reservations. External, PayPal, crypto, unknown legacy credits, and funds already sent to a destination account do not authorize a transfer from the platform Stripe treasury.

Refunds reverse the original booked net. If refundable funds have already been paid out, the refund may require review and remain held; the API does not guarantee that a debit alone returns money to the buyer. Keep a refund buffer and follow refund completion states.

The ledger balance is not Stripe’s net available-cash report. Processor costs are a platform expense requiring separate liquidity; a provider can refuse a transfer when its actual available balance is insufficient.

3. Request a transfer

A payout requires an Idempotency-Key. Send a positive amount in major units that converts to whole minor units, or omit it to request the full available balance. The currency defaults to the account's settlement currency.

curl https://api.ticketconnect.example/v1/payouts \
  -X POST \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: payout-2026-09-30-001" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 500.00, "currency": "USD" }'

A confirmed transfer returns 201:

{
  "object": "payout",
  "id": "po_opaque_operation_id",
  "amount": 500.00,
  "currency": "USD",
  "status": "transferred",
  "reference": "tr_1Q9...",
  "created_at": "2026-09-30T14:22:00.000Z"
}

The platform reserves the funded balance atomically before calling Stripe. Concurrent requests with different keys cannot spend the same balance. A confirmed operation emits payout.transferred. The legacy payout.paid subscription name remains accepted for compatibility; it is not a bank-paid confirmation emitted by this route.

Pending operations and retries

An ambiguous response returns 202 with pending or review_required status. Funds remain reserved. Retry the same request with the original key; recovery uses the original provider operation and destination. Never request a replacement transfer under a fresh key to resolve an unknown result.

Automatic retries stop after 23 hours from the original attempt when there is no definitive outcome, before Stripe can discard the provider key. The operation then stays held for reconciliation. A definitive provider rejection marks it failed and releases its reservation; the route returns 502.

Invalid or missing keys, non-positive or fractional-minor amounts, insufficient funded balance, and missing Connect accounts are rejected before a transfer.

4. Read transfer history

GET /v1/payouts?limit=20 lists durable operations, newest first. Each row includes the operation ID, amount, currency, state, optional Stripe transfer reference, and creation time. Use starting_after for pagination and inspect the state: a pending row is not a completed transfer.

See API reference: payouts and Webhooks.

Ad tracking & attribution

Configure Ad tracking in the white-label portal. Only the organization owner can change the Meta Pixel ID, GTM container ID or write-only CAPI token. The token is encrypted at rest and is never returned by the API.

Browser and server events

The hosted checkout loads your Meta Pixel and published GTM container only after the buyer accepts optional cookies. Cookie settings lets the buyer withdraw that choice. Consent is stored separately for each pixel/container. Test-mode checkouts load neither tracker and test purchases never dispatch CAPI.

purchase includes an ecommerce object with transaction_id, value, currency and items. Amount and currency come from the completed server purchase, including scheduled tier prices. Free tickets emit no Purchase.

The server sends a consented Meta CAPI Purchase after ticket issuance. Browser and server use the same event ID for deduplication. A CAPI failure never prevents a ticket from being issued.

GTM setup

Saving a GTM ID loads the container; you must publish the container and configure tags for the events above yourself. Tags must honor the buyer's Consent Mode v2 settings. All four storage/advertising settings start denied. If you also send Meta through GTM, preserve event_id as Meta's event ID; otherwise remove that duplicate Meta tag and use the built-in pixel.

Available surfaces

A dedicated Gettix deployment must have TICKETCONNECT_TENANT_SLUG set on its backend. Failed tenant lookup disables tracking instead of falling back to the platform pixel. The standard Gettix deployment uses TicketConnect's platform tracking IDs. Public configuration never contains the CAPI token.

Attribution

UTM fields and referrer accompany the order for the Sales sources report. Advertising click IDs, Meta cookie IDs, browser event ID, source page and user agent require marketingConsent: true. On your own frontend, that flag is your declaration that the buyer consented.

Pass the browser page as sourceUrl and the browser's userAgent in the attribution object. Only HTTP(S) source URLs are accepted; credentials, query parameters and fragments are removed. See ticket attribution.

Verify the integration

First check that neither Meta nor GTM requests occur before consent, then accept and check the network requests and dataLayer. Complete a real, paid live-mode purchase and compare the amount, currency and event ID in the browser Purchase and CAPI payload. Verify reception and deduplication in Meta Events Manager using your own pixel and token. Test-mode ticket purchases deliberately do not reach the production pixel.

META_CAPI_TEST_EVENT_CODE is an optional server setting for a coordinated Meta Test Events check; do not leave it set during normal production tracking.

API reference

This is the complete reference for the TicketConnect White-Label API. Every endpoint lives under the /v1 prefix and is automatically scoped to your account. The API is a plain REST + JSON service modeled closely on Stripe, so if you have integrated Stripe before this will feel familiar.

Base URL

https://api.ticketconnect.example/v1

Replace the host with the environment you were issued. All paths below include the /v1 prefix.

Authentication

Send your secret key as a bearer token on every request except the public meta endpoints (/v1/health, /v1/openapi.json, /v1/docs):

Authorization: Bearer sk_test_your_key_here

The key is also accepted in an x-api-key header as a fallback. Use sk_test_… keys against the sandbox and sk_live_… keys against production; the two are fully isolated. Keys are scoped — each endpoint documents the scope it requires (for example events:read). A wildcard * scope satisfies any check. Calling an endpoint without the required scope returns a 403 with type authorization_error and code forbidden. See Authentication for how to manage keys and scopes. Hosted-checkout endpoints are the one exception to the secret-key rule: they authenticate with browser-safe publishable pk_… keys instead (see Payments).

Response & error envelope

Successful responses return the resource object directly. Most resources carry an object discriminator (for example "object": "payout").

Errors always use one consistent envelope:

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "name is required.",
    "param": "name"
  }
}

See Errors for the full catalog of codes and statuses.

Pagination

List endpoints are cursor-based and return a Stripe-style list envelope:

{
  "object": "list",
  "data": [ { "...": "..." } ],
  "has_more": true
}

To page forward, pass the id of the last item in data as starting_after on the next request. Keep paging while has_more is true.

Idempotency

Mutating POST requests accept an Idempotency-Key header. If you retry a request with the same key, the API returns the original response instead of performing the action twice. Replays are honored for 24 hours. See Idempotency.

Idempotency-Key: a1b2c3d4-...

Money

All amounts are in your account's settlement currency (fiat) and are expressed in major units (for example 49.99, not 4999). Prices are always computed server-side from the event/tier; a client-supplied amount is never trusted. See Money and currencies.

Resource groups

Interactive reference

A live, try-it-out Swagger UI is hosted at /v1/docs, backed by the machine-readable OpenAPI 3.0 document at /v1/openapi.json. Import the OpenAPI document into Postman or use it for client/SDK code generation.

Meta

Public discovery endpoints. Both are unauthenticated — call them before you have an API key for uptime monitoring or code generation.

GET /v1/health

Liveness probe. Returns 200 whenever the API is reachable.

Scope: Public (no auth)

Example request

curl https://api.ticketconnect.example/v1/health

Example response

{
  "status": "ok",
  "version": "v1"
}

GET /v1/openapi.json

Returns the machine-readable OpenAPI 3.0 contract for the entire API. Fetch it for client/SDK generation or to import the API into Postman.

Scope: Public (no auth)

Example request

curl https://api.ticketconnect.example/v1/openapi.json

Example response

{
  "openapi": "3.0.3",
  "info": {
    "title": "TicketConnect White-Label API",
    "version": "1.0.0"
  },
  "paths": { "...": "..." }
}

A live Swagger UI rendering of this document is hosted at /v1/docs.

Account

Your partner account — branding, mode, and settlement currency — plus self-serve API key management: list, mint, and revoke keys without leaving the API.

GET /v1/account

Retrieve the authenticated account. A quick way to confirm an API key is valid and learn which mode (live or test) it operates in.

Scope: Authenticated (any valid key)

Example request

curl https://api.ticketconnect.example/v1/account \
  -H "Authorization: Bearer sk_test_your_key_here"

Example response

{
  "id": "ten_8f2a1c4d5e6f7a8b9c0d1e2f",
  "name": "Acme Live Events",
  "mode": "test",
  "status": "active",
  "branding": {
    "logoUrl": "https://acme.example/logo.png",
    "supportEmail": "support@acme.example",
    "primaryColor": "#e11d48"
  },
  "currency": "USD"
}

GET /v1/account/keys

List your API keys, newest first. Revoked keys stay in the list (with revoked_at set) as an audit trail. The secret itself is never returned — only its prefix.

Scope: keys:manage

Example request

curl https://api.ticketconnect.example/v1/account/keys \
  -H "Authorization: Bearer sk_test_your_key_here"

Example response

{
  "data": [
    {
      "prefix": "sk_test_9f8e7d",
      "label": "Backend (staging)",
      "mode": "test",
      "kind": "secret",
      "scopes": ["events:read", "tickets:issue"],
      "created_at": "2026-07-01T10:00:00.000Z",
      "last_used_at": "2026-07-11T08:59:00.000Z",
      "revoked_at": null
    }
  ]
}

POST /v1/account/keys

Mint a new API key. The plaintext secret is returned exactly once, in this response — copy it straight into your secrets manager.

No privilege escalation is possible: the minted key's scopes must be a subset of the calling key's scopes (a * wildcard key can mint anything, including another * key), and a test-mode key can never mint a live-mode key. Active keys are capped at 25 per account (shared with keys created in the dashboard).

Scope: keys:manage

Request body

Example request

curl https://api.ticketconnect.example/v1/account/keys \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Door scanner",
    "scopes": ["scanning:write"]
  }'

Example response

{
  "prefix": "sk_test_2b4c6d",
  "label": "Door scanner",
  "mode": "test",
  "kind": "secret",
  "scopes": ["scanning:write"],
  "created_at": "2026-07-11T09:00:00.000Z",
  "last_used_at": null,
  "revoked_at": null,
  "secret": "sk_test_2b4c6d...shown_only_once"
}

Errors: 400 parameter_invalid (bad label/scopes/mode/kind), 403 scope_escalation (requested scopes exceed the caller's), 403 mode_escalation (test key minting live), 409 key_limit_reached (25 active keys — revoke unused keys first).

DELETE /v1/account/keys/{prefix}

Revoke a key by its prefix. Revocation is immediate — the next request with the revoked key gets a 401 — and idempotent. The calling key can never revoke itself, so a rotation always overlaps: mint the new key, deploy it, then revoke the old one with the new key (or any other key holding keys:manage).

Scope: keys:manage

Path params

Example request

curl https://api.ticketconnect.example/v1/account/keys/sk_test_9f8e7d \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -X DELETE

Example response

{ "prefix": "sk_test_9f8e7d", "revoked": true, "revoked_at": "2026-07-11T09:05:00.000Z" }

Errors: 400 cannot_revoke_self (a key cannot revoke itself), 404 resource_missing (no key with that prefix on your account).

Events

Events are the things you sell tickets to. Each event holds one or more ticket tiers (name, price, supply, perks). Organizations are read-only sub-accounts you can list and retrieve alongside your events.

A serialized event object looks like this:

{
  "id": "evt_a1b2c3d4e5f6a7b8c9d0e1f2",
  "name": "Summer Festival 2026",
  "status": "draft",
  "date": "2026-08-15T18:00:00.000Z",
  "venue": "Riverside Park",
  "city": "Austin",
  "country": "US",
  "category": "music",
  "description": "Two stages, twenty acts.",
  "currency": "USD",
  "imageUrl": "https://acme.example/img/summerfest-card.jpg",
  "bannerUrl": "https://acme.example/img/summerfest-hero.jpg",
  "ticketPools": [
    {
      "name": "General Admission",
      "price": 49.99,
      "totalSupply": 5000,
      "issued": 0,
      "upgradesEnabled": false,
      "perks": null,
      "release": { "released": true }
    }
  ],
  "queue": null,
  "live_codes": true,
  "created_at": "2026-06-05T12:00:00.000Z"
}

The issued field on a tier is the number of tickets already issued from that tier; totalSupply - issued is what remains.

Tier price is always the schedule-effective price — what checkout charges right now. A tier that runs a published price schedule additionally carries:

Every tier carries a release object describing its auto-release state: { "released": true } for tiers on sale, or { "released": false } plus release_at (unlock time) and/or awaiting_sold_out_of (the sibling tier that must sell out first). Locked tiers are visible but cannot be issued from.

queue is non-null only when the event uses an on-sale waiting room (see Waiting room (queue)): { "enabled": true, "sales_start_at": "2026-08-01T10:00:00.000Z" }.

live_codes says whether tickets held in a holder's ticket wallet (any holder experience built on the TicketConnect rails — Gettix, our flagship licensee, is the reference one) show a live, refreshing entry code for this event (an anti-screenshot measure — see Scanning & check-in). It is true by default, settable at creation and togglable with PATCH /v1/events/{id}. It never affects the static qr.data you deliver yourself. It also gates phone passes: a wallet-held ticket can be saved to Apple/Google Wallet only when live codes are off (a phone pass is a static barcode, so the platform refuses one where a live code is enforced).

imageUrl (card/list image) and bannerUrl (wide hero) are the event's two media slots — set them at creation via images or later with PATCH /v1/events/{id}. Events with a published seat map sell seated tiers by the seat (see Reserved seating), and every event can list its closest catalog neighbours via GET /v1/events/{id}/similar.

GET /v1/events

List your events, newest first.

Scope: events:read

Query params

Example request

curl "https://api.ticketconnect.example/v1/events?limit=2" \
  -H "Authorization: Bearer sk_test_your_key_here"

Example response

{
  "object": "list",
  "has_more": false,
  "data": [
    { "id": "evt_a1b2c3d4e5f6a7b8c9d0e1f2", "name": "Summer Festival 2026", "status": "draft", "ticketPools": [] }
  ]
}

POST /v1/events

Create an event under your account. Returns 201 with the new event. New events start in draft status with no tiers — add tiers with POST /v1/events/{id}/tiers.

Scope: events:write

Request body

Accepts an Idempotency-Key header.

The marketplace_settings object (all fields optional; supplied keys override the platform defaults):

royalty_rate is platform-set per organization and is not accepted here — sending it returns 400 parameter_unknown. It appears read-only on the event object so you can see your effective rate.

Example request

curl https://api.ticketconnect.example/v1/events \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: evt-create-001" \
  -d '{
    "name": "Summer Festival 2026",
    "date": "2026-08-15T18:00:00Z",
    "venue": "Riverside Park",
    "city": "Austin",
    "country": "US",
    "currency": "USD"
  }'

Example response

{
  "id": "evt_a1b2c3d4e5f6a7b8c9d0e1f2",
  "name": "Summer Festival 2026",
  "status": "draft",
  "date": "2026-08-15T18:00:00.000Z",
  "currency": "USD",
  "ticketPools": [],
  "queue": null,
  "live_codes": true,
  "created_at": "2026-06-05T12:00:00.000Z"
}

GET /v1/events/{id}

Retrieve a single event by id.

Scope: events:read

Path params

Example request

curl https://api.ticketconnect.example/v1/events/evt_a1b2c3d4e5f6a7b8c9d0e1f2 \
  -H "Authorization: Bearer sk_test_your_key_here"

Example response

{
  "id": "evt_a1b2c3d4e5f6a7b8c9d0e1f2",
  "name": "Summer Festival 2026",
  "status": "draft",
  "date": "2026-08-15T18:00:00.000Z",
  "ticketPools": [
    { "name": "General Admission", "price": 49.99, "totalSupply": 5000, "issued": 12 }
  ],
  "created_at": "2026-06-05T12:00:00.000Z"
}

PATCH /v1/events/{id}

Update an event's media, resale policy, live-code setting and/or ticket extras, end date and/or admission days. Accepts images, marketplace_settings, live_codes, ticket_extras, end_date and/or admission_days — at least one is required. Partial: only the keys you send change. Pass null to unset a media slot; omitted keys are untouched. Naturally idempotent (no Idempotency-Key needed). Emits an event.updated webhook.

Scope: events:write

Path params

Request body

Example request

curl https://api.ticketconnect.example/v1/events/evt_a1b2c3d4e5f6a7b8c9d0e1f2 \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -X PATCH \
  -d '{
    "images": {
      "image_url": "https://acme.example/img/summerfest-card.jpg",
      "banner_url": null
    }
  }'

Example response

{
  "id": "evt_a1b2c3d4e5f6a7b8c9d0e1f2",
  "name": "Summer Festival 2026",
  "status": "draft",
  "imageUrl": "https://acme.example/img/summerfest-card.jpg",
  "created_at": "2026-06-05T12:00:00.000Z"
}

Errors: 400 parameter_missing (none of images, marketplace_settings, live_codes, ticket_extras), 400 parameter_invalid (bad media URL, out-of-range resale bound, non-boolean live_codes, or an invalid ticket_extras field), 400 parameter_unknown (images.gallery_urls or marketplace_settings.royalty_rate), 404 resource_missing (not your event).

POST /v1/events/{id}/tiers

Add a ticket tier to an event. Returns the full updated event with the new tier appended to ticketPools. The tier's issued count always starts at 0.

Scope: events:write

Path params

Request body

Accepts an Idempotency-Key header.

Errors: 404 resource_missing if the event does not exist or is not yours; 400 parameter_invalid if the schedule or release configuration is invalid (e.g. a release_after_sold_out cycle or an unknown sibling tier).

Example request

curl https://api.ticketconnect.example/v1/events/evt_a1b2c3d4e5f6a7b8c9d0e1f2/tiers \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "VIP",
    "price": 149.00,
    "totalSupply": 200,
    "perks": { "lounge": true },
    "upgradesEnabled": true
  }'

Example response

{
  "id": "evt_a1b2c3d4e5f6a7b8c9d0e1f2",
  "name": "Summer Festival 2026",
  "status": "draft",
  "ticketPools": [
    { "name": "General Admission", "price": 49.99, "totalSupply": 5000, "issued": 0, "upgradesEnabled": false },
    { "name": "VIP", "price": 149.00, "totalSupply": 200, "issued": 0, "upgradesEnabled": true, "perks": { "lounge": true } }
  ],
  "created_at": "2026-06-05T12:00:00.000Z"
}

GET /v1/organizations

List your organizations — read-only sub-accounts grouped with your events.

Scope: events:read

Query params

Example request

curl https://api.ticketconnect.example/v1/organizations \
  -H "Authorization: Bearer sk_test_your_key_here"

Example response

{
  "object": "list",
  "has_more": false,
  "data": [
    { "id": "665f1e2d3c4b5a6d7e8f9a0b", "name": "Acme Live", "status": "active", "created_at": "2026-01-10T09:00:00.000Z" }
  ]
}

GET /v1/organizations/{id}

Retrieve one of your organizations by id.

Scope: events:read

Path params

Example request

curl https://api.ticketconnect.example/v1/organizations/665f1e2d3c4b5a6d7e8f9a0b \
  -H "Authorization: Bearer sk_test_your_key_here"

Example response

{
  "id": "665f1e2d3c4b5a6d7e8f9a0b",
  "name": "Acme Live",
  "status": "active",
  "created_at": "2026-01-10T09:00:00.000Z"
}

Waiting room (queue)

High-demand events can run an on-sale waiting room. When an event has one, its serialized queue field is non-null and ticket issuance is gated: a customer must hold a live admission window before POST /v1/events/{id}/tickets will succeed (otherwise it returns 403 with code not_admitted).

The waiting room is a server-side concept — call these endpoints from your backend and proxy queue state to your own buyer-facing UI. Identity is your customer's externalId, passed as customer_id.

The room moves through three phases:

A customer's queue status is waiting, admitted, or completed (bought at least once), or null when they are not in the queue.

Polling is the contract. Poll GET /v1/events/{id}/queue?customer_id=… every few seconds during the pre_sale and queue_active phases. A status of admitted with a non-null, future access_expires_at is the signal to open checkout. No webhook is emitted for admission today.

GET /v1/events/{id}/queue

Return the room phase and aggregate waiting_count, plus — when customer_id is supplied — that customer's position, people_ahead, admission status, and access window. Also includes queue-time price transparency: the purchasable price range and per-tier prices, locked tiers with their unlock conditions, and the next published price change.

Scope: tickets:issue

Path params

Query params