Livello Open Platform API (1.1.1)

The future of autonomous retail. Livello's intelligent smart kiosks make fresh meals, snacks, beverages, and daily essentials available around the clock, anywhere people live, work, and stay.

With automatic product recognition, real-time inventory tracking, and a 10-second average checkout time, each compact unit (just 1m²) operates autonomously without on-site staff. Our clients manage all their units digitally and stay connected to their units and users 24/7.

Our solutions are deployed across Europe in canteens, offices, hotels, healthcare facilities, and educational institutions. Built and engineered in Germany, Livello's patented technology provides a reliable foundation for autonomous retail operations.

The Open Platform API gives your systems direct, programmatic access to this infrastructure, so you can build integrations that keep your data in sync and your operations running automatically.

→ livello.com

The Open Platform API gives machine-to-machine (M2M) clients access to:

• Kiosk fleet: unit status, configuration, and real-time inventory levels
• Products: product catalog (product meta) with metadata, categories, images, and product management
• Product Lines: pricing management for products assigned to kiosk load cells
• Transactions: purchase session history with line items and payment details
• Refills: restocking session history with item-level detail
• Users: user management (list, create, update)
• Alerts: operational alerts and alert type definitions
• Analytics: sales, transaction KPIs, refill statistics, inventory reports, and temperature telemetry
• Discounts: discount instances, type catalog, priority ordering, resolution preview
• Discount Codes: activation codes for code-gated discounts

The legacy Promocodes API is retired; use Discounts and Discount Codes instead.

All data is automatically scoped to your organization and its sub-organizations.

1. Obtain credentials: request M2M client credentials from Livello (see Client Registration)
2. Request a token: exchange your credentials for a JWT via POST /auth/token (see Authentication)
3. Call endpoints: include the token in every request as Authorization: Bearer <token>
4. Explore resources: start with Kiosks to list your fleet, then check Products for your catalog and Transactions for sales history
5. Monitor operations: use Analytics for dashboards and Alerts for real-time notifications

Example: request a token and list your kiosks

# 1. Get a token
TOKEN=$(curl -s -X POST https://my.livello.com/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"client_id":"lv_m2m_abc123","client_secret":"sk_live_xxx","grant_type":"client_credentials"}' \
  | jq -r .access_token)

# 2. List kiosks
curl -s https://my.livello.com/api/v1/kiosks \
  -H "Authorization: Bearer $TOKEN" | jq

Tokens are valid for 24 hours and are cached server-side, so repeated requests with the same credentials return the same token until it expires. See Authentication for scopes, rate limits, and error handling.

To access the API, you need M2M (machine-to-machine) client credentials. These are provisioned by Livello upon request. Contact the Livello Service Team via Service@livello.com or +49 211 63556321.

Each client receives:

Store your secret securely. The client secret is delivered once and cannot be recovered. If lost, a new one must be issued.

IP Allowlisting

Optional but recommended for production. Restrict token issuance to specific IP addresses or CIDR ranges. When enabled, token requests from unlisted IPs are rejected with 403 Forbidden.

Configured during registration or on request. Contact Livello to set up or modify.

Token Lifetime

Defaults to 24 hours, configurable per client. See Token Lifecycle for caching, renewal, and revocation details.

The following terms appear throughout the API and reflect how Livello models its autonomous retail operations.

The OpenAPI specification is available as a downloadable JSON file. You can import it into Postman or any OpenAPI-compatible tool.

Postman import steps:

1. Download openapi.json using the Download button at the top of this page
2. In Postman, go to Import → File and select the downloaded JSON
3. Endpoints are organized into folders matching the API tags: Kiosks, Products, Transactions, Analytics: Sales, and more
4. Set a collection-level Authorization of type Bearer Token and paste your access token

Tip: Tags in the OpenAPI spec map directly to Postman collection folders, making it easy to navigate endpoints by resource type.

Official client libraries for the Livello Open Platform API. Each SDK is generated from the OpenAPI specification, so method signatures and models always match the live API.

SDK download links are provided as part of your M2M client onboarding. Contact your Livello account manager if you haven't received them.

Installation

Python: install directly from URL with pip:

# Latest version
pip install https://my.livello.com/developer/sdks/livello-python-sdk-latest.zip

# Specific version
pip install https://my.livello.com/developer/sdks/1.0.0/livello-python-sdk-1.0.0.zip

TypeScript: download, extract, and install as a local package:

# Latest version
curl -O https://my.livello.com/developer/sdks/livello-typescript-sdk-latest.zip
unzip livello-typescript-sdk-latest.zip -d livello-sdk
npm install ./livello-sdk

# Specific version
curl -O https://my.livello.com/developer/sdks/1.0.0/livello-typescript-sdk-1.0.0.zip
unzip livello-typescript-sdk-1.0.0.zip -d livello-sdk
npm install ./livello-sdk

Usage Examples

Both examples authenticate with client credentials, then list all kiosks, following the same flow shown in the Quick Start using curl.

