Tirdad Python SDK

Type-safe Python client for the Tirdad API: billing, metering, and subscription management for SaaS and usage-based products.

Requirements

• Python 3.10+

Installation

pip install tirdad-sdk

With uv or poetry:

uv add tirdad-sdk
# or
poetry add tirdad-sdk

Runnable samples are in the examples/ directory.

Environment

Integration tests in api/tests/python/test_sdk.py use a different env shape; see api/tests/README.md.

Quick start

Initialize the client, create a customer, ingest an event:

import os
from tirdad_sdk import Tirdad

api_key = os.getenv("TIRDAD_API_KEY", "YOUR_API_KEY")
server_url = os.getenv(
    "TIRDAD_API_HOST", "https://api.tirdad.ai/v1"
)

with Tirdad(server_url=server_url, api_key_auth=api_key) as client:
    external_id = "customer-123"
    client.customers.create_customer(
        external_id=external_id,
        email="user@example.com",
        name="Example Customer",
    )
    result = client.events.ingest_event(
        request={
            "event_name": "Sample Event",
            "external_customer_id": external_id,
            "properties": {"source": "python_app", "environment": "test"},
            "source": "python_app",
        }
    )
    print(result)

Async usage

The same client supports async when used as an async context manager:

import asyncio
import os
from tirdad_sdk import Tirdad

async def main():
    server_url = os.getenv(
        "TIRDAD_API_HOST", "https://api.tirdad.ai/v1"
    )
    async with Tirdad(
        server_url=server_url,
        api_key_auth=os.getenv("TIRDAD_API_KEY", "YOUR_API_KEY"),
    ) as client:
        result = await client.events.ingest_event_async(
            request={
                "event_name": "Sample Event",
                "external_customer_id": "customer-123",
                "properties": {"source": "python_async", "environment": "test"},
                "source": "python_async",
            }
        )
        print(result)

asyncio.run(main())

Authentication

• Pass your API key as api_key_auth when creating the client. The SDK sends it in the x-api-key header.
• Set TIRDAD_API_HOST to a full URL (see Environment) or use the default https://api.tirdad.ai/v1.
• Prefer environment variables; get keys from your Tirdad dashboard or docs.

Error handling

API errors are raised as exceptions. Catch them and inspect the response as needed:

try:
    with Tirdad(server_url="...", api_key_auth="...") as tirdad:
        result = tirdad.events.ingest_event(request={...})
except Exception as e:
    print(f"Error: {e}")
    # Inspect status code and body if available on the exception

See the API docs for error formats and status codes.

Features

• Full API coverage (customers, plans, events, invoices, payments, entitlements, etc.)
• Sync and async support
• Type-safe request/response models (Pydantic)
• Built-in retries and error handling

For a full list of operations, see the API reference and the examples in this repo.

Troubleshooting

• Missing or invalid API key: Ensure api_key_auth is set (or set TIRDAD_API_KEY and pass it in). Keys are for server-side use only.
• Wrong server URL: Use a full URL such as https://api.tirdad.ai/v1 (include /v1; no trailing slash).
• 4xx/5xx on ingest: Event ingest returns 202 Accepted; for errors, check request fields (event_name, external_customer_id, properties, source) against the API docs.

Handling Webhooks

Tirdad sends webhook events to your server for async updates on payments, invoices, subscriptions, wallets, and more.

Flow:

1. Register your endpoint URL in the Tirdad dashboard
2. Receive POST with raw JSON body
3. Read event_type to route
4. Parse payload into typed model
5. Handle business logic idempotently
6. Return 200 quickly

import json
from tirdad_sdk.models import (
    WebhookDtoPaymentWebhookPayload,
    WebhookDtoSubscriptionWebhookPayload,
    WebhookDtoInvoiceWebhookPayload,
)

def handle_webhook(raw_body: str) -> None:
    event = json.loads(raw_body)

    match event.get("event_type"):
        case "payment.success" | "payment.failed" | "payment.updated":
            payload = WebhookDtoPaymentWebhookPayload.model_validate(event)
            if payload.payment:
                print(f"payment {payload.payment.id}")
                # TODO: update payment record

        case "subscription.activated" | "subscription.cancelled" | "subscription.updated":
            payload = WebhookDtoSubscriptionWebhookPayload.model_validate(event)
            if payload.subscription:
                print(f"subscription {payload.subscription.id}")

        case "invoice.update.finalized" | "invoice.payment.overdue":
            payload = WebhookDtoInvoiceWebhookPayload.model_validate(event)
            if payload.invoice:
                print(f"invoice {payload.invoice.id}")

        case _:
            print(f"unhandled event: {event.get('event_type')}")

Event types

Production rules:

• Keep handlers idempotent — Tirdad retries on non-2xx
• Return 200 for unknown event types — prevents unnecessary retries
• Do heavy processing async — respond fast, queue the work

Documentation

• Tirdad API documentation
• Python SDK examples in this repo
• SDK integration tests — different TIRDAD_API_HOST shape for automated tests