Paddle Getting Started: API Integration Guide (2026)

Getting started overview

Integrating with Paddle's platform involves a sequence of steps designed to enable subscription management, payment processing, and tax compliance for software and SaaS businesses. The initial setup focuses on account creation, credential generation, and making a foundational API call. Paddle operates as a merchant of record, handling aspects of sales tax, VAT, and compliance globally, which distinguishes its integration process from direct payment gateways Paddle pricing information.

The Paddle API is RESTful, supporting JSON for request and response bodies. It facilitates operations across Paddle Billing, Paddle Payments, and Paddle Tax. Developers typically interact with the API to manage customers, subscriptions, products, prices, and transactions. Authentication for server-side requests relies on an API Key, while client-side operations often use a Client-side Token Paddle API reference documentation.

This guide outlines the essential steps to get a basic integration operational, from setting up your Paddle account to executing your first API request. It covers the necessary administrative actions within the Paddle Dashboard and provides examples for programmatically interacting with the API.

Quick start summary

The following table summarizes the key steps to begin your Paddle integration:

Create an account and get keys

Before making any API calls, you must first create a Paddle account and obtain the necessary authentication credentials. Paddle offers a free-to-start model, with transaction fees applied as you process payments Paddle pricing page.

Account creation

1. Sign up for Paddle: Navigate to the Paddle website and complete the registration process. This typically involves providing business details, contact information, and agreeing to their terms of service.
2. Onboarding Process: After signing up, Paddle may have an onboarding process that requires additional business verification steps before full account functionality is enabled.

API key generation

Paddle uses two primary types of authentication credentials for API interactions:

• Server Key: Used for server-to-server API calls, such as creating subscriptions, managing customers, or fetching transaction details. This key should be kept confidential and never exposed client-side.
• Client-side Token: Used for client-side operations, particularly with Paddle's checkout and overlay features, to securely identify your account without exposing sensitive server keys.

To generate these keys:

1. Log in to the Paddle Dashboard: Access your Paddle account dashboard.
2. Navigate to Developer Tools: In the left-hand navigation, locate and click on Developer Tools.
3. Select Authentication: Under Developer Tools, choose the Authentication section.
4. Generate Keys: Here you will find options to generate your Server Key and Client-side Token. Make sure to copy these values immediately, as the Server Key may only be shown once for security reasons Paddle quickstart guide.

It is recommended to store your Server Key securely, for example, using environment variables or a secrets management service, rather than hardcoding it directly into your application's source code.

Configure webhooks

Webhooks are essential for receiving real-time notifications about events occurring in your Paddle account, such as subscription renewals, payment failures, or refunds. To configure webhooks:

1. In the Paddle Dashboard: Go to Developer Tools > Webhooks.
2. Add an Endpoint: Click Add an endpoint and provide the URL where Paddle should send event data. This URL must be publicly accessible.
3. Select Events: Choose which events you want to subscribe to (e.g., subscription.created, transaction.completed).
4. Verify Webhook Signature: For security, Paddle signs its webhook requests. Implement webhook signature verification in your application to ensure the requests originate from Paddle Paddle webhooks overview. This typically involves using the Paddle-Signature header and your webhook secret. This practice is a common security measure for webhook integrations across platforms like Twilio Twilio's webhook security guide and Stripe Stripe webhook signatures documentation.

Your first request

After obtaining your API keys, you can make your first authenticated request to the Paddle API. A common initial request is to list products or prices to confirm your setup is correct. For this example, we will use the List Products API endpoint.

Using cURL

Replace YOUR_PADDLE_SERVER_KEY with the Server Key you generated.

curl -X GET \
  'https://api.paddle.com/products' \
  -H 'Authorization: Bearer YOUR_PADDLE_SERVER_KEY' \
  -H 'Content-Type: application/json'

A successful response will return a JSON object containing an array of products associated with your account. If you haven't created any products yet, the data array will be empty.

Using Python SDK

Paddle provides official SDKs for various languages, simplifying API interactions. Here's an example using the Python SDK:

1. Install the SDK:

   pip install paddle-python-sdk

2. Make the request: Replace YOUR_PADDLE_SERVER_KEY with your actual Server Key.

   from paddle_python_sdk import PaddleClient
   
   paddle = PaddleClient(api_key='YOUR_PADDLE_SERVER_KEY')
   
   try:
       products = paddle.products.list()
       print(products.data)
   except Exception as e:
       print(f"An error occurred: {e}")

Using JavaScript SDK (Node.js)

1. Install the SDK:

   npm install @paddle/paddle-sdk

2. Make the request: Replace YOUR_PADDLE_SERVER_KEY with your actual Server Key.

   const { PaddleClient } = require('@paddle/paddle-sdk');
   
   const paddle = new PaddleClient('YOUR_PADDLE_SERVER_KEY');
   
   async function listProducts() {
     try {
       const products = await paddle.products.list();
       console.log(products.data);
     } catch (error) {
       console.error(`An error occurred: ${error.message}`);
     }
   }
   
   listProducts();

Common next steps

Once you've successfully made your first API call, you can proceed with more advanced integrations:

• Define Products and Prices: Create your digital products and define their pricing models (one-time, subscription, free trials) within the Paddle Dashboard or via the API Paddle Create Product API, Paddle Create Price API.
• Integrate Checkout: Implement Paddle's hosted checkout pages or embed the Paddle Checkout within your application. This involves using the Client-side Token and configuring product IDs Paddle checkout overview.
• Manage Subscriptions: Develop logic to create, update, pause, resume, and cancel subscriptions using the Subscriptions API Paddle Create Subscription API.
• Handle Webhook Events: Build robust webhook handlers to react to events like successful payments, subscription changes, and payment failures. This is critical for keeping your application's state synchronized with Paddle Paddle webhook documentation.
• Test in Sandbox: Utilize Paddle's sandbox environment for development and testing without affecting live transactions or customer data. Ensure your API keys are for the sandbox environment during this phase Paddle sandbox environment guide.
• Implement Customer Portal: Provide customers with access to a self-service portal for managing their subscriptions, payment methods, and invoices, often facilitated by Paddle's built-in customer portal features Paddle Customer Portal overview.

Troubleshooting the first call

If your first API call does not return the expected result, consider the following troubleshooting steps:

• Check API Key: Ensure you are using the correct Server Key for server-to-server requests. Double-check for typos or leading/trailing spaces. Verify that you are not accidentally using a Client-side Token where a Server Key is required, or vice versa.
• Environment Mismatch: Confirm that your API key corresponds to the environment you are targeting (sandbox vs. live). Sandbox keys will not work with the live API endpoint, and live keys will not work with the sandbox endpoint Paddle sandbox guide.
• Authorization Header: Verify that the Authorization header is correctly formatted as Bearer YOUR_PADDLE_SERVER_KEY.
• Content-Type Header: For requests with a body (e.g., POST, PUT), ensure the Content-Type header is set to application/json.
• Endpoint URL: Confirm that the API endpoint URL is correct (e.g., https://api.paddle.com/products for live, or https://sandbox-api.paddle.com/products for sandbox).
• Network Connectivity: Ensure your development environment has outbound internet access to reach Paddle's API servers.
• Error Messages: Carefully review any error messages returned in the API response. Paddle's API errors often provide specific codes and descriptions that can guide your debugging Paddle API error handling. Common errors include 401 Unauthorized for invalid authentication or 404 Not Found for incorrect endpoints.
• SDK Configuration: If using an SDK, ensure it is correctly initialized with your API key and that you are calling the appropriate methods. Refer to the specific SDK's documentation for correct usage Paddle SDKs overview.