<!-- https://unlockos.io/manual/checkin-setup-guide -->

# Check-in Setup Guide (from zero to live operation)

This guide is **the scenario-style manual you should read first**. If you're setting up check-in (same-day self-entry / walk-in reception) for the first time, work through this page from top to bottom.

> **About the design philosophy:** UnlockOS check-in bundles "pricing plan × smart lock × payment timing × occupancy" into a single **check-in configuration**, and launches that configuration from a **URL (a QR code at the front desk / a kiosk / the SpaceCard in the member app / the Go Portal)**. From **walk-ins** that never go through a reservation, all the way to reservation and member self-check-in, the same check-in configuration is the foundation. The steps in this guide are built on that premise.

---

## The Whole Picture (8 Steps)

To start accepting check-ins, configure things roughly in the following order. Most steps depend on the ones before them, so we strongly recommend **going through them in numeric order**.

```
[1] KEYVOX integration ─────┐
[2] Base settings (Slug / Lock assignment)
                            │
[3] Plans ──────────────────┼──→ [4] Check-in Config ──→ [8] Test check-in
                            │         ├ Key settings (entry/exit) │
                            │         ├ Key display type           │
                            │         ├ Payment timing             │
                            │         └ Occupancy management       │
                            │                                      │
[5] Check-in Form (optional) ─────────────────────────────────────┤
[6] Check-in URL / kiosk setup ───────────────────────────────────┤
[7] Integration reservation form config (optional) ───────────────┘
```

| # | Step | Required / Optional | Time | Depends on |
|---|------|---------------------|------|------------|
| 1 | KEYVOX integration | Required (if you issue keys) | 5 min | — |
| 2 | Base settings (Slug / Rooms & Lock assignment) | Required (if you issue keys) | 20–40 min | 1 (lock assignment only) |
| 3 | Plans | Required | 10–30 min | — |
| 4 | Create the check-in configuration | Required | 15 min | 1, 3 |
| 5 | Check-in Form | Optional | 10 min | 4 |
| 6 | Check-in URL / kiosk setup | Required | 10 min | 4 |
| 7 | Form setup for integration reservations (iCal / Google Calendar / PMS) | Optional | 10 min | 4, 5 |
| 8 | Test check-in | Required | 10 min | 1–4 (and optionally 5, 6, 7) |

**Total estimate: 70 minutes to 2 hours** (varies with scale)

---

## Step 1: KEYVOX integration

### Purpose

Let UnlockOS operate the smart locks at your facility. This enables **automatic key issuance** (QR / PIN / Remote unlock) at check-in.

> Check-ins that don't issue keys (reception only / pricing calculation only) can skip this step. In that case, you can also skip the "lock assignment" in step 2, and the check-in configuration enters "keyless check-in" mode.

### Prerequisites

- A KEYVOX account
- In the KEYVOX dashboard, the target facility's places (Place) and doors are registered, and lock devices are bound to them

### Steps

1. Open **App Integrations** from the main app's left menu
2. From the tabs at the top, select **KEYVOX**
3. Click **Sign in with KEYVOX** and complete OAuth authentication
4. After authentication, confirm that registered lock devices appear, grouped by place (Place)

### Verify

- The **KEYVOX Lock System** card shows the **"Connected"** label
- Each door has a **UnitID** assigned

### Details

- [Lock Connection help](lock-connection.md)

---

## Step 2: Base settings (Slug / Rooms & Lock assignment)

### Purpose

Set the facility's Slug (URL identifier) so that KEYVOX locks can be selected in a check-in configuration.

> The **Slug** is the base for the check-in URL (`checkin.unlockos.io/{slug}`) and the Go Portal (`go.unlockos.io/{slug}`). Even facilities that don't issue keys should set a Slug, so they can distribute URLs.

### Prerequisites

- Setting the Slug has no prerequisites
- Lock assignment requires step 1 (KEYVOX integration) to be complete

### Steps

1. Open **Base Settings** from the main app menu
2. On the **Facility Basics** tab, enter your desired Slug in the **App URLs** field (lowercase letters, digits, hyphens, 3 characters or more). A green checkmark (✓) means it's available. **Save**
3. If you issue keys per room, register rooms on the **Rooms** tab (**Room Types** / **Rooms list**), then bind a KEYVOX lock to each room in the **Lock Assignment** sub-tab

> **The difference between a check-in configuration's "Entrance Unit" and a room's "Lock Assignment":** The **Entrance Unit** you pick in a check-in configuration is the shared key used for **walk-in (same-day) check-ins** made with that configuration. Reservation guests (including integration reservations) instead receive the key for the **room their reservation is assigned to**. See the note in step 4 for details.

### Verify

- Below the Slug input, an **App URL list panel** appears (`checkin.unlockos.io/{slug}` / `go.unlockos.io/{slug}` + QR code)
- If you issue locks, each room's status shows **"Assigned"**

