> 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

You'll need:

- A [Paddle sandbox account](https://developer.paddle.com/sdks/sandbox.md).
- A [sandbox API key](https://developer.paddle.com/api-reference/about/authentication.md) with permission to read and write products.
- 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
```

[View the Python SDK on GitHub](https://github.com/PaddleHQ/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. Create a product in the dashboard or via `paddle.products.create()` to see results.

## Verify webhooks {% step=true %}

You can use [webhooks](https://developer.paddle.com/webhooks.md) to keep your app in sync with Paddle. For example, you can [provision access](https://developer.paddle.com/build/subscriptions/provision-access-webhooks.md) when a subscription is created, or revoke access when a subscription is cancelled.

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, including creating notification destinations, picking events, and retry behavior, see [Verify webhook signatures](https://developer.paddle.com/webhooks/about/signature-verification.md).

## Next steps

- Use the [webhook simulator](https://developer.paddle.com/webhooks/simulator.md) to test webhook events.
- Browse the [API reference](https://developer.paddle.com/api-reference.md) to see every endpoint Paddle exposes.
- View the [Python SDK reference](https://developer.paddle.com/sdks/libraries/python.md) for the full SDK reference.