ShelfWatch Python SDK

Official Python client for ShelfWatch APIs v2.

pip install shelfwatch

Quick start

Create credentials in ShelfWatch Console → Integrations, then:

from shelfwatch import ShelfWatch

client = ShelfWatch(
    api_key="swpk_…",
    project_id="PROJECT_UUID",
)

visits = client.visits.list(
    start_date="2026-07-01",
    end_date="2026-07-31",
)
print(visits["data"])

detail = client.visits.get(
    visits["data"][0]["visit_uuid"],
    include_kpis=True,
)

OAuth client credentials

client = ShelfWatch(
    client_id="swoc_…",
    client_secret="swocs_…",
    project_id="PROJECT_UUID",
)
# Access tokens are fetched and refreshed automatically.

API coverage

Filters that accept multiple values can be passed as a comma-separated string or a list:

client.visits.list(
    start_date="2026-07-01",
    end_date="2026-07-31",
    visit_status=["completed"],
    store_code=["S001", "S002"],
)

stores = client.mdm.stores(q="delhi")
reports = client.reports.list()
rows = client.reports.generate(
    "visit-level",
    start_date="2026-07-01",
    end_date="2026-07-07",
)

Full HTTP reference: ShelfWatch Console → Help and Support, or the apis-v2 docs.

Errors

Typed exceptions map to HTTP status codes:

from shelfwatch import ShelfWatch, NotFoundError

try:
    client.visits.get("missing-uuid")
except NotFoundError as exc:
    print(exc.status_code, exc.message)

Development

python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest

Publish to PyPI

./scripts/publish.sh --test   # TestPyPI
./scripts/publish.sh          # PyPI

Or manually:

pip install -e ".[publish]"
python3 -m build
python3 -m twine check dist/*
python3 -m twine upload dist/*

Bump version in pyproject.toml and shelfwatch/__init__.py / client.py User-Agent before each release.