Locker Management Help

Overview

Locker Management is the admin interface for running a KEYVOX-connected smart locker rental service at your facility. You define locker sizes, pricing, and assigned KEYVOX units in a "locker config", then share the generated guest-facing booking URL. The order dashboard gives you a real-time view of activity, and individual order detail pages let you inspect access codes and cancel orders.

From the main navigation, select Locker Management to open the locker dashboard.

Guest Booking Flow (Overview)

Guests access the URL you share and complete a booking in four steps.

Step Screen What Happens
1 Size selection Available sizes are fetched from KEYVOX in real time
2 Duration and mode Guest picks a box mode and date range; price is calculated automatically
3 Confirm and pay Guest enters contact details, then completes Stripe payment
4 Complete PIN code, QR code, and assigned box number are displayed

Features

Feature 1: Locker Dashboard (Order List)

The dashboard at /locker lists all locker orders for your facility.

Stats Bar

Three summary cards appear at the top of the page:

Card Description
Active Rentals Number of orders currently in checked_in status
Today's Revenue Total amount from paid orders created today
Total Revenue Total amount from all paid orders in the current date range

Status Filter Tabs

Filter Shows
All Every order regardless of status
Confirmed Orders confirmed but not yet started
Active Orders currently in use
Completed Orders whose rental period has ended
Cancelled Cancelled orders

When viewing "All", a count badge appears next to each non-zero status.

Search and Date Filter

  • Text search: Type a guest name or order number — the list updates automatically after a 400 ms debounce
  • Date range: Defaults to 30 days ago through 90 days ahead. Use the DateRangePicker to change the window
  • Reset: Returns all filters to their default state

Order Card Fields

Field Description
Guest name / email The name or email of the guest who booked
Status badge Current order status
Amount Total order amount (an "Unpaid" badge appears if payment is outstanding)
Size Locker size and display name
Rental period Start and end date/time
Order number Internal reservation ID
Email Guest email address

Click an order card to navigate to the order detail page.

Feature 2: Locker Config List

Click Locker Config in the top-right of the dashboard, or navigate directly to /locker/config.

Each config card shows the config name, active/inactive status, and currency.

Action Buttons

Button Description
Copy URL icon Copies the guest-facing locker booking URL to the clipboard
Edit (pencil) icon Opens the locker config edit form
Delete icon Deletes the config after confirmation

Note: Deleting a config prevents new bookings via that URL but does not affect existing orders.

Feature 3: Creating and Editing a Locker Config

Click New Locker Config from the config list, or click the edit icon on an existing config.

Basic Fields

Field Description Required
Config name Internal label (e.g. "1F Lockers Summer 2026") Yes
Active toggle Enable or disable new bookings via this config —
Description Optional notes about this config No
Currency JPY, USD, or EUR —
Timezone Used for date calculations (default: Asia/Tokyo) —

Facilities connected to KEYVOX can auto-populate size and box information directly from the API.

  1. Click Fetch Devices to load the KEYVOX lockers registered to your facility
  2. Select a device from the dropdown — box sizes and box numbers are filled in automatically
  3. Enter only the pricing fields for each size row to finish setup

If KEYVOX is not connected or an error occurs, click Switch to Manual Entry in the top-right of the section to enter sizes manually.

Size Definition

You can define multiple sizes (S / M / L / Custom) within one config. Each size row requires:

Field Description
Size S, M, L, or Custom
Display name Label shown to guests (e.g. "S (Small)")
Long-term daily rate Price per day for long-term mode (unlimited access)
One-time daily rate Price per day for one-time deposit mode (single open/close)
KEYVOX Unit IDs Manual entry only. Comma-separated KEYVOX unit IDs for this size

About the two rates: Guests choose their box mode during booking. "One-time deposit" (single open/close, lower price) uses the one-time daily rate; "Long-term" (unlimited access, standard price) uses the long-term daily rate. Set both rates for each size.

  • Click Add Size to add another size row
  • Click the × button on a row to remove it (at least one row is required to save)