Python:

from livello_api import ApiClient, Configuration, AuthenticationApi, KiosksApi
from livello_api.models import TokenRequestDto

# 1. Get a token
auth_api = AuthenticationApi()
token_response = auth_api.get_token(
    TokenRequestDto(
        client_id="lv_m2m_abc123",
        client_secret="sk_live_xxx",
        grant_type="client_credentials",
    )
)

# 2. Configure the client with the token
config = Configuration(access_token=token_response.access_token)
client = ApiClient(config)

# 3. List kiosks
kiosks_api = KiosksApi(client)
response = kiosks_api.get_kiosks()

for kiosk in response.data:
    print(f"{kiosk.serial_number}: {kiosk.name}")

TypeScript:

import {
  AuthenticationApi,
  KiosksApi,
  Configuration,
} from "@livello/open-platform-sdk";

// 1. Get a token
const authApi = new AuthenticationApi();
const { accessToken } = await authApi.getToken({
  tokenRequestDto: {
    clientId: "lv_m2m_abc123",
    clientSecret: "sk_live_xxx",
    grantType: "client_credentials",
  },
});

// 2. Configure the client with the token
const config = new Configuration({ accessToken });
const kiosksApi = new KiosksApi(config);

// 3. List kiosks
const { data } = await kiosksApi.getKiosks();

for (const kiosk of data) {
  console.log(`${kiosk.serialNumber}: ${kiosk.name}`);
}

Timeouts

Neither SDK sets a default request timeout, so a stalled connection can hang indefinitely. Set one per call.

Python (_request_timeout: seconds, or a (connect, read) tuple):

response = kiosks_api.get_kiosks(_request_timeout=(3, 10))

TypeScript (an AbortSignal passed as the second argument):

const { data } = await kiosksApi.getKiosks({}, { signal: AbortSignal.timeout(10000) });

Debug Logging (Python)

Warning: Configuration.debug = True logs raw HTTP traffic, including the Authorization bearer token and the token request body (your client secret). Never enable it in production or with real credentials.

Obtain and manage API access tokens. You need M2M client credentials before using the API. See Client Registration for how to obtain your client ID, client secret, and scopes.

Exchange your client_id and client_secret for a JWT access token. The token is included as a Bearer token in the Authorization header of all subsequent requests.

Token Request

POST /auth/token
Content-Type: application/json

{
  "client_id": "lv_m2m_abc123",
  "client_secret": "sk_live_xxxxxxxxxxxxxxxx",
  "grant_type": "client_credentials"
}

Token Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 86400,
  "scope": "kiosks:read inventory:read"
}

Using the Token

GET /kiosks
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Your client is granted specific scopes that determine which endpoints are accessible. Requesting an endpoint without the required scope returns 403 Forbidden.

Optional. When configured, only token requests from allowed IP addresses or CIDR ranges are accepted. Requests from unlisted IPs receive 403 Forbidden.

IP restrictions are enforced at token issuance, not on individual API calls. Contact Livello to configure (see Client Registration).

All API responses include standard rate limit headers:

Exceeding either limit returns 429 Too Many Requests.

All errors follow the RFC 7807 Problem Details standard:

{
  "type": "https://api.livello.com/errors/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "Insufficient scope. Required: kiosks:read",
  "instance": "/api/v1/kiosks"
}

A kiosk is a physical smart vending unit identified by a unique serial number (e.g., LIV-0042). Each kiosk contains multiple load cells, and each load cell holds one product.

Query your kiosk fleet: list units, get details, check real-time inventory, and view the current or most recent session.

See also: Products · Product Lines · Alerts

A product (product meta) is the catalog definition of a sellable item, shared across all kiosks in your organization. Contains name, manufacturer, category, nutrition data, images, and default pricing.

Browse, create, update, and delete catalog entries.

See also: Product Lines · Kiosks

A product line binds a product to a specific load cell inside a kiosk. It defines how that product is sold on that particular scale: pricing, tax rate, and capacity. Each load cell has exactly one product line.

The product line ID is separate from the product (meta) ID; use the inventory endpoint under Kiosks to discover product line IDs.

See also: Products · Kiosks · Discounts

A transaction represents a complete purchase session: payment authorization → door opens → customer takes items → door closes → inventory reconciled → receipt generated.

List and retrieve transaction history with line items and payment details. Supports timezone conversion via the x-timezone header (default: Europe/Berlin).

See also: Kiosks · Analytics: Sales · Analytics: Transactions

A refill is a restocking session initiated by an operator entering a PIN on the kiosk. The unit unlocks, the operator adds or removes products, and inventory is recalculated when the door closes.

List and retrieve refill history with item-level detail. Supports timezone conversion via the x-timezone header (default: Europe/Berlin).

See also: Kiosks · Analytics: Refills

An organization is the root entity for data ownership. Every kiosk, product, user, and transaction belongs to an organization. Organizations can be nested (parent → child) for multi-level structures.

All API data is automatically scoped to your organization and its descendants.