Lockii Browse API

Use these endpoints to build your own booking flow. To use them you will just need to supply a valid company ID.

Base URL: the Lockii base URL is https://dash.lockii.app/api

Looking to implement Lockii onto your site? you should use the Lockii Prebuilt components, the Lockii browse API is only recommended for specific use cases and engineers

Flow Overview

1. GET products — List products with locations (and optional availability/price when a date range is given).

2. GET locations — List locations for the company.

3. POST availability — Check if a cart is available for a time range and get prices.

4. GET time-slots — List availability samples for a product/location.

5. POST checkout — Create an order and redirect the customer to Lockii checkout.

Products with Publicly Viewable turned off in the back office are excluded from all browse endpoints.

Endpoints

1. Get Products

GET {baseUrl}/v1/browse/products

Query Param

Required

Description

company_id

Yes

Company ID (e.g. company_xxxxx or xxxxx)

start_time

No

Window start (Unix ms, UTC). Must be used with end_time.

end_time

No

Window end (Unix ms, UTC). Must be used with start_time.

If both start_time and end_time are provided, each product's locations include hasAvailability and each product can include priceInCents and priceFormatted for that window.

Only products visible on customer browse pages are returned. Products with Publicly Viewable turned off in the product editor are omitted.

Example:
GET {baseUrl}/v1/browse/products?company_id=company_abc123

Response:

{ "products": [ { "id": "product_xxx", "name": "Product Name", "description": "…", "category": "Category Name", "locations": [ { "id": "location_xxx", "name": "Location Name", "hasAvailability": true } ], "priceInCents": 5000, "priceFormatted": "$50.00" } ] }

2. Get Locations

GET {baseUrl}/v1/browse/locations

Query Param

Required

Description

company_id

Yes

Company ID

archived

No

true = only archived; omitted = only active.

Example:
GET {baseUrl}/v1/browse/locations?company_id=company_abc123

Response:

{ "locations": [ { "id": "location_xxx", "name": "Location Name", "archived": false, … } ] }

3. Check Availability

POST {baseUrl}/v1/browse/availability
Content-Type: application/json

Body:

{ "company_id": "company_xxx", "location_id": "location_xxx", "start_time": 1711270800000, "end_time": 1711357200000, "cart": [ { "product_id": "product_xxx", "quantity": 2 } ] }

Field

Type

Description

company_id

string

Required. Company ID.

location_id

string

Required. Pickup/return location.

start_time

number

Required. Window start (Unix ms, UTC).

end_time

number

Required. Window end (Unix ms, UTC).

cart

array

Required. Each item: product_id, quantity.

Requests that include a hidden product return an error.

Response:

{ "available": true, "total_price_cents": 12345, "lines": [ { "product_id": "product_xxx", "quantity": 2, "unit_period_price_cents": 5000, "line_subtotal_cents": 10000 } ] }

total_price_cents includes tax and matches Lockii's pricing rules.

4. Get Time Slots

GET {baseUrl}/v1/browse/time-slots

Query Param

Required

Description

company_id

Yes

Company ID

product_id

Yes

Product ID

location_id

Yes

Location ID

start_time

Yes

Window start (Unix ms, UTC)

end_time

Yes

Window end (Unix ms, UTC)

interval

No

15m (default) or day

Limits: end_time - start_time

• interval=15m → ≤ 48 hours

• interval=day → ≤ 7 days

Hidden products return a not-found error.

Example:
GET {baseUrl}/v1/browse/time-slots?company_id=company_abc123&product_id=product_xxx&location_id=location_xxx&start_time=1711270800000&end_time=1711357200000&interval=15m

Response:

{ "slots": [ { "start_ms": 1711270800000, "available_count": 2 } ] }

slots are sorted by start_ms. available_count is the number of units available at each slot.

5. Create Checkout

POST {baseUrl}/customer/checkout
Content-Type: application/json

Creates an order and returns the payload needed to redirect the customer to Lockii checkout. No authentication required.

Body:

{ "lineItems": [{ "productID": "product_xxx", "quantity": 2 }], "locationId": "location_xxx", "fromDate": "2025-03-24T10:00:00.000Z", "toDate": "2025-03-25T10:00:00.000Z", "companyId": "company_xxx" }

Field

Type

Description

lineItems

array

Each: productID, quantity

locationId

string

Pickup/return location

fromDate

string

Start date/time, ISO 8601

toDate

string

End date/time, ISO 8601

companyId

string

Company ID

stockId

string (optional)

Only for single-item bookings; specific unit to book

Response: Order payload, including id (public order id).

Redirect:
https://book.lockii.app/{company_slug}/checkout?order={id}

Example: if companyId is company_abc123 and id is pio_xyz, then
https://book.lockii.app/abc123/checkout?order=pio_xyz.

Errors

Status

Meaning

400

Invalid parameters or availability check failed

404

Company not found (invalid id or inactive)

500

Server error

Error format:

{ "error": "Bad request", "message": "company_id is required" }

Time Handling

• All API timestamps are Unix milliseconds (UTC).

• Convert to local time for display.

• Use ISO 8601 strings for checkout fromDate and toDate.