Share URL (edit mode only)

After saving, the guest-facing booking URL is displayed:

https://locker.unlockos.io?configId=<config-id>

Click Copy URL to copy it to the clipboard. Share this URL with guests via email, your website, or a QR code.

Save and Cancel

  • Save: Saves the config and returns to the config list
  • Cancel: Discards changes and returns to the config list

Feature 4: Order Detail

Click any order card in the dashboard to open the order detail page at /locker/order/:id.

Information Sections

Section Contents
Guest Info Name, email address, phone number
Locker Info Reservation ID, size, box name, box number, box mode, rental period, notes
Payment Amount and payment status (paid / unpaid)
Access Code PIN code and expiry (shown only when issued)
Cancellation Info Cancellation date/time and reason (shown only for cancelled orders)
Timestamps Created at, updated at

Cancelling an Order

The Cancel button appears for orders that are not yet "Completed" or "Cancelled".

  1. Click Cancel
  2. A confirmation dialog appears
  3. Click Cancel Order to confirm — this action cannot be undone

Setup Guide (Step by Step)

Step 1: Create a locker config

From Locker Config, click New Locker Config. Enter a config name, currency, and timezone.

Step 2: Connect a KEYVOX device and define sizes

Using KEYVOX auto-fetch (recommended):

  1. Click Fetch Devices to load your registered KEYVOX locker devices
  2. Select the device from the dropdown — box sizes and numbers populate automatically
  3. Enter the long-term daily rate and one-time daily rate for each size row

Using manual entry (if KEYVOX is not connected):

  1. Click Switch to Manual Entry
  2. For each size, enter the size preset, display name, both daily rates, and KEYVOX unit IDs
  3. Click Add Size if you need additional size rows

Step 3: Share the URL with guests

After saving, the share URL is generated. Click Copy URL and share it with guests via email, your website, or a QR code.

FAQ

Q: How is the rental price calculated?

The total is the number of rental days multiplied by the daily rate for the selected box mode. If the guest chooses one-time deposit mode, the one-time daily rate applies; if they choose long-term mode, the long-term daily rate applies.

Q: What is the difference between one-time deposit and long-term modes?

Mode Access Use Case Rate Applied
One-time deposit (mode 1) Single open/close only Short-term luggage drop One-time daily rate × days
Long-term (mode 2) Unlimited during rental period Multi-day storage Long-term daily rate × days

Guests select their preferred mode in Step 2 of the booking flow.

Q: When is the PIN code issued?

The PIN is issued automatically after the guest completes the booking and payment is confirmed. You can view it on the order detail page under "Access Code".

Q: How long is the PIN valid?

The access code expiry is shown in the "Access Code" section of the order detail. It is normally set to the end of the rental period.

Q: What happens if I disable a locker config?

Disabling a config prevents new bookings via that URL. Existing orders are not affected.

Q: Does cancelling an order trigger a refund?

Cancelling only changes the order status to "Cancelled". Refunds must be processed separately through your payment provider.

Q: Can I define multiple sizes in one config?

Yes. A single locker config supports multiple size rows (S, M, L, etc.). Guests choose their preferred size during booking.

Q: The KEYVOX device fetch returns an error

Verify that your KEYVOX API key is configured under Base Settings → KEYVOX Integration. If the API key is correct, you can still use Switch to Manual Entry to complete the setup.

Q: Guests cannot see the locker or complete a booking

Check the following:

  1. The locker config is set to Active
  2. KEYVOX Unit IDs are correctly entered (manual mode) or a KEYVOX device has been selected
  3. The URL shared with guests contains the correct configId
  4. Available box count for the selected size is not zero

Last updated: 2026-03-31 - Added KEYVOX device auto-fetch, box mode (one-time deposit / long-term), and dual-rate pricing setup