Skip to content

A ticket starts issued. Checking it in makes it checked_in, and undoing the check-in returns it to issued. Voiding it, or a full refund of its order, makes it voided, which is final. supported_actions lists what the ticket accepts now:

statussupported_actions
issuedcheck_in, void
checked_inundo_check_in, void
voidednone

To sell tickets on your own page instead of Flint's hosted checkout, replace the resolved hosted session with a headless one, as Sell event tickets on your own page describes. The buyer's checkout credential then lists the order's tickets with their admission codes.

Reading tickets needs commerce.tickets.read, and changing them needs commerce.tickets.write. Neither scope includes access to orders or refunds, so a key for door staff can't issue a refund. expand=order also requires commerce.orders.read. Partner apps can read tickets but can't change them.

Check in#

POST /v1/tickets/{ticket_id}/check-in admits an issued ticket. Send the scanned admission_code to confirm the code belongs to this ticket, and Flint records check_in_method: admission_code. Send no code to admit the ticket by hand, recorded as manual. Check-in has no time window.

Flint admits each ticket once. When two scanners check in the same ticket at the same time, one succeeds and the other gets 409 ACTION_NOT_ALLOWED with reason already_applied and current_status: checked_in. A voided ticket returns reason unsupported_state with current_status: voided. Scanners usually omit expected_version: a stale one returns 409 VERSION_CONFLICT instead of telling the door the ticket is already in.

A code that isn't 16 valid characters, or isn't this ticket's current code, returns 400 INVALID_REQUEST with detail code INVALID_VALUE and param set to admission_code, and the ticket doesn't change. To check in from a scan without the ticket ID, look the code up first with POST /v1/tickets/lookup, then check in that ticket with the same code.

cURL
curl -X POST https://api.withflintpay.com/v1/tickets/tkt_01K4GALA/check-in \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"admission_code": "8F3K-2M9Q-7XRD-4HTV"}'

POST /v1/tickets/{ticket_id}/undo-check-in returns a checked-in ticket to issued and clears checked_in_at and check_in_method. On an issued ticket it returns already_applied, and on a voided ticket unsupported_state.

Void a ticket#

POST /v1/tickets/{ticket_id}/void permanently voids an issued or checked_in ticket and frees its seat. In the same change, the event link's total_quantity_sold drops by one. As with a refund, the link's version doesn't change. Voiding refunds nothing and doesn't change the order's ticketed_event, so refund the order yourself if the buyer should get money back. A later full refund of the order voids only its remaining valid tickets and frees only their seats. Voiding a voided ticket returns already_applied.

Attendee names#

PATCH /v1/tickets/{ticket_id} sets attendee_name. Flint trims surrounding spaces, and the name must then be 1 to 200 characters. Send null to clear it. Sending the current name changes nothing and keeps the version. A voided ticket returns 409 ACTION_NOT_ALLOWED with reason unsupported_state.

Admission codes#

An admission code is a secret that identifies one ticket. Merchant reads, lists, and webhooks never include it, and admission_code_last4 shows only its last four characters. Only the ticket's buyer gets the full code, and only where they proved themselves. The paid checkout session's own paying credential reads it on its order's tickets; a checkout link you read from the checkout session, or request after payment, doesn't. GET /v1/me/tickets returns it to a buyer whose email Flint verified, by signing in to Flint's hosted account or through the paid checkout, on orders whose buyer_email is that email. Ticket and receipt emails sent to the order's buyer_email, with no one copied, show each valid ticket's code with a QR code that holds it. Access links, customer sessions and checkout links you create never carry codes, and a receipt you send to another address lists the ticket numbers without them. To deliver tickets from your own pages, issue a code with rotate-code. Flint doesn't log the code, and it stays out of URLs and filters, so look a ticket up by sending the code in the body of POST /v1/tickets/lookup.

