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.
The cap is re-checked again at issuance time, after payment has already gone through. It used to be checked only when a purchase started (before payment), so if several browser tabs or several guests purchased at nearly the same moment, the cap could be exceeded. Now the cap is re-evaluated once more right before a ticket book is issued, after the Stripe payment has succeeded. A purchase that is found to be over the cap at that point is not issued, even though payment has already succeeded. See Troubleshooting for what the guest sees in that case and what the facility should do.
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)
Feature 10: Issuing at the Counter (Cash Sale at the Front Desk)
A "Issue at the counter" button appears on the ticket book detail screen, letting the front desk sell and issue a ticket book on the spot, without the guest using the Member App.
| Condition | Behaviour |
|---|---|
| The ticket book is on sale (not a draft) and priced above ¥0 | The button appears |
| A draft (unlisted) ticket book, or one priced at ¥0 | The button does not appear |
- Click "Issue at the counter" in the top-right of the ticket book detail screen (the same screen as the Sales & Usage tab)
- The receipt dialog opens. First enter the guest's email address to issue to (it must belong to a registered member account — the balance is tied to that account)
- Enter the amount received (defaults to the ticket book's price), the payment method (cash / bank transfer / other), the date and time received, and an optional note, then click "Record receipt"
- The receipt is recorded and the ticket book balance is issued on the spot
Why an email address is required. A ticket book balance belongs to an account, and the front desk only has an email address in front of them, so the server resolves it to a registered account before issuing. It cannot issue to an unregistered email address (see the error below) — direct the guest to sign up first.
The purchase limit, sales window, and sold-out rules are exactly the same as an online purchase. A counter sale is rejected the same way if it fails any of these checks.
Errors specific to counter issuance
| Error | Meaning | What to do |
|---|---|---|
| No member found for this email address | The entered email is not a registered member | Direct the guest to sign up (Member App), then issue again once registered |
| This guest has reached the purchase limit | Hits the Feature 4 purchase limit (count / window) | Check the limit setting and this guest's purchase history |
| This ticket book is sold out | The issuance cap has been reached | Offer a different ticket book, or review the issuance cap setting |
| This ticket book is outside its sales window | The valid period or sales status conditions are not met | Check the ticket book's configuration |
If the receipt was recorded but issuance failed, you do not need to take payment again. The receipt itself is already on the books — check the limit or sales status, and issue a refund if needed (the screen shows "Receipt recorded, but the ticket book could not be issued.").
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, the pre-login Landing page, or the dedicated Ticket Books page (/{facility slug}/tickets) reachable from MyPage, and pays via Stripe. Payment happens entirely inside the app — there is no redirect to an external payment page (the same screen layout as a membership sign-up; it used to redirect to a separate page). Starting a purchase requires being signed in. Once payment settles, the balance is issued to the guest. For the guest-facing screens in detail, see Home Screen (Member App) — "Feature 8: Buying a Ticket Book"- ②' Cash sale at the front desk (counter issuance): Instead of buying online, the front desk can sell a ticket book for cash or bank transfer from "Issue at the counter" on the ticket book detail screen and issue it on the spot (see Feature 10)
- ③ 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 in a window the plan's cancellation policy refunds in full, the balance is restored and can be used for another reservation. Any window that charges even 1% (partial or no refund) forfeits the balance — a ticket book cannot be split, so there is no partial-return equivalent. Facilities with no cancellation policy configured refund in full at any time, so the balance comes back; cancelling after the check-in time has passed forfeits it regardless of the policy
- ⑤ 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 falls in a window the plan's cancellation policy refunds in full, the consumed credit is restored and can be used for another reservation. In any fee-bearing window (partial or no refund) the credit is not restored — it stays consumed, because a single ticket cannot be split in half.
The verdict reads the same policy tier the refund does, so it always matches what the cancellation confirmation screen shows.
| Cancellation timing | Money | Ticket |
|---|---|---|
| Full-refund tier | Refunded in full | ✅ Returned |
| Partial-refund tier (e.g. 50%) | Partially refunded | ❌ Not returned |
| No-refund tier | Not refunded | ❌ Not returned |
| After the check-in time | Per the policy | ❌ Not returned |
With no cancellation policy configured, every cancellation refunds in full, so the credit comes back as long as the check-in time has not passed. Cancelling after check-in time (a no-show) never returns it, whatever the policy says.
Careful how you read a tier: "Hours before check-in" is a floor — it means "this many hours or more before". A single tier of
24h → 100%does not mean "100% within 24 hours", it means "100% whenever you cancel", and the ticket then never comes back. To get "100% once inside 24 hours", configure two tiers:24h → 0%and0h → 100%. The settings screen previews the rates a policy actually produces.
Modifying a reservation follows the same rule. When an hours-based ticket booking is shortened, the unused minutes only return to the balance inside the full-refund window. Shortening inside a fee-bearing window keeps the minutes spent, so a booking cannot be shrunk first to avoid forfeiting them.
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.
Q: The "Issue at the counter" button doesn't show up
Check whether the ticket book is on sale (not a draft) and priced above ¥0. The button does not appear for a draft ticket book or one priced at ¥0.
Q: Counter issuance says "No member found for this email address"
Counter issuance can only issue to a registered member's email address. If the guest has not created a Member App account yet, direct them to sign up first, then issue the ticket book again.
Troubleshooting
A guest says "I paid, but the ticket book was never issued"
The purchase limit (Feature 4) is re-checked not only before payment but again right before a ticket book is issued. If several purchases land at nearly the moment the cap is reached, a purchase can pass the Stripe payment step and still fail to be issued because the cap was exceeded at that later check. The message shown to the guest tells you which situation you are dealing with.
| Message shown to the guest | What happened | What the facility should do |
|---|---|---|
| "This ticket book could not be issued because its purchase limit had already been reached. The facility will review your payment and contact you about a refund." | Issuance refused because of the purchase limit. Payment succeeded, but it will not be issued automatically after this | No automatic refund is issued. Check the payment in your Stripe records, decide whether a refund is warranted, and contact the guest yourself |
| "Payment succeeded but the ticket book could not be issued. Please check your balance again shortly." | A temporary processing error unrelated to the purchase limit | This can resolve itself via a background retry. Ask the guest to check their balance in the Member App again after a short wait |
There is no automatic notification to the facility owner. In either case, you currently learn about it only when the guest reaches out.
Related Pages
- Membership Plans
- Booking Management Dashboard
- Home Screen (Member App)
- My Page (Member App)
- Check-in History
Last updated: 2026-09-08 - Documented counter issuance / cash sale at the front desk (Feature 10, Epic #3421 / #3427): requires a registered member email address, and the purchase limit, sales window, and sold-out rules are shared with an online purchase.
Previously updated: 2026-09-02 - PR #3114 (#3105 follow-up): documented that the purchase limit is now re-checked at issuance time, after payment succeeds, and added the Troubleshooting section covering an issuance refusal after a successful payment. PR #3107 (#3105): documented that purchasing in the Member App now happens entirely inside the app rather than redirecting to an external page, with details linked to member-home.md. PR #3124 (#3120): documented the two distinct guest-facing messages for a refused issuance vs. a temporary processing error.
Previous update: 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)