Ticket Books
Overview
A Ticket Book is a product that lets guests prepay for a bundle of stays or hours in advance. From the Ticket Books menu in the admin dashboard (/ticket-books), you can create and manage per-facility ticket book products such as "a book of 10 stays for ¥80,000" or "50 hours pass for ¥50,000".
A Ticket Book is a specialization of the promotion feature (effect kind grantReservations) and is issued with a unit (count or hours).
- Count unit: "1 reservation = 1 ticket consumed". Good for flat-rate products such as a stay or a time-slot booking
- Hours unit: "1 reservation consumes the reservation's duration". Good for time-based rentals (meeting rooms, shared workspace) where each booking's length varies
Once a ticket book has been purchased by a guest, the remaining balance can be applied toward the price of a future reservation instead of paying cash.
Current implementation status (2026-08): The end-to-end flow — product creation (this page), purchase from the Member App, redemption at booking time, restoration on cancel, and pre-expiry email notifications — is fully implemented.
Detailed Features
Feature 1: Creating a Ticket Book
- Open Ticket Books from the left-hand menu in the admin dashboard
- Click Create Ticket Book
- Fill in the following fields
| Field | Description |
|---|---|
| Name | The product name of the ticket book (e.g. "10-Stay Book", "50-Hour Pass"). Shown on the list screen and at purchase time |
| Description (optional) | An optional supplementary description |
| Unit | Count or Hours. Count = 1 reservation consumes 1 ticket; Hours = consumes the reservation's duration (see Feature 7) |
| Quantity / Hours | With Count, the number of uses per book; with Hours, the number of hours per book. Integer, 1 or more |
| Sale Price (JPY) | The price of the whole book (an integer, 0 or more; whether it is tax-inclusive follows your facility's usual practice) |
| Valid Period | How long the tickets remain valid after purchase. Choose 1 month (30 days) / 3 months (90 days) / 6 months / 1 year / 2 years. The short options are exact day counts; 6 months and longer use month arithmetic |
| Purchase Limit (per user) | The maximum number of times one guest may purchase this book. A limit of at least 1 is always saved — "unlimited" is not available. New books open with "1" already filled in, and saving the field blank or as 0 still stores 1 per person (see Feature 4) |
| Purchase Limit Window | The reset cycle used for the cap above. Choose Lifetime (never resets) / Per calendar year / Per calendar month / Every 365 days / Every 30 days (see Feature 4 for details) |
| Applicable Plans | Restrict which reservation plans can redeem this book. Leave blank to allow every plan at the facility; select one or more to restrict (see Feature 5) |
| Make Available for Sale | When ON, the ticket book becomes purchasable. When OFF, it is saved as a draft (not publicly available) |
- Click Save to create the ticket book
Feature 2: Editing a Ticket Book
- From the ticket book list, tap the card of the ticket book you want to edit
- On the Edit tab, edit the fields and click Save
Editing the quantity, price, or valid period does not affect ticket books that have already been purchased. Each purchase locks in the terms (quantity, price, valid period) at the moment of purchase, snapshotted into the Stripe payment data. Editing only changes the terms offered to future purchasers.
You cannot change the unit on a ticket book that has been sold. Once a ticket book has been purchased at least once, the unit selector locks and you can no longer switch between Count and Hours (existing balances would be in one unit while new balances would be in the other, breaking sales aggregation). To switch units, mark the product as Draft to stop selling it and create a new product with the other unit.
Deleted applicable plans: if a plan you previously linked as an applicable plan has since been deleted, it appears as a red "(deleted plan)" chip in the Applicable Plans field. Use the × button to clear it. Leaving it in place makes the ticket book "only usable on a deleted plan" — no reservation can ever redeem it.
Feature 3: Reading the List Screen
The ticket book list shows each created ticket book as a card.
- The name and a summary line, "{quantity} tickets / ¥{price}", are shown
- A badge on the right indicates the status:
- On Sale: guests can purchase this ticket book
- Draft: not publicly available (cannot be purchased)
- Tapping a card opens the edit screen
To stop selling a ticket book, open it for editing and uncheck Make Available for Sale, then save. The current admin dashboard does not have a delete button for ticket books. If you want to stop selling one, switch it to draft (unpublished) instead.
Feature 4: Purchase Limit Window (max_per_user_window)
Purchase Limit (per user) and Purchase Limit Window work together to control how many times one guest can purchase this ticket book.
| Field | Meaning |
|---|---|
| Purchase Limit (per user) | The maximum number of purchases one guest may make (within the cycle below). Whole numbers of 1 and up only — there is no "unlimited" setting |
| Purchase Limit Window | The reset cycle (starting point) used to count the cap above. Lifetime (never resets) / Per calendar year (resets Jan 1st) / Per calendar month (resets the 1st) / Every 365 days (rolling window) / Every 30 days (rolling window) |
A guest who has already reached the cap has their next purchase attempt rejected.
Important — the actual default behaviour: There is no "unlimited" for ticket books. Saving Purchase Limit (per user) blank or as 0 still stores a cap of 1 purchase, and the default window is "Lifetime (never resets)" — so each guest can buy it exactly once, ever. A ticket book created without touching this field is in exactly that state. If you want guests to be able to purchase more than once, enter the number you want in Purchase Limit (per user), and set the Purchase Limit Window if needed.
The new-ticket-book form opens with the default of "1" already filled in, so the number on screen is the number that gets saved.
Feature 5: Applicable Plans
Restricts which reservation plans this ticket book can be redeemed against. Configure via the Applicable Plans MultiSelect on the Edit tab.
- Blank (default): redeemable on every reservation plan at the facility
- One or more selected: redeemable only on the selected plans; other plans fall back to normal payment
Selected plans render as blue chips; the × button removes each one individually. The search box filters by plan name.
Membership-only (¥0) plans are not offered as choices — applying a ticket book to a booking that a membership already makes free serves no purpose, so the picker only shows paid reservation plans.
Feature 6: Sales & Usage (SalesTab)
The ticket book detail screen has a Sales & Usage tab next to the Edit tab, showing this product's sales record and each purchaser's usage.
- Summary (4 cards): sold count / issued (or "issued hours" for hours units) / used / remaining
- Purchases list: for each purchase,
- Buyer email and purchase date
- "remaining / issued" balance
- Count unit: a dot gauge (filled dot = remaining, hollow dot = used)
- Hours unit: a progress bar (brand accent colour showing hours left)
- A "Used N · Remaining M" caption
Expired or cancelled credits are automatically excluded from the "remaining" totals, so the numbers you see always reflect what is actually usable right now.
Feature 7: Unit (Count / Hours)
The Unit you pick at creation determines how consumption is counted.
| Unit | Consumption Model | Best For |
|---|---|---|
| Count | 1 reservation = 1 ticket consumed | Nightly stays, time slots, buyouts — "flat rate per booking" products |
| Hours | 1 reservation = the reservation's duration in hours (e.g. a 3-hour booking consumes 3 hours) | Meeting rooms, coworking, and other hourly rentals |
For Hours, if the reservation's duration exceeds the ticket book's remaining balance, the ticket cannot be redeemed (ticket books are not split — one book must cover one reservation, otherwise the guest pays normally). The guest's booking screen automatically decides this at STEP 3 (the confirmation step).
Feature 8: Permissions
Creating, editing, and viewing ticket books requires Facility Owner level access or higher.
| Permission Level | Access to Ticket Books |
|---|---|
| Organization Owner | Can manage ticket books for every facility under their organization |
| Facility Owner | Can manage ticket books for their own facility only |
| Facility Member | No access |
Feature 9: Pre-Expiry Email Notifications
Each ticket book balance (credit) has an expiry date. To keep guests from missing an unused balance, the system automatically emails them as expiry approaches.
| Timing | Subject line |
|---|---|
| 30 days before expiry | "【失効予告】回数券の有効期限まで 30 日を切りました" |
| 7 days before expiry | "【まもなく失効】回数券の有効期限が近づいています" |
| The day of expiry | "【本日失効】回数券の有効期限のお知らせ" |
- An automated scan runs every day at 7:00 AM JST, sending to the guest's registered email address
- If one guest has multiple credits expiring on the same day, they are combined into a single email
- The email body includes the expiry date, remaining balance ("N remaining" for count books, "N hours remaining" for hours books), and a link to the Member App
- The same credit and threshold (30 days / 7 days / same-day) is never sent twice
- This notification is purely informational — it does not change the balance or accelerate expiry. Expiry is still evaluated at the moment of redemption or balance lookup
- In the current version, the notification email body is hard-coded in Japanese — it is sent in Japanese regardless of the guest's display language setting (e.g. English)
The End-to-End Flow
The full ticket book lifecycle consists of the following steps. All are implemented.
- ① Create the product (this page): An admin configures unit, quantity (hours), price, valid period, purchase limit, and applicable plans in the Ticket Books menu
- ② Guest purchase (Member App): A guest picks the product from the Member App's (
member.unlockos.io) Home screen, or the dedicated Ticket Books page (/{facility slug}/tickets) reachable from MyPage, and pays via Stripe. Once payment settles, the balance is issued to the guest - ③ Redemption at booking time (Booking App): When a guest with a valid ticket book balance books an applicable plan, STEP 3 of the booking screen shows a "Pay with a Ticket Book" toggle. Selecting it consumes one ticket (or the reservation's duration in hours) and creates a ¥0 reservation. Add-on option products are not covered by the ticket book and are charged separately
- ④ Cancellation handling: If a reservation made with a ticket book is cancelled at least 7 days before check-in, the balance is restored and can be used for another reservation. Cancelling less than 7 days before check-in forfeits the balance (it stays consumed)
- ⑤ Pre-expiry notifications: Guests are emailed 30 days, 7 days, and on the day of expiry (see Feature 9)
Frequently Asked Questions
Q: Can I sell a ticket book to guests right now?
Yes. Products marked On Sale are purchasable by guests from the Member App at member.unlockos.io (Home screen or the Ticket Books page). The balance is issued automatically after payment settles and can be redeemed against future bookings of the applicable plans.
Q: Can I switch the unit of a Count ticket book to Hours later?
Yes, but only while nobody has purchased it yet. Once a single purchase happens, the unit selector locks and you can no longer switch. (Existing purchasers hold balances counted in the old unit; a switch would break sales aggregation and balance comparisons.)
To switch units, mark the product as Draft to stop selling it, then create a new product with the desired unit.
Q: If I set applicable plans, can the ticket book still be used on other plans?
No. With one or more applicable plans selected, the ticket book is redeemable only against those plans. On any other plan, the "Pay with a Ticket Book" toggle does not appear and the booking is charged normally. Leave the field blank to allow every plan at the facility.
Q: What happens if a plan I linked as an applicable plan is later deleted?
It shows up as a red "(deleted plan)" chip on the Edit tab; click the × to remove it. If you leave it in place, the ticket book becomes "only usable on a deleted plan" and no reservation can ever redeem it — outstanding purchased balances effectively become unusable and may need a refund.
Q: My hours ticket has 5 hours left. Why can't I use it for a 6-hour booking?
Ticket books are not split — one ticket book must cover one reservation. A 5-hour balance cannot be partly applied to a 6-hour booking; that booking falls through to normal payment. The booking screen decides this automatically at STEP 3 and hides the toggle when the ticket cannot cover the reservation.
Q: If I change the quantity or price later, does it affect guests who already purchased?
No. The terms at the time of purchase (quantity, price, valid period) are locked into the payment data as a snapshot, so editing only changes the terms offered to future purchasers.
Q: I want to delete a ticket book, but I can't find a delete button
The current admin dashboard has no delete button. To stop selling a ticket book, open it for editing and uncheck Make Available for Sale to switch it to draft. Ticket books that already have purchase/redemption history are designed to never be permanently deletable, to preserve data integrity.
Q: If I leave "Purchase Limit (per user)" blank, can guests buy as many as they want?
No. Saving the field blank or as 0 caps each guest at 1 purchase, for the lifetime of the product (see Feature 4). There is no setting that removes the purchase limit. If you want guests to be able to buy many times, enter a large enough number in Purchase Limit (per user).
Q: If a guest cancels a reservation made with a ticket book credit, does the ticket come back?
If the cancellation happens at least 7 days before check-in, the consumed credit is restored and can be used for another reservation. Cancelling less than 7 days before check-in does not restore the credit — it stays consumed.
Q: Does using a ticket book on a booking also cover add-on options?
No. A ticket book only covers the base plan price. Any add-on option products selected at booking time are billed separately in the usual way.
Q: If a guest has both a free membership quota and a ticket book credit, which one is used?
The membership's free quota takes priority. If the booking fits within the free quota, no ticket book credit is consumed; the credit is only redeemed for bookings that exceed (or don't qualify for) the free quota.
Q: Do ticket book purchases or redemptions show up in "Transaction History" (Go Portal)?
No. In the current version, ticket book purchases and ticket-book-funded (¥0) bookings are not included in the Transaction History page's records. Guests should check their ticket book balance from the Member App's MyPage instead.
Q: The Ticket Books menu doesn't show up
Ticket Books is a beta feature that is hidden by default and requires per-facility opt-in. If it doesn't appear, or if opening the URL directly redirects you to the home page, ask support to enable menu_ticket_books for your facility.
Related Pages
Last updated: 2026-08-21 - #2809 (purchase-limit wording now matches the real behaviour: placeholder "Leave blank for no limit" → "Blank = 1 per person", the new-book form shows the default of 1, the Purchase Limit Window is always editable, and the window label "No limit" → "Lifetime (never resets)"). PR #2374 (added the Purchase Limit (per user) field and documented that leaving it blank actually defaults to a cap of 1 + added pre-expiry email notifications at 30 days / 7 days / same-day). Fixed the Member App URL (app.unlockos.io → member.unlockos.io). Added notes that add-on options are not covered, membership free quota takes priority over ticket book credits, and purchases/redemptions do not appear in Transaction History.
Previous update: 2026-08-06 - PR #2224 (unit = count/hours + applicable plans MultiSelect + post-sale unit lock + 30/90-day validity options + Sales & Usage tab + Member App purchase flow)