Skip to main content

Noosh24

Noosh24 Open API for Python

The official Python client for the Noosh24 Open API.
Menu, reservations, orders and bills, payments and the Z-report, tables, customers, loyalty, stock and reviews of a Noosh24 venue, plus creating and cancelling reservations.

CI Python 3.11+ PyPI MIT license

Developer site · API reference · All SDKs · Report an issue

Contents: Requirements · Install · Quick start · Options · Resources · Lists, filters and pages · Reservations · Errors · Retries and rate limits · Development · License

Requirements

  • Python 3.11 or newer (tested on 3.11 to 3.15). One dependency: httpx.
  • Typed dataclasses for every response (py.typed included).

Install

pip install noosh24

Quick start

import os

from noosh24 import Noosh24, where

noosh = Noosh24(os.environ["NOOSH24_API_KEY"])

me = noosh.whoami()
print(me.restaurant.name, me.key.scopes)

page = noosh.menu.list_products(
    where=where().eq("category", "Salads").eq("available", True),
    sort="price desc",
    limit=50,
)
for product in page:
    print(product.name, product.price)
print(page.total, "products match")

The key belongs to one venue, so there is no venue parameter anywhere. Keys are issued in the Noosh24 panel; keep them on your server, never in a browser or a mobile app.

Options

noosh = Noosh24(
    "nsk_...",
    base_url="https://open-api.noosh24.com/v1",
    timeout=30.0,
    max_retries=2,
    user_agent="acme-pos/2.1",
)

timeout is in seconds. http_client takes your own httpx.Client (proxies, custom TLS, tests). Use the client as a context manager, or call close(), to release connections:

with Noosh24("nsk_...") as noosh:
    print(noosh.whoami().restaurant.name)

Resources

Group Methods
whoami() the venue, the key's scopes and the venue's modules
menu list_categories(), list_products(), iterate_products(), get_product(id, expand=), get_stop_list()
reservations list(), iterate(), get(id), availability(date, time, guests=), create(...), cancel(id)
orders list(), iterate(), get(id), list_bills(), iterate_bills(), get_bill(id)
payments list(), iterate(), get(id), z_report(date=)
tables list(), list_halls()
customers list(), iterate(), get(id)
loyalty get_program(), list_cards(), iterate_cards()
stock list_ingredients(), iterate_ingredients(), list_moves(), iterate_moves(), list_stores()
reviews list(), iterate()

Responses are frozen dataclasses (Product, Reservation, Order, ...) with snake_case attributes: product.prep_minutes, reservation.starts_at. Timestamps are timezone-aware datetime objects in UTC, money is float in AZN. model.raw holds the JSON as the API sent it, including fields this version of the SDK does not know yet.

Lists, filters and pages

List methods take limit, offset, sort, where and, for products, expand. They return a Page with items, total, limit, offset, has_more and next_offset; a page is iterable.

orders = noosh.orders.list(
    where="status = 'served' AND createdAt >= '2026-11-01'",
    sort=["createdAt desc"],
    limit=100,
)

where is AND only, and field names are the API's camelCase names. Build it with where() so strings and dates are quoted correctly:

from datetime import date, datetime, timedelta, timezone

baku = timezone(timedelta(hours=4))
condition = (
    where()
    .eq("status", "confirmed")
    .gte("startsAt", datetime(2026, 11, 20, tzinfo=baku))
    .in_("zone", ["Terrace", "Chef's table"])
)

The iterate*() methods walk every page and fetch the next page only when you reach it:

for payment in noosh.payments.iterate(where="createdAt >= '2026-11-01'"):
    ...

offset stops at 10000. For bigger exports, narrow where by date and walk one window at a time.

Reservations

from noosh24 import PreOrderLine, TableTakenError

free = noosh.reservations.availability("2026-11-20", "19:30", guests=4)

try:
    result = noosh.reservations.create(
        date="2026-11-20",
        time="19:30",
        guests=4,
        guest_name="Aysel Məmmədova",
        phone="+994501234567",
        table_id=free.tables[0].id,
        pre_order=[PreOrderLine(item_id="0b6f3c1e", qty=2)],
        external_ref="acme-booking-991",
    )
except TableTakenError:
    ...

print(result.reservation.code, "created" if result.created else "already existed")
noosh.reservations.cancel(result.reservation.id)

A booking lands as pending and the venue confirms it. Always send external_ref (your own booking id): sending the same external_ref again returns the booking that already exists instead of making a second one, so a create is safe to retry. The client retries a create only when it carries an external_ref. You can cancel only bookings your key created.

Errors

Every API error is a subclass of APIError with status, code (the API's error field), message and headers. Branch on the class or on code, not on the message.

code Exception Parent
validation_error ValidationError APIError
no_api_key NoApiKeyError AuthenticationError
invalid_api_key InvalidApiKeyError AuthenticationError
insufficient_scope InsufficientScopeError PermissionDeniedError
module_not_enabled ModuleNotEnabledError PermissionDeniedError
venue_suspended VenueSuspendedError PermissionDeniedError
not_your_reservation NotYourReservationError PermissionDeniedError
not_found NotFoundError APIError
table_not_found TableNotFoundError NotFoundError
table_taken TableTakenError ConflictError
cannot_cancel CannotCancelError ConflictError
outside_hours, in_the_past, table_too_small OutsideHoursError, InThePastError, TableTooSmallError UnprocessableError
rate_limit_exceeded RateLimitError (retry_after) APIError
temporarily_unavailable TemporarilyUnavailableError ServerError

A network failure raises APIConnectionError; a timeout raises APITimeoutError. All of them extend Noosh24Error.

Retries and rate limits

A key gets 600 requests a minute. On 429 and 502/503/504 the client waits (Retry-After when the API sends it, otherwise 0.5 s, 1 s, 2 s ...) and tries again, up to max_retries times. It never waits more than 60 seconds; a longer Retry-After is raised to you as a RateLimitError. Reads, cancels and creates with an external_ref are retried; a create without an external_ref is not.

Development

python -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/pytest

License

MIT

Metadata

Release files for noosh24 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for noosh24 0.1.0
File Size Uploaded Provenance Actions
noosh24-0.1.0.tar.gz 22.3 kB With provenance Details for noosh24-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for noosh24 0.1.0
File Interpreter ABI Platform Actions
noosh24-0.1.0-py3-none-any.whl Python 3 none any Details for noosh24-0.1.0-py3-none-any.whl

Total release size: 41.2 kB

Release files / noosh24-0.1.0.tar.gz

Download URL noosh24-0.1.0.tar.gz
Size 22.3 kB
Tags Source
SHA-256 checksum
How to use checksums
1100ae110e5bf834b9640226d4d86491d5c40578ed4a14ba5d817ca0afbc00b3
BLAKE2b-256 checksum
How to use checksums
9a0f9d8b1d3f38b749f0c9d515b855b4e0f590c6830a45679c19af3a4a404b67
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / noosh24-0.1.0-py3-none-any.whl

Download URL noosh24-0.1.0-py3-none-any.whl
Size 18.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
514b7e3f628686a8c3bc94e4b5035cc954d1a96e5d6c96ff33fab9e87efaacef
BLAKE2b-256 checksum
How to use checksums
2e9c9c5ef7cc6bd8d27e94a82e8e507420e85444a93b0a269aceaad30428a8de
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Security for noosh24 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for noosh24-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page