Bookings

A booking moves through a defined lifecycle, and every screen in ShortletBox (the list, the calendar, the payment pages, the reports) reads from the same state. References look like SB-XXXXXX.

The lifecycle

awaiting_approval ──approve──▶ pending_payment ──payment lands──▶ confirmed
        │                            │                               │
     decline                       expire                        check in
        ▼                            ▼                               ▼
     declined                     expired                       checked_in ──▶ checked_out

• Awaiting approval: a guest’s request from your booking site. Approve or decline it from the list, the booking page, or the dashboard action queue.
• Approve is payment-aware: if a deposit is owed, the booking moves to Pending payment and the guest gets a pay-by-link with a payment hold (48 hours by default, configurable per workspace). If nothing is owed, it confirms outright.
• Pending payment: the clock is ticking. If the hold lapses unpaid, the booking expires automatically and the nights free up.
• Confirmed: money (or your say-so) has secured the dates. The guest automatically receives their check-in link.
• Checked in: available once every occupant’s ID has been confirmed by your team. Card payments have already settled to your payout account when the guest paid, once payment routing is on for your workspace.
• Checked out: the stay is complete.
• Cancelled: possible from any pre-checkout state. Cancelling revokes any smart-lock door codes already issued.

Bookings carry their source: direct (your site, widget or API), admin (created by your team), or airbnb / booking_com.

Creating a booking yourself

Add booking on the Bookings page, or New Booking in the top bar, is for walk-ins and phone bookings. Pricing is calculated server-side (nightly rate × nights, length-of-stay discount, then coupon), and you can override the deposit for this one booking. Guests are de-duplicated by email, so a returning guest keeps one history. Bookings you create are confirmed immediately and skip the online check-in gate.

If your plan has a monthly booking cap, creation is blocked at the cap, and the banner in the admin warns you from 80%.

Send a client booking link

Owners and admins can turn a negotiated stay into a secure payment link without confirming it by hand.

1. Open Bookings → Send booking link.
2. Choose the property and dates, then enter the guest’s name, email, optional phone number and guest count.
3. Enter the agreed nightly rate. ShortletBox starts with the property’s base rate, but you can replace it with the amount you agreed.
4. Choose Create hold & email link.

ShortletBox immediately creates a Pending payment booking and blocks the dates for 48 hours. The agreed rate is exact: length-of-stay discounts and coupons do not stack onto it, and the client cannot edit it. The form does not offer agent pricing, add-ons or a deposit override.

The client receives an email showing the stay, rate, total, required deposit and exact hold deadline. The payment URL contains no readable guest, property or price data. Paying the property’s required deposit confirms the booking; if the property has no deposit requirement, the client must pay the full amount.

If the email cannot be queued, the booking and hold still exist. Open the booking and choose Resend payment link instead of creating another hold. If the deadline passes unpaid, the booking expires, the link stops working and the dates become available again.

Staff can resend an existing payment link, but only owners and admins can create a client booking link.

No double bookings, ever

Overlapping active bookings for the same property are impossible. The rule is enforced at every level, down to the database itself, and it also runs race-safe: two guests grabbing the last night at the same instant can’t both win. Back-to-back stays are fine, since checkout day and the next check-in day can be the same date.

Manual calendar blocks and OTA blocks also make dates unavailable, but a lagging OTA feed can’t lock you out of fixing a real booking; blocks are only checked when a booking’s dates actually change.

Occupants

Each booking tracks who is actually staying. The primary guest adds companions during check-in (capped at the booking’s guest count), or your team manages the occupant list from the booking page: add, edit, remove, resend links, confirm IDs, request re-uploads.

Where money fits

Each booking’s pricing card shows the total, what’s been paid, the balance, and a payment-state chip (Unpaid → Partially paid / Deposit paid → Paid, or Refunded), always computed live from the payments ledger, never stored, so it can never disagree with the money.