Skip to main content

​
Python SDK

The official Windback SDK for Python. Use it to track events, create churn events, and manage recovery flows from your server.

​
Installation

pip install windback
The SDK requires Python 3.8 or later.

​
Quick Start

from windback import Windback

client = Windback(
    api_key="sk_live_your_secret_key",
    project_slug="my-project",
)

# Track a customer event
client.track_event(
    event="feature_used",
    customer_email="jane@example.com",
    properties={
        "feature": "exports",
        "plan": "pro",
    },
)
Use your secret key (sk_) for server-side SDK calls. Never expose it in client-side code.

​
Track Events

# Track a single event
client.track_event(
    event="feature_used",
    customer_email="jane@example.com",
    properties={
        "feature": "dashboard",
        "duration_seconds": 120,
    },
)

# Track a batch of events
client.track_events([
    {
        "event": "login",
        "customer_email": "jane@example.com",
        "timestamp": "2025-12-01T10:00:00Z",
    },
    {
        "event": "subscription_renewed",
        "customer_email": "jane@example.com",
        "properties": {"plan": "pro", "mrr": 2999},
    },
])

​
Create Churn Events

event = client.create_churn_event(
    customer_email="jane@example.com",
    customer_name="Jane Smith",
    event_type="cancellation",
    cancel_reason="Missing integrations we need",
    mrr=4999,
    currency="usd",
    plan_name="Team Pro",
    tenure_days=180,
)

print(event.id)      # "evt_abc123"
print(event.status)  # "new"

​
Cancel Flow

# Submit a cancel flow response
client.submit_cancel_flow(
    customer_email="jane@example.com",
    cancel_reason="Too expensive for our team",
    feedback_text="Love the product but budget is tight",
    selected_offer="downgrade",
)

# Report just the cancel reason
client.report_cancel_reason(
    customer_email="jane@example.com",
    reason="switching_competitor",
)

​
Async Support

The SDK includes an async client for use with asyncio and frameworks like FastAPI. 
from windback import AsyncWindback

client = AsyncWindback(
    api_key="sk_live_your_secret_key",
    project_slug="my-project",
)

# All methods are async
event = await client.create_churn_event(
    customer_email="jane@example.com",
    event_type="cancellation",
    cancel_reason="Too expensive",
    mrr=2999,
)

await client.track_event(
    event="feature_used",
    customer_email="jane@example.com",
    properties={"feature": "exports"},
)
The async client uses httpx under the hood for non-blocking HTTP requests.

​
Method Reference

MethodDescription
track_event(event, customer_email, ...)Track a single customer behavior event
track_events(events)Track a batch of events
create_churn_event(...)Create a churn event manually
submit_cancel_flow(...)Submit cancel flow data (reason + feedback)
report_cancel_reason(...)Report a cancel reason for an existing event
create_recovery_template(...)Create a custom recovery email template

​
Error Handling

from windback import WindbackError

try:
    event = client.create_churn_event(...)
except WindbackError as e:
    print(e.status)   # HTTP status code
    print(e.message)  # Error message
    print(e.code)     # Error code (e.g., "INVALID_API_KEY")
The SDK automatically retries failed requests up to 3 times with exponential backoff.