iikocloudapi

A fully typed async Python client for the iikoCloud API, generated from the official OpenAPI specification.

• Every endpoint: deliveries, table orders, reserves, loyalty, menu, inventory, finance, nomenclature, employees, reports. The method name mirrors the URL: /api/1/order/create is iiko.order.create(...).
• Typed models for every request and response, with documentation for every field.
• Strict requests, tolerant responses: a typo in a field name fails before the request is sent; new fields and enum values from iikoCloud never break parsing.
• Exact money: all numbers are Decimal.
• Batteries included: token refresh, typed errors, waiting for asynchronous commands, webhook parsing.
• Always up to date: the specification is checked weekly.

Installation

pip install iikocloudapi

Python 3.11 to 3.14.

Quickstart

import asyncio
from decimal import Decimal

from iikocloudapi import AppAuth, IikoCloud
from iikocloudapi.models import CashPayment, ProductOrderItem, TableOrder


async def main() -> None:
    auth = AppAuth(api_key="...", app_id="...", client_secret="...")
    async with IikoCloud(auth=auth) as iiko:
        organizations = await iiko.organizations()
        org_id = organizations.organizations[0].id

        groups = await iiko.terminal_groups(organization_ids=[org_id])
        group_id = groups.terminal_groups[0].items[0].id

        created = await iiko.order.create(
            organization_id=org_id,
            terminal_group_id=group_id,
            order=TableOrder(
                table_ids=["..."],
                items=[ProductOrderItem(product_id="...", amount=Decimal(1), price=Decimal("450.00"))],
                payments=[CashPayment(payment_type_id="...", sum=Decimal("450.00"))],
            ),
        )
        await iiko.wait(created, organization_id=org_id)  # order creation is an asynchronous command


asyncio.run(main())

More in the documentation and the examples: table orders paid online (pay first and cook first), deliveries, menu sync with stop lists, a webhook receiver.

Handling errors

from iikocloudapi import BadRequest, CommandFailed, IikoNetworkError

try:
    created = await iiko.deliveries.create(organization_id=org_id, terminal_group_id=group_id, order=order)
    await iiko.wait(created, organization_id=org_id)
except BadRequest as error:
    print(error.description, error.correlation_id)
except CommandFailed as error:
    print("The terminal rejected the order:", error.exception)
except IikoNetworkError:
    ...

API coverage

324 endpoints: every iikoCloud API endpoint that is not superseded by a newer version.

Upgrading from 0.4

Version 1.0 is a rewrite: see the migration guide.

Development

poetry install --all-groups
python -m codegen  # regenerate the client from spec/iiko-cloud-api.json
pytest

See Development for the code generator, tests and releases.

License

MIT