Sessions and tariffs

A session is one vehicle's stay in a zone, from entry to exit. Tariffs decide which vehicles an LPR camera lets in when they aren't on the whitelist, and how the stay is priced. This guide covers reading and managing sessions, and setting up tariffs, members and groups.

Prerequisites

An API token; see Authentication.
For automatic sessions: LPR cameras assigned to zones, on the way in and the way out.

How sessions start and end

Event	Session	`entry.type` / `exit.type`
A camera lets a vehicle in (whitelist or tariff)	Starts	`lpr_camera`
You create one with `POST /v2/sessions`	Starts	`account` (API token) or `attendant` (user)
A camera sees the vehicle leave	Ends; `possibly_exited` becomes `true`	`lpr_camera`
You close it with `POST /v2/sessions/{id}/close`	Ends	`account` or `attendant`

Payment machines also create and close sessions, and record payments in amount_paid.

Session fields you'll use most:

Field	Meaning
`public_id`	A 10-character code, A–Z and 0–9, for showing to the driver. Filterable.
`duration`	Seconds so far, or the full stay once ended.
`ended_at`	When it ended; absent or `null` while open.
`exit_allowed`	`true` while the session is open.
`discount_time`	Free minutes granted, or `-1` for unlimited.
`amount_paid`	What was paid at a payment machine. Read-only.
`entry_license_plate`	The plate read on entry.

1. Follow sessions

In realtime, session_create and session_update carry the whole session; see Events. Over REST, GET /v2/sessions filters by lot_id, zone_id, license_plate, public_id, lpr_camera_id, created_at and ended_at:

Open sessions in lot 7
curl -s "https://api.parklio.com/v2/sessions?filter=lot_id:eq:7&filter=ended_at:eq:null&sort=created_at:desc" \
  -H "Authorization: Bearer $PARKLIO_API_TOKEN"

For reports, GET /v2/sessions/export returns a CSV, GET /v2/sessions/analytics counts entries and exits (or the peak hour) per lot or zone, and GET /v2/sessions/vehicle-analytics gives visits and time spent per plate.

2. Create and change sessions

Create a session for a vehicle a camera missed, or one you let in by hand. Name the camera: the session is created in that camera's zone.

Start a session
curl -s -X POST https://api.parklio.com/v2/sessions \
  -H "Authorization: Bearer $PARKLIO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"license_plate": "ZG1234AB", "lpr_camera_id": 15}'

Always send both license_plate and lpr_camera_id.
No whitelist, tariff or capacity check is made, and the zone's occupied_count doesn't change.

Grant free time, or fix a misread plate, with PATCH /v2/sessions/{id}:

Grant 60 free minutes
{ "discount_time": 60 }

discount_time is in minutes; -1 means unlimited. A value of 0 is ignored. To correct the entry plate, send license_plate instead.

End a session with POST /v2/sessions/{id}/close (no body). Close only open sessions (check ended_at first): closing doesn't check whether the session already ended, and doesn't change the zone's occupied_count.

3. Set up tariffs

A tariff is a set of rules for a zone: when it applies, who it applies to, and how the stay is priced. Create one with POST /v2/tariffs; only name is required:

Weekday tariff, 2 per hour after 15 free minutes
curl -s -X POST https://api.parklio.com/v2/tariffs \
  -H "Authorization: Bearer $PARKLIO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekdays",
    "interval": 60,
    "price": 2,
    "entry_free_time_interval": 15,
    "price_progression_type": "flat",
    "schedules": [
      { "weekday": 0, "start_time": "07:00:00", "end_time": "19:00:00" },
      { "weekday": 1, "start_time": "07:00:00", "end_time": "19:00:00" },
      { "weekday": 2, "start_time": "07:00:00", "end_time": "19:00:00" },
      { "weekday": 3, "start_time": "07:00:00", "end_time": "19:00:00" },
      { "weekday": 4, "start_time": "07:00:00", "end_time": "19:00:00" }
    ]
  }'

Field	Meaning
`interval`, `price`	Price per interval of minutes (at least 15; default 60).
`price_progression_type`	`flat` (default), `linear`, `exponential` or `incremental`.
`entry_free_time_interval`, `exit_free_time_interval`, `gratis_time`	Free minutes.
`maxima`, `max_time_of_stay`	Maximum price, maximum stay in minutes.
`schedules`	Up to 7 `{weekday, start_time, end_time}`; `weekday` 0 is Monday. Times are in the lot's time zone.
`start_time`, `end_time`	Absolute dates the tariff is valid between.
`season_start`, `season_end`	A yearly season (`YYYY-MM-DD`; only day and month count).
`group_ids`, `max_affected_members_per_group`	Limit the tariff to groups, and how many of a group's members can be inside at once.
`currency_id`	Defaults to EUR.

Then assign the tariff to a zone with PUT /v2/zones/{id}/tariffs/{tariffId}. A zone can have several tariffs; their order is set with PATCH /v2/zones/{zone_id}/tariffs/{tariff_id} and {"order": 0}. A tariff can't be deleted while a zone still uses it (code 1400).

The API doesn't calculate prices; payment machines do, from these rules.

4. Members and groups

To restrict a tariff to known vehicles, register their plates as members (POST /v2/members, or a CSV upload), put them in a group (POST /v2/groups), and give the tariff that group's id in group_ids. A tariff with no groups applies to every vehicle.

Members and groups don't open anything by themselves; they only decide which tariffs apply. For access that doesn't depend on tariffs, use the whitelist.

How a camera decides on entry

For a plate that isn't on the lot's whitelist:

Find the zone's tariffs that apply now (dates, season, schedule) and to this plate (no groups, or a group the plate is a member of).
None: denied, reason no_tariff.
If every one of them is full (its group already has max_affected_members_per_group members with open sessions): denied, reason max_capacity.
Otherwise: let in, reason tariff, and a session starts.

On the way out, a vehicle with an open session is let out (session_exit) and its session ends; one without is denied (no_active_session). The zone's occupied_count isn't part of the decision.

Verify it worked

Create a tariff for a zone with a schedule covering now, and no groups.
Drive in past the zone's entry camera: plate_reading_update shows access_decision: "triggered", reason tariff, and session_create arrives.
GET /v2/sessions?filter=public_id:eq:<public_id> returns the session, with no ended_at.
Drive out: session_update arrives with ended_at set and exit.type lpr_camera.

Common errors

Symptom	Cause	Fix
Reason `no_tariff`	No tariff applies now, or none matches the plate's groups.	Check the zone's tariffs, schedules (Monday = 0, lot time) and groups.
Reason `max_capacity`	Every applicable tariff's group is full.	Raise `max_affected_members_per_group`, or close stale sessions.
Reason `no_active_session` on exit	The entry wasn't recorded as a session.	Create the session by hand, or check the entry camera.
`discount_time: 0` has no effect	`0` is ignored.	Not supported today.
`1400` when deleting a tariff	A zone still uses it.	Unassign it from its zones first.
`1505` when correcting a plate	The session has no entry plate.	Not possible for that session.

View as Markdown

Prerequisites​

How sessions start and end​

1. Follow sessions​

2. Create and change sessions​

3. Set up tariffs​

4. Members and groups​

How a camera decides on entry​

Verify it worked​

Common errors​

Next​