Python SDK

Official Python client. Works on CPython 3.9–3.13. Ships type stubs.

Install

pip install oligon-receipts

Sync & async

from oligon_receipts import OligonReceipts, AsyncOligonReceipts
 
# Sync
client = OligonReceipts(api_key="sk_live_...")
r = client.extract(file="receipt.jpg")
 
# Async — same surface, "a" prefix
import asyncio
 
async def main():
    async with AsyncOligonReceipts() as client:
        r = await client.extract(file="receipt.jpg")
 
asyncio.run(main())

Configuration

Argument	Default	Description
`api_key`	`OLIGON_API_KEY` env	Required.
`base_url`	`https://api.receipts.oligontech.com`	Override for staging / self-hosted.
`timeout`	`30.0`	Seconds per request.
`max_retries`	`5`	Auto-retries on 429/5xx.
`backoff_base`	`0.3`	Initial backoff in seconds.
`backoff_max`	`8.0`	Max backoff.
`http_client`	new `httpx.Client`	Inject your own (proxies, mTLS).

Pagination

# auto-paginate — yields every receipt across pages
for r in client.receipts.list(after="2026-01-01"):
    print(r.id)
 
# single page
page = client.receipts.list_page(limit=20)
while page.has_more:
    page = client.receipts.list_page(cursor=page.next_cursor, limit=20)

Errors

from oligon_receipts import (
    OligonAPIError, AuthError, RateLimitError, ValidationError,
)
 
try:
    client.extract(file=path)
except AuthError:
    rotate_key()
except RateLimitError as e:
    time.sleep(e.retry_after or 1)
except ValidationError as e:
    log(e.body)
except OligonAPIError as e:
    log("oligon failed:", e.status_code, e.request_id)

Webhook verification

from oligon_receipts import OligonReceipts
 
OligonReceipts.verify_webhook(raw_body, signature, secret)

The static method works without a client instance — useful in serverless handlers where you do not need any other API call.

Source

github.com/gogoncalves/oligon-receipts/tree/main/sdks/python (opens in a new tab)

Errors Node / TypeScript