### Details

- [Base Settings help](base-settings.md) / [Lock Connection help](lock-connection.md)

---

## Step 3: Create Plans

### Purpose

Create the **pricing plans** to link to a check-in configuration. For check-in, in addition to bookable plans (Hourly / Accommodation / TimeSlot), you can also use in-facility-billing-only plans (Daily flat / Fixed + overtime / One-time).

### Prerequisites

- For paid use, Stripe integration must be complete ([Lock Connection (Stripe)](lock-connection.md#stripe-payment-tab))
- No prerequisites for free use (no payment)

### Steps

1. **Plan List** → **Plans** tab from the main app's left menu
2. Click **New** in the top-right
3. Enter plan name, description, plan type, and price
4. Check the price calculation in the **Simulation** panel on the right
5. **Save**

> **About day-specific and holiday rates:** Daily flat / Fixed + overtime / One-time plans each let you set rates on Weekday / Weekend / Holiday tabs, and **holidays are detected automatically from the facility's country** (facilities with no country configured never detect holidays).
>
> The day type behind the initial amount quoted and charged at check-in (deposit / entry fee) is resolved from **the civil date in the facility's timezone**. It previously came from server time (UTC), so check-ins during Japanese late night / early morning (roughly 00:00–09:00 JST) were classified under the previous day. **Facilities with frequent late-night entries, or with a Holiday tab configured, will see different charges.** See [Price Plan Settings — How Day-of-Week and Holiday Rates Are Chosen](plan-form.md).

### Verify

- The created plan appears in the Plan List with a type badge

### Details

- [Plan List help](plan-list.md) / [Plan Form help](plan-form.md)
- If you want guests to choose among multiple plans: [Plan Group](plan-group-form.md)

> **Design tip:** Use a **Plan Group** if you want guests to choose a plan, or an **Individual Plan** if you want a single fixed plan (chosen in step 4).

---

## Step 4: Create the check-in configuration

### Purpose

Bundle pricing plan, smart lock, payment timing, and occupancy into **a single check-in configuration**. This is **the central step of this guide**.

### Prerequisites

- A plan created in step 3
- Step 1 (KEYVOX integration) complete if you issue keys

### Steps

1. Open **Check-in List** from the main app's left menu
2. Click **New** in the top-right
3. **Basic info**: Enter check-in configuration name, description, and currency
4. **Plan settings**: Choose the Plan Selection Type (**Individual Plan** / **Plan Group**), then select the plan (or group) to apply
5. **Lock settings**: Select the **Entrance Unit** / **Exit Unit** (see "4-1" below)
6. **Key display type**: Choose from QR / PIN / Unlock Button (see "4-2" below)
7. **Payment settings**: Set payment timing and deposit (see "4-3" below)
8. **Occupancy management**: Set maximum capacity, congestion display, etc. (see "4-4" below)
9. **Save**

After creation, a check-in ID (`ic-xxxxxxxx`) is assigned.

### 4-1. Lock settings (Entrance / Exit Unit)

- Leaving **both** entrance and exit blank automatically enters **"keyless check-in"** mode (no key UI is shown, pricing calculation only).
- Once **either** the entrance or exit is selected, at least one key display type becomes required.

> **Note — integration reservations (iCal / Google Calendar / Site Controller):** The Entrance/Exit Unit set here does **not** apply to integration reservations imported from a calendar or site controller. Those guests always receive the key for the **room their reservation is assigned to** (the room's own lock), issued ahead of time. This Unit setting only affects **walk-in (same-day) check-ins** made directly with this check-in configuration.

### 4-2. Key display types

| Type | Description |
|------|-------------|
| **QR Code** | Display a QR code on the guest's smartphone to unlock the door |
| **PIN Code** | Display a numeric PIN code to unlock the door |
| **Unlock Button (Remote Unlock)** | Tap a button to unlock remotely (available only when the unit has a lock device linked) |

- When you select a lock for the first time, "QR Code" is set automatically.
- If "Unlock Button" is grayed out, link a lock device to the relevant unit in **App Integrations**.

### 4-3. Payment settings

| Option | Description |
|--------|-------------|
| **Postpaid** | Pay at checkout |
| **Prepaid** | Pay full amount at check-in |
| **Prepaid + Postpaid** | Pay deposit upfront, settle remaining at checkout |
| **No Payment** | No charges (free use, etc.) |

- You can also set a **Deposit** and a **Prepaid Display Amount** (if you want to display an amount different from the deposit).
- For hourly billing plans, you can set the **Billing Unit** (15 / 30 / 60 minutes) and the **Rounding Method** (Round Up / Round Down / Round to Nearest).

### 4-4. Occupancy management

| Field | Description |
|-------|-------------|
| **Maximum Capacity** | Maximum number of simultaneous users (1–999) |
| **Congestion Reset Time** | Time when the count resets |
| **Display congestion rate** | Show guests the current congestion |
| **Block new check-ins when at full capacity** | Block new check-ins when the max is reached |

> **Note:** The congestion rate is **aggregated at the check-in configuration level**. If you bundle physically separated spaces (Men's / Women's Sauna, Building A / Building B, etc.) into one plan group, the congestion rate becomes misleading. For separate physical spaces, create **separate check-in configurations**.

### Verify

- The created configuration appears in the Check-in List with a check-in ID (`ic-xxxxxxxx`) assigned
- Plan, entrance/exit key, payment, currency, and deposit are as intended

### Details

- [Check-in Configuration help](checkin-config-form.md) / [Check-in List help](checkin-list.md)
- [Access Key Display (QR, PIN & Remote Unlock)](key-display.md)

---

## Step 5: Check-in Form (optional)

### Purpose

Attach a form that collects **guest information** (name, address, nationality, ID documents, etc.) at check-in.

> Forms are not required for check-in. Only set one up if you need it.

### Prerequisites

- A check-in configuration created in step 4
- The form itself is created on the **Forms** page ([Form Management](forms.md))

### Steps (attaching a form to the default check-in configuration)

1. **Reservation Management** → **Check-in** tab → check-in configuration list
2. In the config card with the **Default** badge, select a form from the **Check-in Form** picker and save
3. To change the default, click **Set as Default** on another card (the picker moves with it)

> **The form picker only appears on the "default" check-in configuration.**

### Form priority (important)

| Reservation source | Form used |
|--------------------|-----------|
| Online booking (Booking) | The form attached to that plan |
| Manual reservation (created in Reservation Management > Check-in) | Default check-in configuration form |
| iCal / Google Calendar / Site Controller integration | The form set on that integration source |
| None of the above configured | Default check-in configuration form (final fallback) |

### Difference in display timing

| Check-in path | When the form appears | Form used |
|---------------|-----------------------|-----------|
| Self-check-in via Booking / Go app | At booking (just before payment) | Form attached to the plan |
| Host check-in URL / kiosk (checkin-host) | At check-in | Default check-in configuration form (or the integration source's form) |

> **Common misconception:** "A form appears at booking for one plan but at check-in for another" is not a bug. It reflects whether the plan has a form attached. If you want the form to appear both at booking and at check-in, attach a form to each plan.

### Details

- [Check-in Configuration (Check-in Form settings)](checkin-config-form.md#check-in-form-settings)
- [Form Management](forms.md)

---

## Step 6: Check-in URL / kiosk setup

### Purpose

Turn the check-in configuration you created into a **URL** that guests can launch. There are multiple ways to distribute it: a QR code at the front desk, a tablet kiosk, the SpaceCard in the member app, the Go Portal, and so on.

### Prerequisites

- A check-in configuration created in step 4
- Slug set (step 2)

### Main distribution methods

| Distribution method | Description |
|---------------------|-------------|
| **Check-in app URL** | `checkin.unlockos.io/{slug}` — distributed via a front-desk QR or link. The basis of walk-in reception |
| **Kiosk (checkin-host)** | Set up a tablet permanently at reception so visitors operate it themselves |
| **Go Portal** | `go.unlockos.io/{slug}` — guides guests to booking, membership, and check-in in one place. The "Walk-in" tab forwards to check-in |
| **SpaceCard in the member app** | Members check in from the member app home (when membership is configured) |
| **Check-in ID (`ic-xxxxxxxx`)** | Used for URL generation in Unlock Lab, API integration, and embedded snippets |

### Steps

1. In **Check-in List**, copy the check-in URL from the link icon on the relevant configuration
2. If needed, generate a custom URL or embedded snippet in **Unlock Lab**
3. Post the QR code / link at reception, on your own site, and on the Go Portal

### Verify

- Opening the copied check-in URL in a browser launches the check-in flow

### Details

- [Unlock Lab (URL/Snippet Generation)](unlock-lab.md)
- [Go Portal & Service Linking Guide](go-linking-guide.md)

---

## Step 7: Form setup for integration reservations (optional)

### Purpose

Show a form at check-in to guests from **integration reservations** imported from iCal (Airbnb, etc.) / Google Calendar / Site Controller (PMS).

> Facilities that don't handle integration reservations can skip this step.

### Steps

- In the **Check-in URL** section of the **Check-in** tab, set the **applied form** individually for each integration source (iCal / Google Calendar / Site Controller).
- The form you set is shown when guests from that source check in via the check-in URL or kiosk.

### Verify

- You can select and save an applied form per integration source

### Details

- [Check-in Configuration (booking forms for iCal / Google Calendar integrations)](checkin-config-form.md#q-can-ical--google-calendar--site-controller-reservations-also-prompt-a-form)
- [iCal integration help](ical-config.md) / [Google Calendar integration](google-calendar-integration.md)

---

## Step 8: Test check-in

### Purpose

Run one check-in end-to-end as a guest to confirm the whole configuration works correctly.

### Prerequisites

- Steps 1–4 complete
- Optionally steps 5, 6, 7 as well

### Steps

1. Open the check-in URL copied in step 6 (`checkin.unlockos.io/{slug}` or the kiosk) in a fresh browser window (incognito preferred)
2. Select a plan (or choose one from the plan group) and the number of people, etc.
3. Fill in the form if there is one
4. If there's a payment, pay with the Stripe **test card** (`4242 4242 4242 4242` / any future date / any CVC)
5. After the check-in is confirmed, verify that the **access code (key)** is displayed (for configurations that issue keys)
6. Confirm you can enter using the displayed QR / PIN / Unlock Button
7. Confirm a new entry appears in **Check-in History**

### Verify

| Item | How |
|------|-----|
| The check-in screen displays correctly | Open the check-in URL |
| (Paid) Payment goes through | Payment completes with the test card |
| A key is issued | Access code screen (configurations that issue keys only) |
| It's the lock for the correct room / door | Compare the issued key against the lock assignment |
| An entry appears in history | Check-in History |
| Occupancy is counted | Congestion display (when enabled) |

### After testing

- Check out the test check-in if needed
- Before going live, re-confirm the check-in URL / kiosk / Go Portal paths you distribute
- If you switch to live mode, reconfigure the Stripe integration in live mode

---

## Setup Completion Checklist

Once everything is checked, you're ready to go live.

### Required

- [ ] KEYVOX integration shows "Connected" (facilities that issue keys only)
- [ ] Slug set, and `checkin.unlockos.io/{slug}` is issued
- [ ] Every room has a lock assigned (facilities that issue keys per room only)
- [ ] At least one plan created
- [ ] At least one check-in configuration created, with a check-in ID (`ic-xxxxxxxx`) assigned
- [ ] Test check-in succeeded and a key was issued (facilities that issue keys only)

### Optional

- [ ] Check-in form set up
- [ ] Kiosk (checkin-host) set up
- [ ] Forms for integration reservations (iCal / Google Calendar / PMS) set up
- [ ] Paths from the Go Portal / member app SpaceCard confirmed

---

## Common stumbles

### Q: All key display types are grayed out and I can't select any

Leaving **both** the entrance and exit units blank makes it a "keyless check-in," so no key types can be selected. Check that a unit is selected.

### Q: Only "Unlock Button (Remote Unlock)" can't be selected

The selected unit has no lock device (device ID) linked. Link a lock device to the relevant unit in **App Integrations**, then try again.

### Q: Guests from integration reservations (Airbnb, etc.) don't get the key for the check-in configuration's entrance unit

This is expected. Integration reservations are issued the key for the **room the reservation is assigned to**. The check-in configuration's entrance unit is only for walk-in (same-day) check-ins.

### Q: I set a form on the default check-in configuration, but it doesn't appear for guests who booked through Booking

This is expected. Guests who self-check-in through Booking see the **form attached to the plan** at booking time (just before payment). The default check-in configuration form is shown when checking in via a kiosk / check-in URL. If you want it to appear in both, attach a form to each plan as well.

### Q: Does deleting a check-in configuration also delete the history?

No, past check-in history is retained. However, you can no longer check in using the deleted configuration.

### Q: The congestion rate doesn't match reality

The congestion rate is **aggregated at the check-in configuration level**. If you bundle physically separated spaces into one configuration, create a separate check-in configuration for each space.

---

## Support

If you've followed this guide in order and still can't resolve the issue, contact support with **which step** and **what's happening** (attach a screenshot of the error message if you have one).

---

## Related pages

### Per-step details
- Step 1: [Lock Connection (KEYVOX)](lock-connection.md)
- Step 2: [Base Settings](base-settings.md)
- Step 3: [Plan List](plan-list.md) / [Plan Form](plan-form.md) / [Plan Group](plan-group-form.md)
- Step 4: [Check-in Configuration](checkin-config-form.md) / [Check-in List](checkin-list.md) / [Access Key Display](key-display.md)
- Step 5: [Form Management](forms.md)
- Step 6: [Unlock Lab](unlock-lab.md) / [Go Portal & Service Linking](go-linking-guide.md)
- Step 7: [iCal integration](ical-config.md) / [Google Calendar integration](google-calendar-integration.md)
- Step 8: [Check-in History](checkin-history.md) / [Guest Check-in](guest-checkin.md)

### Related topics
- [Booking Setup Guide](booking-setup-guide.md)
- [Membership Setup Guide](membership-setup-guide.md)
- [Go Portal & Service Linking Guide](go-linking-guide.md)
- [Quick Mode](quick-mode.md)