Events
Public events: listings, tickets, registration, payment and self-service.
Quick start
Register for the first free ticket
const events = await window.Portal.events.events();
const detail = await window.Portal.events.event(events[0].reference_num);
const occurrence = (detail.occurrences || [])[0];
const result = await window.Portal.events.register({
occurrence_reference_num: occurrence.reference_num,
ticket_type_reference_num: occurrence.ticket_types[0].reference_num,
attendee_name: 'Ada Lovelace',
attendee_email: 'ada@example.com',
});
if (result.requires_payment && result.payment && result.direct_payment_ref && result.order_reference_num && result.registration_reference_num) {
const pay = await window.Portal.events.beginPayment({
directPaymentRef: result.direct_payment_ref,
itemRef: result.payment.item_ref,
quantity: result.payment.quantity,
orderRef: result.order_reference_num,
registrationRef: result.registration_reference_num,
accessToken: result.access_token,
email: 'ada@example.com',
mountSelector: '#pay',
});
await pay.confirm();
}API reference
payment
The handle beginPayment() returns for an event registration.
confirm()
Call when the attendee presses pay.
await payment.confirm();Returns
Resolves when the call has completed.
window.Portal.events
Portal.events — public events: listing, tickets, registration, payment and self-service.
beginPayment()
Mounts the payment form for a registration that requires payment.
const eventPaymentHandle = await window.Portal.events.beginPayment(opts);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
opts | PortalEventPaymentOptions | Yes | Options of Portal.events.beginPayment(); most come from the payment block of register(). |
Returns
Resolves with a PortalEventPaymentHandle: The handle beginPayment() returns for an event registration.
calendarUrl()
The address of an .ics calendar file for a registration. Synchronous: it only builds the URL.
const value = window.Portal.events.calendarUrl(referenceNum, token);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
referenceNum | string | Yes | The record's reference number. |
token | string | No | A token issued by the server (see the description above). |
Returns
Returns a string.
cancelRegistration()
Cancels a registration.
await window.Portal.events.cancelRegistration(referenceNum, token);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
referenceNum | string | Yes | The record's reference number. |
token | string | No | A token issued by the server (see the description above). |
Returns
Resolves when the call has completed.
confirmPayment()
Tells the server the payment went through so the registration is confirmed.
await window.Portal.events.confirmPayment(registrationRef, token);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
registrationRef | string | Yes | The registration's reference. |
token | string | No | A token issued by the server (see the description above). |
Returns
Resolves when the call has completed.
event()
One event with occurrences and ticket types.
const eventDetail = await window.Portal.events.event(referenceNum, site);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
referenceNum | string | Yes | The record's reference number. |
site | string | No | The website's reference. |
Returns
Resolves with a PortalEventDetail: An event with its occurrences and their ticket types (Portal.events.event()).
events()
Lists published events.
const eventSummarys = await window.Portal.events.events(filter);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
filter | PortalEventsFilter | No | Filter of Portal.events.events(). |
Returns
Resolves with an array of PortalEventSummary.
hold()
Reserves tickets for a few minutes while the attendee fills in the form. Pass the hold_reference_num to register().
const result = await window.Portal.events.hold(payload);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
payload | object | Yes | The data to send. |
payload.occurrence_reference_num | string | Yes | The event date's reference. |
payload.ticket_type_reference_num | string | Yes | The ticket type's reference. |
payload.quantity | number | No | How many. |
payload.tier_reference_num | string | No | — |
Returns
Resolves with an object with these fields:
| Name | Type | Required | Description |
|---|---|---|---|
hold_reference_num | string | Yes | The reference returned by hold(). |
expires_at | string | No | ISO time it expires. |
joinWaitlist()
Puts someone on the waiting list of a sold-out occurrence.
const result = await window.Portal.events.joinWaitlist(payload);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
payload | object | Yes | The data to send. |
payload.occurrence_reference_num | string | Yes | The event date's reference. |
payload.ticket_type_reference_num | string | No | The ticket type's reference. |
payload.attendee_name | string | Yes | — |
payload.attendee_email | string | Yes | — |
payload.quantity | number | No | How many. |
Returns
Resolves with an object with these fields:
| Name | Type | Required | Description |
|---|---|---|---|
waitlist_reference_num | string | Yes | The waiting-list entry's reference. |
position | number | Yes | — |
myRegistrations()
The signed-in attendee's registrations.
const eventRegistrationRecords = await window.Portal.events.myRegistrations();Returns
Resolves with an array of PortalEventRegistrationRecord.
passes()
The multi-event passes (season tickets) of a site.
const result = await window.Portal.events.passes(siteRef);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
siteRef | string | Yes | The website's reference. |
Returns
Resolves with Array<Record<string, unknown>>.
redeemPass()
Uses a pass to register.
const result = await window.Portal.events.redeemPass(passRef, payload);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
passRef | string | Yes | — |
payload | Record<string, unknown> | Yes | The data to send. |
Returns
Resolves with the server's record as a plain object.
register()
Registers an attendee. Check requires_payment in the result.
const eventRegisterResult = await window.Portal.events.register(payload);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
payload | PortalEventRegisterPayload | Yes | What Portal.events.register() sends. |
Returns
Resolves with a PortalEventRegisterResult: The answer to Portal.events.register().
registration()
One registration; a guest passes the access token.
const eventRegistrationRecord = await window.Portal.events.registration(referenceNum, token);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
referenceNum | string | Yes | The record's reference number. |
token | string | No | A token issued by the server (see the description above). |
Returns
Resolves with a PortalEventRegistrationRecord: A registration as the public / the signed-in attendee sees it.
releaseHold()
Gives held tickets back.
await window.Portal.events.releaseHold(holdRef);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
holdRef | string | Yes | The reference returned by hold(). |
Returns
Resolves when the call has completed.
scannerManifestUrl()
The address of the door-scanner app's manifest. Synchronous: it only builds the URL.
const value = window.Portal.events.scannerManifestUrl();Returns
Returns a string.
validatePromo()
Checks a promo code against a subtotal; resolves with the discount in cents.
const result = await window.Portal.events.validatePromo(occurrenceRef, code, subtotalCents);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
occurrenceRef | string | Yes | — |
code | string | Yes | The code to apply. |
subtotalCents | number | Yes | The order subtotal in cents. |
Returns
Resolves with an object with these fields:
| Name | Type | Required | Description |
|---|---|---|---|
discount_cents | number | Yes | — |
Types
PortalEventDetail
An event with its occurrences and their ticket types (Portal.events.event()).
Extends PortalEventSummary.
| Name | Type | Required | Description |
|---|---|---|---|
occurrences | object[] | No | The dates the event runs on. |
occurrences[].reference_num | string | Yes | The occurrence's reference; use it to register. |
occurrences[].starts_at | string | No | — |
occurrences[].ends_at | string | No | — |
occurrences[].timezone | string | No | An IANA timezone, for example Europe/Paris. |
occurrences[].status | string | Yes | Publication / run status. |
occurrences[].availability | string | Yes | — |
occurrences[].ticket_types | PortalTicketTypePublic[] | Yes | The tickets on sale for this date. |
site_users | PortalSiteUsersBlock | No | Absent on an older server bundle; treat as unconnected. |
PortalEventPaymentOptions
Options of Portal.events.beginPayment(); most come from the payment block of register().
| Name | Type | Required | Description |
|---|---|---|---|
directPaymentRef | string | Yes | The Direct Payment to charge on. |
itemRef | string | Yes | The Direct Payments item the ticket type is mapped to (payment.item_ref from register()). |
quantity | number | Yes | Number of tickets. |
discountItemRef | string | null | No | The promo discount line (payment.discount_item_ref / payment.discount_cents), when a code applies. |
discountCents | number | No | The promo discount in cents. |
orderRef | string | Yes | The order being paid. |
registrationRef | string | Yes | The registration being paid. |
accessToken | string | No | The registration's access token from register(); lets a guest attach the invoice. |
email | string | Yes | The payer's e-mail. |
mountSelector | string | No | CSS selector of the element the card form is mounted in. |
onSuccess | () => void | No | Called when payment succeeded. |
onError | (err: Error) => void | No | Called when payment failed. |
PortalEventRegisterPayload
What Portal.events.register() sends.
| Name | Type | Required | Description |
|---|---|---|---|
occurrence_reference_num | string | Yes | The date being registered for. |
ticket_type_reference_num | string | Yes | The ticket type chosen. |
attendee_name | string | Yes | The attendee's name. |
attendee_email | string | Yes | The attendee's e-mail (tickets are sent here). |
attendee_phone | string | No | The attendee's phone. |
quantity | number | No | Number of tickets; default 1. |
idempotency_key | string | No | Any unique string; repeating the call with it will not register twice. |
hold_reference_num | string | No | The hold made with hold(). |
promo_code | string | No | A promo code (check with validatePromo() first). |
form_submission_ref | string | No | A form submission the event asked the attendee to fill. |
tier_reference_num | string | No | The pricing tier chosen, when the ticket type has tiers. |
PortalEventRegisterResult
The answer to Portal.events.register().
| Name | Type | Required | Description |
|---|---|---|---|
success | boolean | Yes | True when the registration was created. |
order_reference_num | string | No | The order created. |
registration_reference_num | string | No | The registration created. |
status | string | No | The registration status. |
access_token | string | No | Lets a guest read, pay for or cancel the registration later. Keep it. |
direct_payment_ref | string | No | The Direct Payment to pay on. |
requires_payment | boolean | No | True when the attendee must pay before the registration is confirmed. |
payment | object | No | What the browser needs to build the invoice; present only when a charge is due. |
payment.item_ref | string | Yes | The Direct Payments item reference. |
payment.quantity | number | Yes | How many. |
payment.ticket_name | string | Yes | — |
payment.discount_item_ref | string | null | No | — |
payment.discount_cents | number | No | — |
error | object | No | Set when success is false. |
error.message | string | Yes | A message to show the visitor. |
error.code | string | Yes | A code. |
PortalEventRegistrationRecord
A registration as the public / the signed-in attendee sees it.
| Name | Type | Required | Description |
|---|---|---|---|
reference_num | string | Yes | The registration's reference. |
event_reference_num | string | No | The event registered for. |
event_name | string | null | No | The Dashboard's events provider. |
venue_name | string | null | No | The event's default venue. |
occurrence_reference_num | string | No | The date registered for. |
starts_at | string | null | No | The occurrence's own starts_at, eager-loaded server-side — splits upcoming/past. |
ticket_type_reference_num | string | No | The ticket type bought. |
ticket_type_name | string | null | No | From ticket_snapshot. |
attendee_name | string | No | The attendee's name. |
status | string | No | confirmed, pending_payment, cancelled... |
checked_in_at | string | null | No | Set only by door scanning — present means Attended, absent means unknown, never "no". |
amount_cents | number | No | Amount paid in cents. |
currency | string | No | ISO currency code. |
registered_at | string | No | ISO time of registration. |
ticket_code | string | No | The code on the ticket (QR / barcode). |
access_token | string | No | Present only on the single-registration response (registration()), never on myRegistrations(). |
read_only | boolean | No | Same scoping as access_token above. |
read_only_notice | string | null | No | Text to show when read_only is true. |
PortalEventsFilter
Filter of Portal.events.events().
| Name | Type | Required | Description |
|---|---|---|---|
site | string | No | Only the events of this website (reference). |
PortalEventSummary
One event in a public event listing.
| Name | Type | Required | Description |
|---|---|---|---|
reference_num | string | Yes | The event's reference. |
slug | string | No | URL slug. |
name | string | Yes | The event's name. |
subtitle | string | No | A secondary line under the name. |
summary | string | No | A one-line summary. |
description | string | No | The full description. |
category | string | No | The event category. |
timezone | string | No | IANA timezone of the times. |
starts_at | string | No | ISO start of the next (or only) occurrence. |
ends_at | string | No | ISO end. |
occurrence_reference_num | string | No | The occurrence the summary times refer to. |
availability | string | No | available, sold_out... |
PortalTicketTypePublic
A ticket type as the public sees it.
| Name | Type | Required | Description |
|---|---|---|---|
reference_num | string | Yes | The ticket type's reference. |
name | string | Yes | The ticket type's name. |
description | string | No | What the ticket includes. |
kind | string | Yes | paid, free, donation... |
price_cents | number | Yes | Price in cents (0 = free). |
currency | string | Yes | ISO currency code. |
availability | string | Yes | available, sold_out, not_on_sale... |
remaining | number | No | Tickets left, when the server reports it. |
min_per_order | number | No | Fewest tickets per order. |
max_per_order | number | No | Most tickets per order. |