Skip to content

Sell event tickets with QR code check-in

An event payment link sells ticket tiers that share a capacity. Each admission the buyer pays for becomes a numbered ticket with its own QR code. At the door, staff scan the code from a phone and Flint admits each ticket once, even when two scanners read it at the same moment. The scanner in the Flint Dashboard uses the same public API calls you can use to build your own.

StepWhat happensSection
SellCreate an event link with tiers, capacity, and a sales window1. Sell ticket tiers
DeliverFlint issues ticket numbers and sends each buyer their QR codes2. Ticket numbers and QR codes
Staff the doorGive door staff a check-in-only role and the event's scanner link3. Run the door
Check inLook up a scanned code, check the ticket in, or undo it4. Check guests in
Fix mistakesVoid a ticket, replace a leaked code, or correct a name5. Void, replace, or rename a ticket
Give money backRefunds void tickets and put their seats back on sale6. Refunds and seats
Build your ownScan codes in your app with a key that can't refund7. Build your own door scanner
Stay in syncFollow ticket events8. Webhooks

Before you start#

You need a sandbox API key with the scopes for the steps you use:

  • checkouts.payment_links.write to create and change the event link.
  • commerce.tickets.read to read and look up tickets, and commerce.tickets.write to check them in, undo check-ins, void them, and replace codes. The write scope includes the read scope. Neither scope reaches orders or refunds.
  • commerce.refunds.write to refund ticket orders.
  • accounts.api_keys.write to create the door scanner key in step 7. The credential that creates the key must also hold every scope the new key gets.

Amounts are in cents. Replace the example IDs with your own.

1. Sell ticket tiers#

Create a payment link with payment_link_type: "event". Each line item is a tier, priced per admission: one unit is one ticket and takes one place. This link sells General Admission and VIP for a 500-person gala, with no more than 20 VIP places:

cURL
curl -X POST https://api.withflintpay.com/v1/payment-links \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: payment-link-spring-gala-001" \
  -d '{
    "name": "Spring Gala",
    "payment_link_type": "event",
    "event_config": {
      "event_at": "2027-05-12T23:00:00Z",
      "timezone": "America/New_York",
      "venue": "Pier 57, New York",
      "max_total_quantity": 500,
      "ticket_prefix": "GAL",
      "send_ticket_emails": true,
      "collect_attendee_names": true
    },
    "line_items": [
      {
        "type": "custom_fixed",
        "key": "general",
        "name": "General Admission",
        "unit_price_money": {"amount": 7500, "currency": "USD"}
      },
      {
        "type": "custom_fixed",
        "key": "vip",
        "name": "VIP",
        "unit_price_money": {"amount": 20000, "currency": "USD"},
        "max_quantity": 4,
        "max_total_quantity": 20
      }
    ]
  }'

Share the link's url. Its page shows the event's date and venue in the event's time zone and a count for each tier. What each setting does:

  • Date and time zone. event_at and timezone are required. Checkout and ticket emails show the event in that IANA time zone, such as "Wed, May 12, 2027, 7:00 PM EDT (New York time)".
  • Capacity. event_config.max_total_quantity caps tickets across all tiers, and a tier's max_total_quantity caps that tier. max_quantity limits one order and defaults to 10. Tickets in a payment that has started count against both caps until it succeeds or fails, so two buyers can't pay for the last seat.
  • Availability. The public link reports remaining_quantity and is_sold_out on each tier. When 20 or fewer tickets remain, the page shows how many are left. A payment that can't fit returns 409 INVENTORY_INSUFFICIENT and charges nothing.
  • Sales window. Sales close at event_at unless you set sales_end_at, for example an hour before doors open. sales_start_at schedules an on-sale.
  • Attendee names. With collect_attendee_names, hosted checkout asks for a name for every ticket and copies each one to its ticket.
  • Ticket numbers. ticket_prefix, up to five characters, starts every number: GAL001, GAL002. It can't change after the first ticket is issued.

To move the event, PATCH its event_config.event_at, timezone, or venue. Existing tickets stay valid, and Flint emails ticket holders the new details unless you send "notify_ticket_holders": false. Sell event tickets covers every event setting, changing tier caps, rescheduling, and selling from your own page.

2. Ticket numbers and QR codes#

When the payment succeeds, Flint issues one ticket for each admission. The order's ticketed_event.ticket_numbers lists the numbers, and ticketed_event.ticket_status is pending until they exist. Each ticket is also its own record with a tkt_ ID:

cURL
curl "https://api.withflintpay.com/v1/tickets?order_id=ord_01K4GALA2" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "data": [
    {
      "ticket_id": "tkt_01K4GALA",
      "version": 1,
      "order_id": "ord_01K4GALA2",
      "payment_link_id": "pl_01K4GALA",
      "order_line_item_id": "li_01K4GALA",
      "payment_link_line_item_key": "vip",
      "tier_name": "VIP",
      "ticket_number": "GAL014",
      "status": "issued",
      "supported_actions": ["check_in", "void"],
      "attendee_name": "Priya Shah",
      "checked_in_at": null,
      "check_in_method": null,
      "voided_at": null,
      "admission_code_last4": "4HTV",
      "created_at": "2027-04-02T16:20:00Z",
      "updated_at": "2027-04-02T16:20:00Z"
    }
  ],
  "next_page_token": null,
  "request_id": "req_..."
}

