Sessions

A session is a usage record that tracks a device interaction from reservation through active use to completion. Sessions are the backbone of Bikeep’s billing, analytics, and user history — every time a user books or locks a device, a session captures the full lifecycle.

Authentication requirement: Session tracking requires the External Users authentication method. The S2S OAuth2 method does not create sessions.

Session Types

Sessions track parking and storage interactions. A session is created automatically when a device command (lock, book) is issued via the External Users authentication method. Session type is device — set automatically based on the device involved (LOCKER, BIKE_DOCK, SCOOTER_DOCK).

Session Statuses

Every session moves through a defined set of statuses:

Status Meaning How It’s Reached
pending Session created, awaiting user action Internal initialization (not typically seen via API)
booked Device reserved for the user book command sent
active Device is in use — locked with user’s item lock command
ended Session complete unlock command or forced end

Lifecycle Diagram

stateDiagram-v2
    [*] --> pending

    pending --> booked : book
    pending --> active : lock (direct)

    booked --> active : lock

    active --> ended : unlock / forced end

    class pending available
    class booked reserved
    class active active
    class ended ended

A session can skip the booked status entirely — if a user locks a device without booking first, the session goes directly from pending to active.

Session Events

Sessions record key moments as events. Each event has a name, timestamp, and optionally a location reference.

Event When It Occurs
book Device is reserved
start Session becomes active (device locked)
end Session completes (device unlocked)

Timestamp Fields

Sessions include dedicated timestamp fields for integration logic:

Field Description
booked_time When the booking was created (RFC 3339)
booked_until_time When the booking expires — the reservation deadline (RFC 3339)
start_time When the session became active — device locked (RFC 3339)
end_time When the session ended — device unlocked (RFC 3339)

These fields are null when the corresponding event hasn’t occurred yet (e.g., start_time is null while the session is still in booked status).

Note: The v2 Session model also includes pause and resume events for micromobility rental sessions. These are not relevant for parking/storage integrations — you can safely ignore them.

Payment

Sessions track fees and payment status. The fee object contains the calculated amount and currency, while payment.status tracks the payment lifecycle:

Payment Status Description
PENDING Fee calculated, payment not yet authorized
PAID Payment completed successfully
NEEDS_APPROVAL Payment requires manual approval
APPROVED Payment approved
CANCELED Payment canceled / not approved
PAYMENT_FAILED Payment attempt failed
REFUNDED Payment was refunded to the user
REFUND_FAILED Refund attempt failed
NOT_CHARGED Session will not be charged (see Billing Rules)

Billing Rules

Not every session incurs a charge. A session is chargeable only when all of these conditions are met:

  1. A price list is configured for the location/fleet (this is done by Bikeep)
  2. The user is identified — anonymous sessions / RFID-only sessions (where the user is identified only by their card, not a user account) are not charged
  3. The session is not short — sessions shorter than 1 minute (measured from start to end, or booked to end) are considered accidental and are not billed

When a session is not chargeable, its payment status is set to NOT_CHARGED.

Rating

Sessions support user feedback through a rating system. After a session ends, the user can submit:

Field Description
rating A rating value (string)
comment Free-text feedback from the user

Querying Sessions

The session API provides endpoints for retrieving session data:

  • List sessions: GET /session/v2/sessions — query by user, location, time range, or status
  • Get single session: GET /session/v2/users/{user_id}/sessions/{session_id} — retrieve a single session

Query parameters

The list endpoint supports filtering:

Parameter Type Description
user_id UUID Filter by user
location_id UUID Filter by location
status string Filter by session status (active, ended, or booked)
from YYYY-MM-DD Start of time range
to YYYY-MM-DD End of time range
limit integer Max results per page
pagination_token string Cursor for next page

See the Session API Reference for full endpoint documentation.

v1 vs v2: The v2 session endpoints (shown above) use cursor-based pagination and are recommended for new integrations.

Important Notes

  • Forced end: Operators can force-end a session via the Bikeep Console (e.g., for maintenance or support). The without_fee flag controls billing — when set to true, the session’s payment status is set to NOT_CHARGED.
  • Pending session TTL: Sessions in pending status expire after 30 days. Active sessions are retained for 2 years.
  • Session events are immutable — once recorded, events cannot be modified. The session status is derived from which events have been recorded.