Stowbo

StowboModule runs a marketplace for temporary custody of space: a guest books somewhere to leave a car, a bag or a box, and a host takes it in. Two surfaces, 188 routes: /stowbo/* is the platform operator's console (68 routes, scoped to nobody because overseeing everyone is its job), and /client/stowbo/* is the guest and host app (120 routes, every read scoped to whoever is signed in).

Every route takes the orgid header and needs a JWT. The operator controller is @StaffOnly(); on the client surface the gate is the JWT plus checks in the service:

• No customer needed. Browsing, the pickup pass (pickup/:token) and the pay page (pay/:ref) work with the site's app token and nobody signed in. init then answers { signedIn: false, host: false }.
• Customer only. Everything else on the client surface throws 401 Sign in required when there is no customer. Guest routes also check that the booking is yours (403 Not your booking).
• Approved host. Hosting is the CRM benefit stowbo-host (see CRM). Approval puts it on customer.data.benefits. Creating listings, units, add-ons, fees and coupons, and every take-payment, wallet and payout route, answer 403 without it. Host routes on a listing or booking also check that you own the listing (403 Not your listing).
• Operator. /stowbo/* answers only someone signed in to the business — never a customer or the site's app token (403).

The model

A listing is the bookable thing, and listings nest through parent: a locker bank holds locker types, a warehouse holds bays. Identical slots are a capacity count on one listing. Numbered doors are stowbo_unit rows. A listing carries rates (bands read as posted or progressive), payment (upfront %, deposit), taxRate, fees[] and addOns[] (by name), cancellationPolicy, staffing (manned · unmanned), blackouts and status (draft · active · paused · inactive).

A booking is an order. Its items[] is the bill: lines of kind space · addon · fee · tax · discount · adjustment · overstay. Amounts are signed, and a line is never edited — a mistake is undone by a reversing line. Order status: requested → confirmed → active → completed → settled, or cancelled. Payments are not stored on the booking. They are sf_transaction rows carrying metadata.booking, and the balance is worked out from them.

A booking item (stowbo_booking_item) is one thing booked, with its own window, unit, identifier (plate, tag), session and movements. Its status runs reserved → active → ended, and can also be disputed or cancelled. Twelve units under one order are twelve items, so every counter action addresses an item, never the order.

• Check-in opens the session and records the first in movement. It is idempotent.
• Movements (in / out) are unlimited and append-only inside one session. They are never billed and never touch capacity. Whether a thing is present is read from the direction of its last movement.
• Check-out is the only place an item stops using capacity. It refuses with 409 STILL_PRESENT until the thing has moved out. It adds what that item actually cost to the order as lines: an open stay priced from start to exit, or overstay past a fixed window.

Availability is never stored. It is worked out from open booking items, and the booking write checks it again, so a stale read can under-sell but cannot double-book.

Checkout

The pending purchase is a stowbo_cart (open · held · converted · abandoned · expired). Each customer has one, and it is updated in place.

• quote prices a mixed cart line by line and has no side effects. A bad code or a short line comes back in the answer; it is not thrown.
• cart saves the cart without claiming any capacity.
• resume prices the cart again rather than replaying the old total, and changed says whether the price moved.
• hold takes the capacity off the market for holdTtlMinutes (default 15, or the STOWBO_HOLD_TTL_MINUTES env). If anything is unavailable it answers 409 UNAVAILABLE.
• confirm captures by default; send captureNow: false to authorise only. What it charges is upfront% of the total plus any deposit, or nothing for a free or open-ended stay. A decline answers 402 and leaves the hold alive. A hold that has expired answers 409 HOLD_EXPIRED. Sending confirm again after it succeeded returns the same booking.

Cancellation terms are copied onto the booking when it is confirmed:

Guest routes

Discovery:

listings returns only top-level active listings. It searches by map viewport (swLat/swLng/neLat/neLng), by a point and radiusKm (default 10, max 200), or by city/keyword. With startDate + endDate it returns only what is free for that window, priced for it. Without dates it is a plain catalogue browse, with no availability or price.

My bookings and items:

• due?action=current|cancel gives the numbers the cancel will use.
• Cancelling is refused once any item is checked in. From then on, you check it out.
• extend and addons take payment before they commit, so a decline changes nothing.
• settle-payment can be sent more than once with the same payment intent; it settles once.
• The guest timeline leaves out who bore each cost internally.

Movements and self-serve parking:

staffing decides who moves things:

• unmanned. The guest records their own in and out, and can use park to start a metered open stay that is already checked in.
• Anything else (attended). The guest raises a tracked retrieval or return request and the host does the move. A manned listing refuses park.

Delegated pickup

The owner hands some items to someone else: a buyer, a colleague, a courier. The hand-off is a stowbo_pickup_delegation with its own pickup code and pass token.

• What to send. The body is items[], name, phone or email (one is required), verify (qr · qr_name · qr_id, default qr_id), and optional validUntil, note and photo.
• Which items. Each item must still be in custody and not on another live hand-off.
• How long. validUntil is capped at the booking end.
• The owner's code. While a hand-off is live, the booking's own pickupCode no longer releases those items.
• The token. It is stored hashed. resend issues a new link and the old one stops working.
• Where the outcome goes. Who collected, what was verified and any refusals are written on the booking item.

The host at the counter:

• GET host/handover?code= looks up a scanned code and releases nothing.
• POST host/handover needs verified[] to cover what the pass asks for (400 VERIFY_REQUIRED) and a photo for a hand-off (400 PHOTO_REQUIRED). It then moves each item out and checks it out.
• A refusal (wrong_person · expired · revoked · id_mismatch · other) moves nothing, and the owner is told.

Host routes

Becoming a host, and listings:

apply enrols the customer in the stowbo-host benefit and runs setup first if the org has never had it.

Add-ons, fees and coupons:

• Add-ons. An add-on with price: 0 is free. service: true means buying it raises a fulfilment request for the host. DELETE retires the add-on rather than removing it.
• Coupons. Host coupons are storefront discounts. The server locks each one to the host's own listings.
• Fees. A stowbo_fee is defined once and attached to listings by name. Its fields answer four questions:
  • Whose money: type (host · platform · tax · processing) and paidBy (guest adds a line to the bill; host comes out of the payout).
  • When it applies: trigger (booking · cancellation · late_pickup · no_show).
  • How it is counted: appliesTo (checkout once, or per item) and basis (fixed or percent).
  • Limits and scope: priceFrom/priceTo, minFee/maxFee, channels, spaceTypes, validFrom/validTo.

The counter:

• resolve?q= takes at least 2 characters and searches plates, phones, references, units and tags across the host's own listings.
• host/bookings opens a stay for someone at the counter. It defaults to an open stay, needs only one detail (phone or plate) to identify the customer, and 409s when the space cannot take it.
• GET …/checkout previews what closing the item will bill, with the same calculation POST uses.
• host/items/:itemId/request moves a guest's request along: acknowledged · preparing · ready.

Bookings, the bill and money:

due includes the meter still running on items that are present.

Take payment, wallet and payouts (approved host only):

• What is cleaned. Before a take-payment or payment-request body reaches the ledger, the controller caps amount at 1,000,000 and rounds it to 2 decimals, whitelists category (anything unknown becomes other), and falls back to usd for currency. Emails and phone numbers that fail a format check are dropped.
• take-payment records a Tap to Pay intent that has already succeeded.
• payment-request writes a pending ledger row and returns a pay link and QR code.
• complete is called by the signed-out web /pay flow, so it needs no customer. It verifies paymentIntentId with the gateway, and settles the request only when the charge covers its amount and currency; a charge that doesn't is recorded on its own and answered 402 PAYMENT_AMOUNT_MISMATCH.
• pay/:ref looks up a request token, then a ledger row, then a booking id, and always charges the balance the server computes.
• Payout methods. Bank numbers are encrypted when they arrive, and only the last four digits are ever returned.
• The wallet. available is balance minus reserved minus held. See finance wallets.

Operator routes

Setup and platform config:

• setup creates whatever is missing: the stowbo-host benefit, the stowbo-custody-pipeline workflow and the stowbo site. It is safe to run more than once, and it also runs on its own the first time someone applies to host.
• platform-config holds minPayout, takeRate (a fraction from 0 to 1, default 0.18), gateway (default stripe), holdTtlMinutes, appUrl and site. It is stored as an org setting and takes effect with no restart.
• platform-fees replaces the whole list. A body without a fees array answers 400.

A single booking:

POST /stowbo/booking goes through the same path as the customer app, with channel: operator. skipPayment records the booking as owed.

Money on a booking:

• settle adds overstay for items still open, then captures. It refuses with BOOKING_UNPAID while the ledger shows a balance. It then splits the money at the take rate and credits the host's wallet.
• A hold (paymentHold) still lets the guest be charged but stops the host being paid at settle.
• cancel frees units, voids an uncaptured authorisation, refunds per the cancellation terms and keeps the record. Send noShow: true for a no-show.
• refund without cancel leaves the stay running.
• An adjustment's bearer (guest · host · platform) says who absorbs it.

Spaces:

• A blackout does not cancel bookings already inside its window. They come back as conflicts.
• capacity limits a space for a window; capacity: 0 closes it.
• addons lists the listing's own add-ons plus those of every listing above it.

Oversight:

• items lists booking items, filtered by lane: custody · arriving · departing · overstaying · awaitingCheckout · present · gone · requests.
• funnel follows cart → details → payment → held → booked → turned up → collected, and counts walk-ins separately.
• audience?group= turns a group into real recipients. Groups: hosts.all · hosts.pending · hosts.overstaying · guests.inCustody · guests.overstaying · guests.unpaid · booking.both.

Ledger, discounts and hand-offs:

• Refunds. A refund writes a linked refund row and marks the original; the original amount is never changed.
• Cancelling a request refuses one that is already paid; refund it instead.
• Discounts. :action is activate or deactivate. A platform discount belongs to nobody, so no host can edit it.

Datatypes

stowbo_listing, stowbo_unit, stowbo_addon, stowbo_fee, stowbo_cart, stowbo_booking, stowbo_booking_item, stowbo_pickup_delegation, plus sf_transaction for every payment and refund.