tolt

Python SDK for the Tolt API (v2), with sync and async clients. Run it on your server: it needs your secret API key. Requires Python 3.10 or newer.

Install

pip install tolt

Usage

import os
from tolt import ToltApi

client = ToltApi(token=os.environ["TOLT_API_KEY"])

partner = client.partners.get(id="part_8fKq2LmZx7RtYw3nVbHc5dPj").data

for customer in client.customers.list():
    print(customer.id)

Single-item calls return the API envelope, so read .data. list returns a pager: iterate it to walk every page, or read .items for one page.

Resources: partners, customers, transactions, commissions, links, clicks, promotion_codes, programs, groups, flows, reports, embed_tokens.

Async

import asyncio
import os
from tolt import AsyncToltApi

client = AsyncToltApi(token=os.environ["TOLT_API_KEY"])


async def main() -> None:
    async for partner in await client.partners.list():
        print(partner.id)


asyncio.run(main())

Errors

import httpx
from tolt import NotFoundError
from tolt.core.api_error import ApiError

try:
    client.partners.get(id="part_8fKq2LmZx7RtYw3nVbHc5dPj")
except NotFoundError as e:
    print(e.body.code)  # "not_found"
except ApiError as e:
    print(e.status_code, e.body)
except httpx.TimeoutException:
    ...  # no response within the timeout

Every API error extends ApiError. Timeouts raise httpx's TimeoutException. Read e.status_code and e.body rather than str(e), which starts with the response headers.

Retries and timeouts

Failed requests (408, 409, 429, 5xx and dropped connections) are retried twice with backoff. Calls that create something (every create, and transactions.rerun_flows) are never retried, so a server error can't create a duplicate. Override per client or per call:

client = ToltApi(token=os.environ["TOLT_API_KEY"], max_retries=3, timeout=30)

client.partners.get(id="part_8fKq2LmZx7RtYw3nVbHc5dPj", request_options={"timeout": 5})

The client talks to https://platform.tolt.com by default. Pass base_url to point it elsewhere.

Type checking

The package ships py.typed. With mypy, annotate sub-clients you pass around (partners: PartnersClient = client.partners), since mypy reads the client's sub-client properties as untyped. Pyright infers them.

Development

src/tolt/ is generated by Fern from the API's OpenAPI spec in toltapp/tolt-sdks, which opens a pull request here when the spec changes. Don't edit it by hand.

pip install -e . pytest mypy
pytest tests
mypy src/tolt --exclude src/tolt/tests