> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).

# Get started with Paddle in Python

Install the Paddle Python SDK, initialize a client, make your first request, and verify webhook signatures.

---

{% version-badge sdk="paddle-python" /%}

This quickstart walks through installing the Paddle Python SDK, initializing a client, making your first read-only API call, and verifying webhook signatures. Python is a common choice for AI workloads, internal tooling, and data scripts that work with billing data.

## Before you begin

- A [Paddle sandbox account](https://developer.paddle.com/sdks/sandbox.md).
- An [API key](https://developer.paddle.com/api-reference/about/api-keys#create-api-key.md) generated in your sandbox dashboard.
- Python 3.11 or later.

## 1. Install the SDK {% step=true %}

Install `paddle-python-sdk` from PyPI. The package imports as `paddle_billing`.

{% code-group %}

```sh {% title="pip" %}
pip install paddle-python-sdk
```

```sh {% title="poetry" %}
poetry add paddle-python-sdk
```

```sh {% title="uv" %}
uv add paddle-python-sdk
```

{% /code-group %}

## 2. Initialize the client {% step=true %}

Read your API key from the environment, then create a `Client` with the sandbox environment while you're building.

```python
from os import getenv
from paddle_billing import Client, Environment, Options

api_key = getenv("PADDLE_API_KEY")
paddle = Client(api_key, options=Options(Environment.SANDBOX))
```

For production, drop the `options` argument:

```python
paddle = Client(getenv("PADDLE_API_KEY"))
```

{% callout type="note" %}
Sandbox API keys contain `_sdbx`. Sandbox and live keys are separate — using one against the other API returns a `forbidden` error.
{% /callout %}

## 3. Make your first request {% step=true %}

List products to confirm the client is wired up. The SDK returns an iterable collection that paginates lazily.

```python
from os import getenv
from paddle_billing import Client, Environment, Options
from paddle_billing.Resources.Products.Operations import ListProducts, ProductIncludes
from paddle_billing.Exceptions.ApiError import ApiError

paddle = Client(getenv("PADDLE_API_KEY"), options=Options(Environment.SANDBOX))

try:
    products = paddle.products.list(ListProducts(includes=[ProductIncludes.Prices]))
    for product in products:
        print(product.id, product.name)
except ApiError as error:
    print(f"Paddle API error: {error}")
```

If your sandbox account is empty, the loop runs zero times — that's fine. Create a product in the dashboard or via `paddle.products.create()` to see results.

## 4. Verify webhooks {% step=true %}

Paddle pushes webhook events to your endpoint when subscriptions, transactions, and customers change state. The SDK ships a `Verifier` that works with any request object matching its protocol — Flask and Django requests work out of the box. Always verify the signature before acting on the payload.

```python
from os import getenv
from flask import Flask, request
from paddle_billing.Notifications import Secret, Verifier
from paddle_billing.Entities.Notifications import NotificationEvent

app = Flask(__name__)
secret = Secret(getenv("PADDLE_WEBHOOK_SECRET"))

@app.route("/webhooks", methods=["POST"])
def webhook():
    if not Verifier().verify(request, secret):
        return "invalid signature", 400

    notification = NotificationEvent.from_request(request)
    if notification.event_type == "transaction.completed":
        # Provision access, send a receipt, etc.
        pass
    elif notification.event_type == "subscription.updated":
        # Sync the subscription to your database.
        pass

    return "ok", 200
```

For the full webhook setup flow — creating notification destinations, picking events, retry behavior — see [Verify webhook signatures](https://developer.paddle.com/webhooks/signature-verification.md).

## Next steps

{% card-group cols=2 %}
{% card title="Build with subscriptions" icon="carbon:repeat" url="/build/subscriptions" %}
Lifecycle, plan changes, pause and resume, addons.
{% /card %}
{% card title="Set up notification destinations" icon="carbon:notification" url="/webhooks/notification-destinations" %}
Configure where Paddle sends webhook events.
{% /card %}
{% card title="API reference" icon="carbon:api" url="/api-reference/overview" %}
Browse every endpoint Paddle exposes.
{% /card %}
{% card title="Python SDK reference" icon="carbon:logo-python" url="/sdks/libraries/python" %}
Full SDK reference — version, repo, install, auth.
{% /card %}
{% /card-group %}

{% callout type="note" %}
**Building AI tools or agents?** Use the [Paddle MCP server](https://developer.paddle.com/sdks/ai/paddle-mcp.md) for natural-language workflows over your account, and the [docs MCP server](https://developer.paddle.com/sdks/ai/docs-mcp.md) for current Paddle documentation in your AI agent.
{% /callout %}