Payments, Cancellations, and Inventory Protection
Book Ahead combines payment collection and inventory protection so operators can confidently promise future scooter and bike availability.
Deposit Payment Model
Model reservations use an upfront booking deposit.
When a rider confirms a booking:
- The backend creates the reservation through an atomic reservation function.
- The platform charges the booking deposit immediately through Stripe.
- If the deposit charge succeeds, the reservation is confirmed.
- If the deposit charge fails, the reservation is marked expired and the rider sees a payment error.
Book Ahead does not depend on long-lived authorization holds.
Deposit is non-refundable
Model reservation booking deposits are labeled and treated as non-refundable. Use consistent language in rider support, policy pages, and operator training.
What the Deposit Covers
The booking deposit is applied toward the reservation total.
| Amount | Meaning |
|---|---|
| Total | Full reservation cost for the selected model, quantity, and time window |
| Booking deposit | Amount charged immediately at booking |
| Amount paid | Money already collected from the rider |
| Balance due | Remaining amount to collect at checkout |
For example:
| Total | Booking Deposit | Balance Due |
|---|---|---|
| $40.00 | $15.00 | $25.00 |
| $20.00 | $20.00 | $0.00 |
| $120.00 | $50.00 | $70.00 |
The booking deposit is capped at the booking total, so the rider is not charged more than the reservation total as the upfront deposit.
Checkout Balance Collection
At checkout, the system attempts to collect the remaining balance.
If collection succeeds:
- The reservation completes.
- Balance due becomes zero.
- Assignment is released.
- Rider receives checkout notification.
If collection fails:
- The reservation can still complete.
- The unpaid amount remains as balance due.
- Mobile reports the unpaid balance.
- Operators can follow up through support or billing workflows.
This keeps operational state accurate even when payment recovery needs separate handling.
Cancellation Behavior
When a model reservation is cancelled:
- Reservation status changes to cancelled.
- Active assignments are released.
- Assigned vehicles can be used again.
- Cancellation reason is stored when provided.
The booking deposit remains non-refundable for model reservations. Any other cancellation fee or refund handling should follow the operator's published policy and configured pricing/cancellation rules.
No-Show Behavior
If a rider does not arrive within the no-show window, the reservation can be marked no-show by the scheduled process.
No-show handling:
- Marks the reservation as no-show.
- Releases assigned vehicles.
- Keeps the booking history for reporting and support.
- Preserves the payment and balance state on the reservation.
Operators should review no-shows periodically to identify locations, times, or policies that need adjustment.
Cap-Based Availability
Book Ahead sells against inventory caps.
Availability is calculated as:
Available quantity = Model cap - Quantity already booked in overlapping reservations
The overlap rule checks reservations where:
- Existing pickup is before the requested return.
- Existing return is after the requested pickup.
- Status is not in a non-blocking final state such as cancelled, expired, completed, or no-show.
- Location and model match.
This means two reservations conflict if their booking windows overlap for the same pickup location and vehicle model.
Atomic Booking Protection
The booking create operation is atomic. This prevents two riders from simultaneously buying the last unit of the same model capacity.
If capacity is gone by the time a rider confirms:
- The create operation fails.
- The rider should choose another model, location, quantity, or time window.
- No confirmed reservation is created for unavailable inventory.
Assignment Conflict Protection
After a model reservation is sold, the assigned physical vehicle is protected separately.
The same vehicle cannot be assigned to overlapping reservations when assignment status is active. This protects against:
- Assigning one vehicle to two model reservations.
- Assigning a vehicle that already has an overlapping direct vehicle reservation.
- Assigning a vehicle blocked by maintenance or availability windows.
Walk-Up Unlock Protection
Instant walk-up rides check for upcoming reservation pressure before unlocking.
A walk-up unlock can be blocked when:
- The exact vehicle has an upcoming reservation.
- The vehicle is already assigned to an upcoming model reservation.
- The vehicle's model is needed to satisfy unassigned or partially assigned model reservations in the near term.
This prevents walk-up riders from consuming the last available units needed for confirmed Book Ahead reservations.
Near-term pressure window
The unlock flow checks upcoming reservation pressure close to the current time. It is meant to protect imminent bookings without unnecessarily suppressing all walk-up demand for the entire day.
Operator Monitoring
Use these dashboard surfaces:
| Surface | Use |
|---|---|
| Reservations list | Review all bookings, statuses, customer details, and dates |
| Reservation detail | See financial summary, booking deposit, balance due, vehicle/model, notes, and assignments |
| Inventory page | Configure locations and model caps |
| Assignment queue | Find upcoming model bookings that still need vehicles |
| Eligible vehicle picker | Assign vehicles and inspect unavailable reasons |
Troubleshooting
| Symptom | Likely Cause | Action |
|---|---|---|
| Model does not appear in Book Ahead | No active cap, inactive location, deleted model, or filtered vehicle type | Check inventory caps and location setup |
| Model appears but cannot be booked | Missing or invalid pricing tier | Configure reservation pricing for the model or vehicle type |
| Available quantity is lower than expected | Overlapping bookings consume cap quantity | Review reservations for the same location, model, and time window |
| Booking fails at confirmation | Capacity changed or deposit charge failed | Ask rider to retry or choose another option; inspect Stripe/payment logs |
| No eligible vehicles for assignment | Vehicle not reservable, wrong model, bad status, conflict, or blocked window | Expand unavailable reasons on the assignment panel |
| Walk-up unlock blocked | Vehicle or model is needed for an upcoming reservation | Assign/stage reservation vehicles or direct rider to another available unit |
| Balance due remains after checkout | Remaining balance charge failed | Follow up through support or billing workflow |
Production Readiness Checklist
Before enabling Book Ahead in production:
- Apply the reservation migration to the environment.
- Regenerate Supabase types from the real database.
- Configure reservation locations and timezones.
- Configure pricing tiers for reservable models.
- Configure conservative inventory caps.
- Mark physical vehicles as reservable.
- Test deposit charge success and failure.
- Test assignment conflict protection.
- Test walk-up blocking near an upcoming booking.
- Test single-unit check-in and checkout.
- Test multi-unit operator-assisted pickup.
- Test cancellation and no-show release behavior.