Pass Balances

Show how many Access Passes and Guest Passes the signed-in customer has left, per pass type

Show signed-in customers how many Access Passes and Guest Passes they have left, for example "3 Access Passes, 2 Guest Passes". Requires DOM Package 1.13.0 or later.

A pass balance is not a Guest Pass invitation. getPassBalances() counts the passes a customer holds. getGuestPasses() lists individual invitations, one per guest and visit; see Custom Guest Invitations for those.

Balances or invitations?

	Pass balances	Guest Pass invitations
Answers	How many passes do I have left?	Who have I invited, and who invited me?
DOM Package	`getPassBalances()`	`getGuestPasses()`
Hosted Package	`data-tiquo-pass-balance-total`, `data-tiquo-pass-balances`	`data-tiquo-guest-passes`
Customer API	`GET /pass-balances`	`GET /guest-passes`
Covers	Access Passes and Guest Passes	Guest Passes only
Each entry is	A pass type and its uses left	One invitation

Get balances

// After OTP sign-in.
const { accessPassBalance, guestPassBalance } = await tiquo.getPassBalances();

accessPassCount.textContent = String(accessPassBalance.total);
guestPassCount.textContent = String(guestPassBalance.total);

for (const passType of accessPassBalance.passTypes) {
  // passType.name, passType.balance, passType.nextExpiresAt, passType.sublocationNames
}
for (const passType of guestPassBalance.passTypes) {
  // passType.name, passType.balance, passType.heldByInvitations, passType.nextExpiresAt
}

getPassBalances() returns a TiquoPassBalances object:

{
  "accessPassBalance": {
    "total": 3,
    "passTypes": [
      {
        "passTypeId": "k57...",
        "name": "Day Access",
        "balance": 3,
        "nextExpiresAt": 1793404800000,
        "sublocationNames": ["Members Club / Gym"]
      }
    ]
  },
  "guestPassBalance": {
    "total": 2,
    "heldByInvitations": 1,
    "invitationsUseGuestPasses": true,
    "passTypes": [
      {
        "passTypeId": "k58...",
        "name": "Member Guest Pass",
        "balance": 2,
        "heldByInvitations": 1,
        "nextExpiresAt": 1792540800000
      }
    ]
  }
}

Display pass names with textContent. A signed-in customer without a completed profile gets zero balances.

Fields

Field	Description
`accessPassBalance.total`	Access Pass uses left across all Access Pass types
`guestPassBalance.total`	Guest Passes the customer can still give to guests. Doesn't include `heldByInvitations`
`guestPassBalance.heldByInvitations`	Guest Passes reserved by invitations the customer sent that haven't been used at reception yet
`guestPassBalance.invitationsUseGuestPasses`	`true` when sending an invitation uses a Guest Pass. `false` when the organisation has no guest limit; use the flow's `maxGuestsPerSubmission` as the limit instead
`passTypes[]`	One entry per pass type with uses left, or for Guest Passes, uses held by invitations

Each passTypes[] entry has:

Field	Applies to	Description
`passTypeId`	Both	Pass type ID
`name`	Both	Pass type name
`balance`	Both	Uses left of this type
`nextExpiresAt`	Both	Earliest expiry among these uses, in milliseconds. Omitted when none of them expire. Other uses of the same type may expire later
`sublocationNames`	Access Passes	Where the pass admits the customer, as `Location / Sublocation`
`heldByInvitations`	Guest Passes	Uses of this type reserved by sent invitations

What counts

Balances match what reception accepts:

Left out: expired, used-up, revoked and archived passes, passes that haven't started yet, and passes from a membership that's no longer active.
Counted early: passes a membership is due to issue but hasn't issued yet, because registration issues them on first use. A member with "3 guests a day" sees 3 from the start of each day.
Not covered: Package Passes.
Access Pass total: adds up every Access Pass type, whichever sublocations it covers. Use sublocationNames to show where each one works.

How invitations change the Guest Pass balance

In limited mode (invitationsUseGuestPasses is true):

Sending an invitation moves one use from total to heldByInvitations.
Accepting by the guest keeps it held.
Registering the guest at reception uses it up, so heldByInvitations goes down by one.
Expiry or revocation of the invitation returns it to total.

A guest who accepts an invitation gets nothing added to their own balance: the Guest Pass belongs to the host. The guest sees the invitation in getGuestPasses() with status: 'accepted'.

Refresh balances after the customer sends or accepts an invitation, when the page regains focus, or when they ask. Registrations at reception also change balances.

Hosted Package

The Hosted Package has the same window.Tiquo.getPassBalances() method, plus HTML attributes that render totals and per-type lists without code. See Pass balances.

Errors

getPassBalances() throws a TiquoAuthError:

NOT_AUTHENTICATED when no customer is signed in.
GET_PASS_BALANCES_FAILED with the server's message when the request fails, for example Unable to load pass balances.