Lookup and check-in accept the code in lowercase, with spaces or hyphens, and read O as 0 and I or L as 1. Lookup returns the ticket whatever its status. A code that isn't 16 valid characters returns 400 INVALID_REQUEST with detail code INVALID_VALUE, and a code that matches no ticket in the key's environment returns 404 RESOURCE_NOT_FOUND, both with param set to admission_code. Branch on error.code; details[0].code names the cause. A code from another merchant, or from the other environment, is not found.

POST /v1/tickets/{ticket_id}/rotate-code replaces a ticket's code and returns the ticket with the new code in admission_code, formatted XXXX-XXXX-XXXX-XXXX. The old code stops working immediately. This is the only merchant route that returns a code. To deliver tickets yourself, turn off send_ticket_emails on the event link, rotate each ticket's code, and encode the code in your QR code without hyphens.

A retry with the same Idempotency-Key returns the code again under the one-time secret rules, as long as the ticket hasn't changed since the rotation. After any later change to the ticket, including another rotation, the retry returns the ticket without admission_code. A voided ticket returns 409 ACTION_NOT_ALLOWED with reason unsupported_state.

Versions#

Every change accepts an optional expected_version. When it doesn't match the ticket's current version, the request returns 409 VERSION_CONFLICT and changes nothing, even when the ticket's status would also refuse the action. Read the ticket again before you retry.

Events#

Every ticket event carries the ticket as a read returns it, without the code.

  • ticket.created: Flint issued the ticket.
  • ticket.checked_in: the ticket was checked in.
  • ticket.voided: you voided the ticket, or a full refund voided it.
  • ticket.updated: any other change, such as an attendee name edit, an undone check-in, or a replaced code. A replaced code changes admission_code_last4 and version.

See Read individual tickets for the fields and a list example.

The Ticket object#

An individual admission, a top-level child of an order. Merchant reads and webhooks never include the bearer admission code.

Returned by GET /v1/tickets/{ticket_id} and carried by the endpoints below.

Attributes

admission_codestring

The ticket's 16-character Crockford base32 admission code, the value its QR code holds. A bearer secret: only the paid checkout session's own paying credential receives it, on its own order's tickets that aren't voided. A checkout credential from a launch URL a merchant reads or requests after payment never does. Returned only to the checkout credential; never in webhook payloads.

Not returned with a bearer token

admission_code_last4stringRequired

Last four characters of the current admission code.

attendee_namestring or nullRequired

Optional attendee name. Null when not supplied.

check_in_methodenum or nullRequired

How the ticket was admitted. Null when the ticket is not checked in.

  • admission_code
  • manual
checked_in_atstring or nullRequired

When the ticket was admitted. Null when the ticket is not checked in.

created_atstringRequired

When the ticket was issued.

orderobject

Order summary, present only with expand=order. Requires commerce.orders.read.

order_idstringRequired

The order that purchased this ticket.

order_line_item_idstringRequired

The purchased ticket tier.

payment_link_idstringRequired

The event payment link.

statusenumRequired

The admission lifecycle.

  • issued
  • checked_in
  • voided
supported_actionsarray of enumRequired

Actions currently offered for this ticket.

  • check_in
  • undo_check_in
  • void
ticket_idstringRequired

Unique ticket identity with the tkt_ prefix.

ticket_numberstringRequired

The event prefix and sequence, such as GAL001. Numbers are never reused and do not authorize entry.

updated_atstringRequired

When the ticket last changed.

versionintegerRequired

Persisted version of this resource's owned state. Expanded resources and external observations can change independently.

voided_atstring or nullRequired

When the ticket was permanently voided. Null when the ticket has not been voided.

JSON
{
  "admission_code_last4": "1234",
  "attendee_name": null,
  "check_in_method": null,
  "checked_in_at": null,
  "created_at": "2026-07-03T14:30:00Z",
  "order_id": "ord_01KEZF7C00JBKMARG3P06Z224B",
  "order_line_item_id": "li_01KEZF7C004XP0V220YVMGQ354",
  "payment_link_id": "pl_01KEZF7C00FEBVYY6R0DKKQRWX",
  "status": "issued",
  "supported_actions": [],
  "ticket_id": "tkt_01J00000000000000000000000",
  "ticket_number": "GAL001",
  "updated_at": "2026-07-03T14:30:00Z",
  "version": 1,
  "voided_at": null
}