A ticket has two identifiers, and only one of them gets someone in:

  • The ticket number, such as GAL014, is printed for people to read. Numbers are never reused, and a number alone doesn't admit anyone.
  • The admission code is a secret: 16 characters printed as XXXX-XXXX-XXXX-XXXX, such as 8F3K-2M9Q-7XRD-4HTV. The ticket's QR code holds the same 16 characters without hyphens, so a scan and a typed code send the same value.

Merchant reads, lists, and webhooks never include the admission code; admission_code_last4 shows its last four characters. Flint delivers codes only to the buyer:

  • The confirmation page. After paying, the buyer sees each ticket with its QR code. Your redirects.success_url, if set, becomes its Continue button.
  • Ticket emails. With send_ticket_emails on, Flint emails the tickets with their QR codes to the order's buyer_email. Receipts sent to that address with no one copied show the codes too. A receipt you send to another address lists the ticket numbers without codes.
  • The buyer account. A buyer whose email Flint verified reads their tickets, with codes, in Flint's hosted account or through GET /v1/me/tickets.

To send tickets from your own system instead, turn off send_ticket_emails, then call POST /v1/tickets/{ticket_id}/rotate-code for each ticket. It returns a fresh code once, in admission_code. Encode it in your QR code without hyphens. Admission codes has the full delivery rules.

3. Run the door#

The Flint Dashboard has a scanner for each event. Open the event link in Payment links and choose Check in guests in its Tickets panel. Staff check guests in three ways:

  • Scan the QR code with the phone or laptop camera.
  • Enter code to type the printed code when a camera can't read it.
  • Find guest to search by attendee name or ticket number and check in by hand.

The panel's Export attendance button downloads every ticket and its check-in status as a CSV, and the link's sales summary counts checked-in tickets in checked_in_ticket_count.

Give door staff check-in access only#

Volunteers and venue staff don't need to see your orders, customers, or payouts. Invite them in Settings > Team with the Check-in role. Owners and admins can grant it. A check-in teammate can look up tickets and check guests in, and nothing else: they can't open the rest of the Dashboard, read orders or buyer emails, void tickets, or issue refunds.

In the event's Tickets panel, choose Copy staff link and send it to your door staff. It opens a scanner page outside the Dashboard, where a check-in teammate signs in and starts scanning. Their guest search matches attendee names and ticket numbers, not buyer emails. They can undo a check-in made by mistake; voiding stays with operators and above.

4. Check guests in#

A scanner makes two calls. First it looks up the scanned code to find the ticket. Lookup changes nothing and returns the ticket whatever its status, so the screen can say "already checked in at 7:42 PM" or "voided" before anyone is admitted:

cURL
curl -X POST https://api.withflintpay.com/v1/tickets/lookup \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"admission_code": "8F3K2M9Q7XRD4HTV"}'

Lookup and check-in accept the code in lowercase, with spaces or hyphens, and read O as 0 and I or L as 1. Send the code in the request body: Flint keeps codes out of URLs and logs.

Then it checks the ticket in 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": "8F3K2M9Q7XRD4HTV"}'

The response is the ticket with status: "checked_in", checked_in_at, and check_in_method: "admission_code". Leave out the code to admit a guest by hand, such as one who lost their phone and showed ID; Flint records check_in_method: "manual". Check-in has no time window, so you can admit early arrivals or check in after the event.

What the door sees when a check-in can't go through:

  • HTTP 409
    With details[0].reason already_applied and current_status checked_in, the ticket is already in. This is also what the second of two simultaneous scans gets: Flint admits each ticket once. Show when it was checked in from a fresh read. With reason unsupported_state and current_status voided, the ticket was voided or refunded. Turn the guest away or send them to the box office.
  • HTTP 400
    With detail code INVALID_VALUE and param admission_code, the code isn't 16 valid characters, or isn't this ticket's current code, for example after a code was replaced. The ticket doesn't change.
  • HTTP 404
    From lookup, with param admission_code: the code matches no ticket for your account in this environment. A sandbox key never finds live tickets, and another merchant's code is never found.
  • HTTP 409
    VERSION_CONFLICTRefresh, then retry
    You sent an expected_version and the ticket changed since you read it. Door scanners usually leave expected_version out, so a stale read doesn't hide whether the guest is already in.

To reverse a mistaken check-in, call POST /v1/tickets/{ticket_id}/undo-check-in. The ticket returns to issued, and checked_in_at and check_in_method are cleared. Undoing on an issued ticket returns already_applied.

A ticket's supported_actions lists what it accepts now:

statussupported_actions
issuedcheck_in, void
checked_inundo_check_in, void
voidednone. voided is final.

