acme.orgo.space). The checkout endpoints under /api/v1/public/event/ send permissive CORS headers (Access-Control-Allow-Origin: *), so a browser on your own domain can call them directly.
What’s public, what’s not
Anything visitor-facing is public. Anything that changes the event itself requires authentication.
Prerequisites
The event must be published and public (status: published, isPublic: true). Anonymous reads of a draft, private or members-only event answer 404 or 403: the public surface only exposes what the organizers chose to share. Registration can also be closed by hand (registrationManuallyClosed), in which case holds and checkout are refused.
Step 1: Fetch event details
id, uuid, name, description, location, dateTimeBegin, dateTimeEnd, timezone, logo, type, speakers, maxCapacity, registrationManuallyClosed, requiresRegistrationForm, hasEventTicketing, the ticketing product, and the registration form configuration with its custom fields resolved. Render these as you like.
Ticket types and their live availability come from Step 2, not from this payload.
Step 2: Check live availability
The event payload can be a little stale on a busy event. Availability is always fresh:id is the ticket’s price id, the value every later call calls productPriceId. price is in currency units. To avoid pressure messaging, availability is deliberately coarse: availabilityStatus is null (unlimited, or more than 20 left), limited (11 to 20), low (10 or fewer, with the exact availabilityCount), or sold_out. Seats currently held by other buyers already count as taken. Capacity of a ticketed event is set per ticket type; for a non-ticketed event the response is isFull plus capacity and spotsLeft.
Call this when the page renders and when the tab regains focus. For a sold-out ticket (availabilityStatus: sold_out) or a full event (isFull: true), replace the form with a “sold out” message.
Step 3: Hold tickets while the buyer fills the form
Hold seats the moment the buyer starts the form, so two buyers cannot both reach payment for the last ticket:- Holds last 8 minutes. A second hold for the same ticket and session adds to it and extends the clock.
- Keep the returned
sessionIdand send it back on later holds and releases. It is what proves a hold is yours. One session can hold at most 10 tickets for an event. - Holds are rate limited to 12 per hour per IP address and event (
429). - Members-only tickets and tickets restricted to specific local groups cannot be held anonymously (
400). - A held seat is released when it expires, when you release it, or when payment completes.
POST or DELETE the hold, or release everything for the session:
Step 4: Save the buyer and attendee details
Once the buyer has chosen tickets and filled in the form:tickets is required. Each entry names a ticket and a quantity, and the server re-checks the sales window, capacity and eligibility (members-only tickets need a signed-in member, because identity comes from the session and never from the typed email). Optional fields include voucherCode (a discount or registration-link code, checked by POST .../validate-voucher), addonAttendees, per-ticket add-ons under each ticket entry’s ticketAddons, and wantCompanyInvoice with billing details. Set fillNow to false to let each attendee fill in their details later by email.
totalAmount is in the smallest currency unit (5000 is $50.00), unlike the price values from availability. uniqueId identifies this order in every following call. Nothing is booked yet.
Failures here answer with {"error": "<message>"} and a 400, for example Only 3 tickets available for General Admission or This ticket is not yet available for purchase.
Step 5: Take payment or complete a free registration
Paid events: card payment with Stripe
Orgo uses Stripe Elements on the connected account. The flow has three calls:Stripe(publishableKey, { stripeAccount }) and confirm the payment with the clientSecret. Card details go to Stripe only. Once Stripe reports success, tell Orgo:
amount is refused. Calling complete again for the same order answers Payment already processed with the same ids. Each attendee gets a confirmation email with a QR code.
Free events, or a voucher that covers the total
When the order total is zero, skip Stripe and finish with:success, message, eventAttendIds, and the first attendee’s attendHash). The total is recomputed server-side and any amount above zero is refused.
Step 6: Show “thanks for registering”
Show a confirmation page from thecomplete response, and rely on the email for the ticket: each attendee’s email carries a personal link and the QR code, keyed by a hash that is unique to that attendee. Event agenda items for the page come from GET /api/v1/public/event-agenda/{uuid}.
Showing the time correctly
dateTimeBegin and dateTimeEnd are ISO 8601 timestamps. The event carries a timezone (an IANA name like America/New_York). For an in-person event, render the date in the event’s timezone, not the visitor’s:
Adding to-calendar buttons
There is no hosted.ics link. Build one from the event data in the browser:
Common gotchas
My page caches event data and sold-out tickets show as available
My page caches event data and sold-out tickets show as available
Cache the event details (Step 1) for a few minutes, but never cache
availability (Step 2). Call it fresh on every render. The numbers change second to second.Buyers complete the form but never reach payment
Buyers complete the form but never reach payment
Check the
save-attendees answer. It returns {"error": ...} with a 400 when a ticket is sold out, outside its sales window, or reserved for members. Surface that message to the buyer.Attendees aren't appearing in admin although save-attendees returned 200
Attendees aren't appearing in admin although save-attendees returned 200
save-attendees only records the order. Attendances are created when complete (or complete-free) succeeds. Until then nothing is booked. Wait for the event_attend.created webhook to know a registration is confirmed.Can attendees edit their registration later?
Can attendees edit their registration later?
Yes. When an organizer or buyer chose to fill in details later, each attendee receives a personal details link by email and can update their own record there. Build your own page only if you need a different look; the link works on the stock page.
What to do next
- Create and sell event tickets: the admin-side setup that produced this event
- Process payments: payment reconciliation and refunds after checkout
- Handle webhooks: react to new registrations server-side