List tickets#

GET/v1/tickets

Requires scope commerce.tickets.read or commerce.tickets.write

Rate limit: read

Lists individual event tickets, newest first by default. Merchant credentials never receive admission codes. The checkout credential of a paid checkout session lists only its own order's tickets: it must send that order_id, may not send other filters, search, sort or expand, and receives admission_code on every ticket that isn't voided, unless the credential came from a launch URL a merchant read or requested after payment. Any other order_id returns 403, as reading another order does. Default order: created_at descending, then ticket_id descending.

Query parameters

page_sizeinteger

Maximum number of results to return, from 1 to 100. Defaults to 20.

page_tokenstring

Opaque, signed next_page_token from the previous response, bound to the list and caller. Omit on the first request. You may change `page_size` between pages. Reuse it with the same endpoint, filters, sort, and request context. Do not parse or construct tokens. An altered, invalid, expired, or mismatched token returns a validation error.

payment_link_idstring

Only tickets for this event payment link.

order_idstring

Only tickets belonging to this order.

statusarray of enum

Filter by ticket status. Values are trimmed and deduplicated in first-seen order; empty or unknown entries are rejected. Values within this filter are ORed; separate filters are ANDed.

  • issued
  • checked_in
  • voided
querystring

Case-insensitive text search across ticket number, attendee name, buyer name and buyer email. For Dashboard check-in staff it matches ticket number and attendee name only.

sort_byenum

Field to sort by. Defaults to created_at; ties are broken by ticket_id.

  • created_at
  • attendee_name
sort_directionenum

Sort direction. Defaults to desc.

  • asc
  • desc
checked_in_afterstring

Inclusive lower bound on checked_in_at.

checked_in_beforestring

Exclusive upper bound on checked_in_at.

expandarray of enum

Include related objects in the response. Supported expansions: order. Include the requested related resources using scoped batch reads for this page. Each relationship requires its existing target read scopes. Expansion changes the representation without changing pagination tokens. Limits: at most 10 unique expand paths per request.

  • order

Response · 200

The ticket or ticket page.

dataarray of objectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

next_page_tokenstring

Opaque token to send as `page_token` to retrieve the next page. Omitted when there is no next page.

request_idstringRequired

Identifier of this API request, used to correlate logs and support requests.

curl https://api.withflintpay.com/v1/tickets \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

The ticket or ticket page.