5. Void, replace, or rename a ticket#

These changes need commerce.tickets.write. In the Dashboard they need the operator role or above, not the Check-in role.

  • Void. POST /v1/tickets/{ticket_id}/void permanently invalidates an issued or checked_in ticket and puts its seat back on sale: the link's total_quantity_sold drops by one. Voiding refunds nothing, so refund the order yourself if the buyer should get money back.
  • Replace a code. If a buyer posted their QR code online, POST /v1/tickets/{ticket_id}/rotate-code issues a new code and the old one stops working at once. The response carries the new code in admission_code, the only merchant response that ever does, so deliver it to the buyer. Send an Idempotency-Key: a retry with the same key returns the code again while the ticket hasn't changed since.
  • Rename. PATCH /v1/tickets/{ticket_id} with attendee_name puts a new guest's name on a transferred ticket. Send null to clear it.

A voided ticket refuses every other change with reason unsupported_state. Tickets covers versions and retries for each call.

6. Refunds and seats#

Refunds and tickets stay in step, so a refunded ticket can't get anyone in:

  • A full refund of the order voids every ticket on it that is still valid and puts those seats back on sale.
  • A refund of specific ticket lines with refund_type: "targets" voids that many tickets on the line once the refund succeeds, lowest ticket number first among those still valid, and frees their seats. For a buyer who bought four General Admission tickets and can now bring only three, refund one unit of that line:
cURL
curl -X POST https://api.withflintpay.com/v1/refunds \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: refund-gala-ord-01k4gala2-one-ticket" \
  -d '{
    "refund_type": "targets",
    "order_id": "ord_01K4GALA2",
    "reason": "requested_by_customer",
    "line_items": [
      {"order_line_item_id": "li_01K4GALB", "quantity": 1}
    ]
  }'
  • A partial amount refund, such as a goodwill credit, leaves every ticket valid and its seat sold.

A freed seat is available to the next buyer straight away: the tier's remaining_quantity rises on the public link. Voiding a ticket by hand frees its seat the same way.

To cancel a show, deactivate the link to stop new sales, then refund each order in full. The refund email names the event and its date. Deactivating the link alone refunds nothing and tells no one. Refunds covers line refunds, reasons, and what the buyer sees.

7. Build your own door scanner#

Your own app, a turnstile, or a kiosk can do everything the Dashboard scanner does. Give it its own restricted key with only the ticket scopes, so a lost tablet can't refund an order or read your customers:

cURL
curl -X POST https://api.withflintpay.com/v1/api-keys \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pier 57 door scanner",
    "access": "restricted",
    "scopes": ["commerce.tickets.write"]
  }'

Keep the key on your server and have the scanning device call your backend, or keep it on a managed device you can revoke the key for. Then build the door loop:

  1. Read the QR code#

    Decode the QR code to text. It holds exactly the 16-character code. Anything else, such as the link's own sharing QR code, isn't a ticket. Let staff type the printed code as a fallback.

  2. Look the code up#

    POST /v1/tickets/lookup with admission_code in the body. Check that payment_link_id is tonight's event, then show ticket_number, tier_name, attendee_name, and status. Your rules can use payment_link_line_item_key, such as letting vip through a separate entrance. The key stays the same if you rename the tier.

  3. Check the ticket in#

    POST /v1/tickets/{ticket_id}/check-in with the same code. Treat 200 as admitted, already_applied as already in, and unsupported_state as voided. Don't retry a refused check-in; read the ticket and show why.

  4. Keep the guest list current#

    For a searchable list at the door, page GET /v1/tickets?payment_link_id=pl_01K4GALA with sort_by=attendee_name&sort_direction=asc. query matches part of a ticket number, attendee name, buyer name, or buyer email. Filter status=checked_in with checked_in_after to count arrivals.

Admission codes are bearer secrets. Don't log scanned codes, put them in URLs, or store them after the request. Flint keeps codes out of every merchant read, so your scanner never needs to store a list of them.

8. Webhooks#

Subscribe to ticket events to update a guest list, a CRM, or a badge printer as tickets change. Every event carries the ticket as GET /v1/tickets/{ticket_id} returns it, without the admission code:

  • ticket.created
    Flint issued a ticket after the buyer paid. An order of three tickets sends three events.
  • ticket.checked_in
    A ticket was checked in, by your scanner, the Dashboard, or a check-in teammate.
  • ticket.voided
    A ticket was voided by hand, or a refund voided it.
  • ticket.updated
    Any other change: an attendee name edit, an undone check-in, or a replaced code.

Order events carry ticketed_event, and a rescheduled event sends order.updated with the former details in data.previous_attributes.ticketed_event. Events can arrive more than once and out of order, so deduplicate by event ID and compare each ticket's version. Ticket events has the payloads.

API calls#

Next steps#

Tickets API referenceAdmission codes, versions, retries, and every field.Event payment linksTier caps, rescheduling, attendee names, and selling tickets on your own page.RefundsLine refunds, reasons, and what the buyer sees.

Was this helpful?