Skip to main content
To connect Paddle, Qonversion needs a Paddle API key. Qonversion uses this key to register the webhook destination on your Paddle account automatically (you don’t need to create the webhook yourself) and to read your products, transactions, subscriptions, refunds, and customers so it can grant entitlements and report revenue.

​
Required permissions

Grant the API key the permissions below when you create it. Qonversion validates the key on connect and reports a missing Notification settings: Write scope explicitly, but the read scopes are required for ongoing processing — a key without them connects but then fails to sync data or map customers to users.
Paddle entityAccessUsed for
Notification settingsRead & WriteRegistering and verifying the webhook destination Qonversion creates for you
ProductsReadValidating the key on connect and matching your Paddle products
TransactionsReadReading purchase / transaction details for analytics and entitlements
SubscriptionsReadTracking renewals, plan changes, and cancellations
AdjustmentsReadDetecting refunds
CustomersReadResolving the buyer to a Qonversion user (the custom_data fallback — see Send Paddle Purchases to Qonversion)

​
1. Get your Paddle API key

Paddle keeps Production and Sandbox in fully separate environments, each with its own API key. Generate the key in the environment you want to connect. Create a new API key (or copy an existing one) with the permissions listed in Required permissions above, and copy its value.
Treat the API key like a password. Paddle shows it in full only once when created — copy it immediately. After you connect it, Qonversion only ever displays a masked value, never the full key.

​
2. Paste the key into Qonversion

  1. Open Project Settings → Stores in the Qonversion dashboard and find the Paddle card.
  2. Click Configure Paddle to open the Paddle drawer. Production and Sandbox are managed side by side.
  3. In the matching mode section, paste your API key into the API Key field and click Connect Production or Connect Sandbox.
Once connected, the section shows a Connected badge and the masked key. Qonversion registers the webhook destination on your Paddle account at this point — there is no separate webhook secret to paste.

​
3. Verify the connection

After connecting, use the buttons in the Paddle drawer to confirm everything works:
  • Test Connection — checks that the saved API key is valid.
  • Test Webhook (Sandbox) — confirms a webhook fired by Paddle reaches Qonversion.
A green result means the credentials are valid and Qonversion is receiving Paddle notifications. If a test fails, double-check that you copied the key for the correct environment and that it has all of the required permissions — in particular Notification settings: Write.
If connecting fails because a Paddle notification destination already exists for this webhook URL but wasn’t created by Qonversion, delete (or rename) that destination in Paddle under Developer Tools → Notifications, then connect again.
Make sure to connect your Production API key before going live. Sandbox credentials cannot process real charges.
Paddle Integration Test Purchases — Paddle