JSON
{
  "data": [
    {
      "admission_code_last4": "1234",
      "attendee_name": null,
      "check_in_method": null,
      "checked_in_at": null,
      "created_at": "2026-07-03T14:30:00Z",
      "order_id": "ord_01KEZF7C00JBKMARG3P06Z224B",
      "order_line_item_id": "li_01KEZF7C004XP0V220YVMGQ354",
      "payment_link_id": "pl_01KEZF7C00FEBVYY6R0DKKQRWX",
      "status": "issued",
      "supported_actions": [],
      "ticket_id": "tkt_01J00000000000000000000000",
      "ticket_number": "GAL001",
      "updated_at": "2026-07-03T14:30:00Z",
      "version": 1,
      "voided_at": null
    }
  ],
  "meta": {
    "api_version": "2026-09-07"
  },
  "next_page_token": "example",
  "request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}

Get a ticket#

GET/v1/tickets/{ticket_id}

Requires scope commerce.tickets.read or commerce.tickets.write

Rate limit: read

Returns an individual ticket. Merchant credentials never receive its admission code. The checkout credential of a paid checkout session reads only its own order's tickets, without expand, and receives admission_code unless the ticket is voided or the credential came from a launch URL a merchant read or requested after payment; another order's ticket returns 404 RESOURCE_NOT_FOUND.

Path parameters

ticket_idstringRequired

The ticket ID. Must be a valid ID with prefix tkt_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.

Query parameters

expandarray of enum

Include related objects in the response. Supported expansions: order. Include the order summary. Limits: at most 10 unique expand paths per request.

  • order

Response · 200

The ticket or ticket page.

dataobjectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

request_idstringRequired

Identifier of this API request, used to correlate logs and support requests.

curl https://api.withflintpay.com/v1/tickets/tkt_01KEZF7C00AWVKS6GAX8RMEBZ8 \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

The ticket or ticket page.

JSON
{
  "data": {
    "admission_code_last4": "1234",
    "attendee_name": null,
    "check_in_method": null,
    "checked_in_at": null,
    "created_at": "2026-07-03T14:30:00Z",
    "order_id": "ord_01KEZF7C00JBKMARG3P06Z224B",
    "order_line_item_id": "li_01KEZF7C004XP0V220YVMGQ354",
    "payment_link_id": "pl_01KEZF7C00FEBVYY6R0DKKQRWX",
    "status": "issued",
    "supported_actions": [],
    "ticket_id": "tkt_01J00000000000000000000000",
    "ticket_number": "GAL001",
    "updated_at": "2026-07-03T14:30:00Z",
    "version": 1,
    "voided_at": null
  },
  "meta": {
    "api_version": "2026-09-07"
  },
  "request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}

Update a ticket#

PATCH/v1/tickets/{ticket_id}Idempotent

Requires scope commerce.tickets.write

Rate limit: write

Sets the attendee name. Surrounding whitespace is trimmed; send null to clear the name. Sending the current name changes nothing and keeps the version. A voided ticket returns 409 ACTION_NOT_ALLOWED with reason unsupported_state.

Path parameters

ticket_idstringRequired

The ticket ID. Must be a valid ID with prefix tkt_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.

Request body

attendee_namestring or nullRequired

The attendee name, 1 to 200 characters after surrounding whitespace is trimmed. Send null to clear it.

expected_versioninteger

The ticket version last read. The change applies only while the ticket is at this version; a stale value returns 409 VERSION_CONFLICT, even when the ticket's status would also refuse the change. Door scanners usually omit it.

Response · 200

The ticket after the change.

Same response as Get a ticket.

curl -X PATCH https://api.withflintpay.com/v1/tickets/tkt_01KEZF7C00AWVKS6GAX8RMEBZ8 \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "attendee_name": "Alex Rivera"
  }'

Check in a ticket#

POST/v1/tickets/{ticket_id}/check-inIdempotent

Requires scope commerce.tickets.write

Rate limit: write

Admits an issued ticket. Concurrent check-ins of one ticket admit it once: the others return 409 ACTION_NOT_ALLOWED with reason already_applied and current_status checked_in. A stale expected_version returns 409 VERSION_CONFLICT first, so scanners usually omit it. With admission_code the check-in method is admission_code, and the code must be the ticket's current code: a wrong code returns 400 at admission_code and changes nothing. Without a code the method is manual. A voided ticket returns reason unsupported_state. There is no event-time window. The code is never returned or logged.

Path parameters

ticket_idstringRequired

The ticket ID. Must be a valid ID with prefix tkt_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.

Request body

admission_codestring

The 16-character Crockford base32 admission code scanned at the door. Spaces, hyphens and ASCII lowercase are normalized. Omit it to check the ticket in manually.

expected_versioninteger

The ticket version last read. The change applies only while the ticket is at this version; a stale value returns 409 VERSION_CONFLICT, even when the ticket's status would also refuse the change. Door scanners usually omit it.

Response · 200

The ticket after the change.

Same response as Get a ticket.

curl -X POST https://api.withflintpay.com/v1/tickets/tkt_01KEZF7C00AWVKS6GAX8RMEBZ8/check-in \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "admission_code": "0123456789AB1234"
  }'

Replace a ticket admission code#

POST/v1/tickets/{ticket_id}/rotate-codeIdempotent

Requires scope commerce.tickets.write

Rate limit: sensitive_write

