Delivery Locker Settings

Overview

Delivery Locker Settings is the admin interface for configuring a KEYVOX delivery locker for your facility. You define the billing plan (free tier, paid tier, or both), set pricing and usage limits, and connect the KEYVOX locker device. Once saved, the system generates an API key used by the webhook to process incoming package deposits automatically.

From the Delivery Management page, select the Locker tab to access these settings.

Setup Guide (Step by Step)

Step 1: Select a Plan Type

Choose the billing plan that applies to your residents.

Plan Type Description
Storage Days Charge is calculated based on the number of days a package is stored in the locker
Usage Count Charge is calculated based on the number of pickups per month
Both Apply storage-day fees AND usage-count limits simultaneously

If you are unsure which plan to use, start with Storage Days — it is the most common configuration for apartment buildings.

Step 2: Configure Pricing and Limits

After selecting a plan type, configure the corresponding billing parameters.

Storage Days Plan

Field Description
Free Days Number of days storage is free before charges begin. Set to 0 for no free period
Fee Per Day Daily storage fee charged after the free days have elapsed (in your facility's currency)
Monthly Limit Maximum number of free pickups per resident per month. Leave blank for unlimited
Overage Policy What happens when a resident exceeds the monthly limit: Block (prevent new deposits) or Charge (continue to allow deposits and bill the overage)

Usage Count Plan

Field Description
Free Uses Per Month Number of pickups per month that are included at no charge
Fee Per Use Fee charged per pickup after the free allowance is exceeded
Overage Policy Block or Charge when the monthly free usage is exhausted

Warning: Changing the plan type or fee settings after the locker is active will affect how in-progress packages are billed. Existing assignments already created are not retroactively updated.

Step 3: Select a KEYVOX Locker Device

  1. Click Fetch Devices to load all KEYVOX locker units registered to your facility
  2. Select the target locker unit from the dropdown
  3. The selected device's ID is saved and used as the identifier when KEYVOX sends package arrival webhooks

If your KEYVOX device does not appear in the list, verify that your KEYVOX API key is configured under Base Settings → KEYVOX Integration.

Step 4: Save Configuration

Click Save to apply your settings.

After saving, the system generates an API key (webhook secret) used by KEYVOX to authenticate package arrival notifications. This key is used internally — you do not need to share it with residents.

If a webhook secret already exists for this facility, saving the form will rotate it. Notify KEYVOX support if you need to update the registered webhook URL.

Features

Feature 1: Plan Type Selection

The plan type controls how package storage is billed to residents. Select the model that matches your billing agreement with residents.

  • Storage Days: Best for buildings where residents may leave packages for varying durations
  • Usage Count: Best for buildings with a flat monthly allowance (e.g., 5 free pickups/month)
  • Both: Combines both billing axes — a package can be billed both for storage duration and counted against the monthly quota

Feature 2: Free Tier Configuration

Every plan supports a free tier to avoid charging residents for quick pickups.

  • Set Free Days to 1 or 2 so residents who pick up promptly are never billed
  • Set Free Uses Per Month to match any building-wide complimentary allowance
  • Setting both values to 0 means all usage is billable from the first day

Feature 3: KEYVOX Device Integration

The locker device dropdown lists all KEYVOX units registered to your facility. Selecting one links your locker settings to that specific device.

When KEYVOX sends a webhook notification that a package was deposited:

  • The system looks up the locker setting by KEYVOX device ID
  • The target resident is identified from the box/room assignment
  • The system decides whether the deposit is free or billable based on the current plan

Feature 4: API Key Management

The API key (webhook secret) is automatically generated after you save the configuration. It is used to verify that incoming webhook events genuinely originate from KEYVOX.

  • The key is stored securely and never exposed to residents
  • If you suspect the key has been compromised, save the configuration again to rotate it

FAQ

Q: How do I change the plan type after the locker is already active?

You can change the plan type at any time by selecting a new type and clicking Save. The new settings apply to packages deposited after the change. Packages already in storage continue to be billed under the settings that were active when they were deposited (the settings are snapshotted at deposit time).

Q: What happens when a resident's usage exceeds the monthly limit?

Behavior depends on your Overage Policy setting:

Policy Result
Block New deposits for that resident are rejected by the webhook until the next billing cycle
Charge Deposits are still accepted, but the resident is billed at the overage fee rate

Q: Can I set a free period of 0 days to make all storage immediately billable?

Yes. Set Free Days to 0. In this case, residents must pay before unlocking the locker, even for same-day pickups.

Q: Can the locker run without Stripe configured?

The locker can operate in free-tier mode without Stripe. However, if your plan includes paid pickups, Stripe must be configured for residents to complete payment. Without Stripe, packages requiring payment will be blocked at the payment step.

Troubleshooting

KEYVOX device not appearing in the dropdown

  1. Open Base Settings → KEYVOX Integration and verify the API key is saved correctly
  2. Confirm the KEYVOX device is registered and active in the KEYVOX management portal
  3. Click Fetch Devices again after confirming the above

Configuration save failed

  1. Check that all required fields are filled in (plan type must be selected, fee values must be non-negative numbers)
  2. If the KEYVOX device is not connected, you can still save the configuration without selecting a device — package deposits will be rejected until a device is selected
  3. If the error persists, contact support with the error message shown on screen

Residents see "Payment Required" immediately after deposit

This typically means Free Days is set to 0 or Free Uses Per Month is set to 0. Update the free tier settings if you intended to provide a complimentary period.