Skip to Content
Paddle integrationConnecting Paddle

Connecting Paddle

LicenseManager connects to your Paddle Billing account with an API key you create in Paddle, which can only do what its permissions allow. It needs five permissions, a sixth one to sell subscriptions, and three optional ones, to refund canceled licenses, cancel subscriptions and open the Paddle customer portal, all explained below. Every other permission stays off.

The connection belongs to your organization, not to a product: once connected, every product of the organization can map prices of that Paddle account. You manage it from the Integrations page of any product.

Only Paddle Billing is supported. Paddle Classic accounts use another API, and can’t be connected.

Live and sandbox

Paddle keeps live and sandbox accounts apart, with their own dashboards and API keys, and so does LicenseManager:

  • Your live products use a live key, starting with pdl_live_apikey_, from vendors.paddle.com . Only real payments create licenses.
  • Your test products use a sandbox key, starting with pdl_sdbx_apikey_, from a sandbox account . Only sandbox payments create licenses, which are test licenses.

We recommend connecting a sandbox account first, mapping a price and paying it with one of Paddle’s test cards , to see the whole flow before selling for real.

Connect your account

Open the Integrations page

In LicenseManager, open a product: a live one to connect your live account, a test one to connect a sandbox account. Click Integrations in the sidebar, then Connect Paddle. The dialog lists the permissions the key needs, with a link to the right page of your Paddle dashboard.

Create an API key in Paddle

In your Paddle dashboard, open Developer tools → Authentication, then click New API key. Name it, for example “LicenseManager”.

Set its permissions

Turn on the permissions listed in the dialog, and only them: see permissions.

Copy the key

Save the key, then copy it. Paddle shows it once.

Paste it in LicenseManager

Paste it in the dialog, then click Connect Paddle. LicenseManager checks the key works, is of the right environment and has the required permissions, then creates a notification destination on your Paddle account, named “LicenseManager: creates licenses from payments”.

Permissions

PermissionAccessWhy
Transactions (transaction.read)ReadReads the items of each completed transaction, their prices and quantities, to create one license per unit bought.
Customers (customer.read)ReadReads the email and name of the customer who paid, to send them their keys.
Prices (price.read)ReadLists your prices so you can choose which ones create licenses, and checks they can still be paid.
Products (product.read)ReadShows the names of your products next to their prices.
Notification settings (notification_setting.write)WriteCreates the notification destination, keeps it pointed at LicenseManager, and deletes it when you disconnect.
Subscriptions (subscription.read)ReadReads the subscriptions to recurring prices, to keep their licenses valid while they’re paid. Only checked once a recurring price is mapped.
Subscriptions (subscription.write)Write, optionalCancels the subscription of the licenses you cancel. Without it, cancel subscriptions from Paddle.
Customer portal sessions (customer_portal_session.write)Write, optionalOpens the Paddle customer portal from the license portal. Without it, the license portal has no link to it.
Adjustments (adjustment.write)Write, optionalRequests the refund of the licenses canceled during their money back guarantee. Without it, refunds are turned off and you refund transactions from Paddle.

Paddle allows 10 active notification destinations per account. When yours already has 10, deactivate one in Developer tools → Notifications, then connect again.

The Paddle card

The card shows the API key’s start and end, the URL of the notification destination, and when the integration was last checked and last received an event. From it, Check now, Replace API key and Disconnect.

Health checks

Every day, LicenseManager checks each integration: that Paddle still accepts the key, that it has the read permissions, Subscriptions: Read included once a recurring price is mapped, that it can manage the notification destination, and which optional permissions it has. The check also repairs the destination: when it was deleted it’s created again, when it was deactivated it’s turned back on, and its URL and events are set back.

When a check finds a new problem, the owners and admins of the organization are emailed what’s wrong and how to fix it.

Statuses

StatusMeaningWhat to do
ActiveEverything works.Nothing.
ErrorSomething needs fixing, explained on the card: a permission removed from the key, a mapped price archived in Paddle, or a payment that couldn’t be turned into licenses.Read the reason, fix it, then click Check now.
DisconnectedPaddle rejects the key: it was revoked or expired.Replace the API key.

Replace the API key

Click Replace API key on the Paddle card, and follow the same steps with a new key. With a key of the same account, the destination and mappings are kept. With a key of another account, a destination is created on the new account, and the mappings point to prices the new account doesn’t sell: delete them and map the new account’s prices.

Disconnect Paddle

Click Disconnect on the Paddle card. LicenseManager deletes the notification destination from your Paddle account, then the connection and all its price mappings, for every product of the organization in that mode. The licenses it created stay. Then revoke the API key in Paddle.

Troubleshooting

“This isn’t a Paddle Billing API key”: you pasted something else, like a client-side token (live_… or test_…). Copy the API key, starting with pdl_.

“This is a sandbox key: live products need a live key”, or the opposite: create the key in the other account, or connect from a test product.

“Paddle rejected the API key”: the key was mistyped, revoked or expired. Create a new one.

“The API key lacks these permissions: …”: edit the key in Paddle to give it the listed permissions, and try again.

“The Paddle account already has 10 active notification destinations”: deactivate one you don’t use, and try again.

“Paddle couldn’t be reached”: try again in a few minutes.