Replaces the ticket's admission code and returns the new code once, in admission_code. The old code stops working immediately. Use it to deliver tickets yourself with send_ticket_emails turned off. A retry with the same Idempotency-Key within 24 hours returns the code again while the ticket is unchanged since this rotation; after any later change, including another rotation, it returns the ticket without admission_code. A voided ticket returns 409 ACTION_NOT_ALLOWED with reason unsupported_state.

Path parameters

ticket_idstringRequired

The ticket ID. Must be a valid ID with prefix tkt_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.

Request body

expected_versioninteger

The ticket version last read. The change applies only while the ticket is at this version; a stale value returns 409 VERSION_CONFLICT, even when the ticket's status would also refuse the change. Door scanners usually omit it.

Response · 200

The ticket with its new admission code.

dataobjectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

request_idstringRequired

Identifier of this API request, used to correlate logs and support requests.

curl -X POST https://api.withflintpay.com/v1/tickets/tkt_01KEZF7C00AWVKS6GAX8RMEBZ8/rotate-code \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "expected_version": 2
  }'

Undo a ticket check-in#

POST/v1/tickets/{ticket_id}/undo-check-inIdempotent

Requires scope commerce.tickets.write

Rate limit: write

Returns a checked-in ticket to issued and clears checked_in_at and check_in_method. An issued ticket returns 409 ACTION_NOT_ALLOWED with reason already_applied; a voided ticket returns reason unsupported_state.

Path parameters

ticket_idstringRequired

The ticket ID. Must be a valid ID with prefix tkt_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.

Request body

expected_versioninteger

The ticket version last read. The change applies only while the ticket is at this version; a stale value returns 409 VERSION_CONFLICT, even when the ticket's status would also refuse the change. Door scanners usually omit it.

Response · 200

The ticket after the change.

Same response as Get a ticket.

curl -X POST https://api.withflintpay.com/v1/tickets/tkt_01KEZF7C00AWVKS6GAX8RMEBZ8/undo-check-in \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "expected_version": 2
  }'

Void a ticket#

POST/v1/tickets/{ticket_id}/voidIdempotent

Requires scope commerce.tickets.write

Rate limit: write

Permanently voids an issued or checked-in ticket and releases its seat: the payment link's total_quantity_sold drops by one in the same transaction. Like a refund release, this doesn't change the link's version or send payment_link.updated. Nothing is refunded and the order's ticketed_event doesn't change. A later full refund of the order releases only its remaining valid tickets. A voided ticket returns 409 ACTION_NOT_ALLOWED with reason already_applied.

Path parameters

ticket_idstringRequired

The ticket ID. Must be a valid ID with prefix tkt_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.

Request body

expected_versioninteger

The ticket version last read. The change applies only while the ticket is at this version; a stale value returns 409 VERSION_CONFLICT, even when the ticket's status would also refuse the change. Door scanners usually omit it.

Response · 200

The ticket after the change.

Same response as Get a ticket.

curl -X POST https://api.withflintpay.com/v1/tickets/tkt_01KEZF7C00AWVKS6GAX8RMEBZ8/void \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "expected_version": 2
  }'

Look up a ticket#

POST/v1/tickets/lookup

Requires scope commerce.tickets.read or commerce.tickets.write

Rate limit: read

Looks up an admission code in the authenticated merchant and environment, including voided tickets. ASCII lowercase, spaces and hyphens are accepted; O maps to 0 and I/L to 1. Malformed codes return 400 INVALID_REQUEST with detail INVALID_VALUE; an unknown or foreign code returns 404 RESOURCE_NOT_FOUND at admission_code. The code is never returned.

Request body

admission_codestringRequired

The 16-character Crockford base32 admission code. Spaces, hyphens and ASCII lowercase are normalized.

Response · 200

The ticket or ticket page.

Same response as Get a ticket.

curl -X POST https://api.withflintpay.com/v1/tickets/lookup \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "admission_code": "0123456789AB1234"
  }'

Was this helpful?