Get started with Paddle in 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.
• A sandbox API key with permission to read and write products.
• Python 3.11 or later.

1. Install the SDK

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

pip install paddle-python-sdk

poetry add paddle-python-sdk

uv add paddle-python-sdk

2. Initialize the client

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

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:

paddle = Client(getenv("PADDLE_API_KEY"))

3. Make your first request

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

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

You can use webhooks to keep your app in sync with Paddle. For example, you can provision access 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.

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.

Next steps

• Use the webhook simulator to test webhook events.
• Browse the API reference to see every endpoint Paddle exposes.
• View the Python SDK reference for the full SDK reference.