Skip to main content
Qonversion supports Paddle web payments. This integration allows Qonversion to manage cross-platform subscribers’ access and provide analytics for payments made via Paddle on your website.
In case you are selling digital goods, you can not promote web payment options in your mobile app as it goes against the app stores’ policies.

​
1. Connect your Paddle account to Qonversion

Find the Paddle card in the Stores tab of your project settings in the Qonversion dashboard and click Configure Paddle. Qonversion manages Production and Sandbox side by side — you can connect either or both. For each mode, paste the Paddle API key and click Connect Production or Connect Sandbox. See Paddle Credentials for where to get the API key.
Qonversion registers the webhook destination on your Paddle account automatically — you don’t need to wire it up in Paddle. The API key must carry the required permissions (Notification settings read+write, plus read access on products, transactions, subscriptions, adjustments, and customers).
Once connected, Qonversion streams subscriptions, renewals, and refunds from Paddle into your project. You have complete control over your Paddle account and can disconnect whenever you want.

​
2. Create Paddle products

You can create products using the Paddle dashboard (or the sandbox dashboard for testing). A Paddle product can have multiple prices — more about setting up Paddle catalog products in Paddle official documentation. You can use the Paddle dashboard to create a subscription manually, but the most common way is to use Paddle Checkout on your website to collect the customer’s payment information. You can check the details of working with Paddle subscriptions using the API here.

​
3. Add your Paddle products to Qonversion

Skip this step if you are not using the Qonversion Subscription Management mode.
Add your Paddle products to the dashboard to manage cross-platform subscribers’ access. Make sure that the Paddle Product Identifier that you provide to Qonversion matches your Product ID in Paddle (it starts with pro_). You can find your Product ID in the Paddle Catalog on the product page. Every Paddle purchase must be linked to a Qonversion user. The recommended way is to tag the Paddle Checkout with the buyer’s Qonversion User ID in custom_data — Qonversion reads it from the Paddle webhook and grants entitlements and tracks revenue automatically, including for later renewals, refunds, and cancellations. No purchase-submission call is required. 
Paddle.Checkout.open({
  items: [{ priceId: 'pri_01hv4rrk', quantity: 1 }],
  customData: {
    qonversion_client_uid: '<QONVERSION_USER_ID>',
  },
});
The key must be exactly qonversion_client_uid, and its value is the Qonversion User ID (the qonversionId from the SDK’s userInfo()). If a transaction’s custom_data is empty, Qonversion falls back to the Paddle customer’s custom_data. See Send Paddle Purchases to Qonversion for the customer-level fallback and how to obtain the Qonversion User ID.
Alternatively, you can submit the completed purchase yourself from your server via the API endpoint, or from the browser with the Qonversion Web SDK. Capture the Paddle identifiers from the completed transaction — the transaction_id (txn_), the product_id (pro_), and, for subscriptions, the subscription_id (sub_). Note that the subscription_id is created asynchronously and is not in the client-side checkout.completed event — read it from the transaction.completed / subscription.created webhook (or GET /transactions/{id}) before submitting. See Send Paddle Purchases to Qonversion for the full reference. Then send them to Qonversion: 
curl --request POST \
  --url https://api.qonversion.io/v3/users/{user_id}/purchases \
  --header 'Authorization: Bearer {project_key}' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "currency": "USD",
    "price": "11.99",
    "purchased": 1653458781,
    "paddle_store_data": {
      "type": "subscription",
      "transaction_id": "txn_01hv4rrk",
      "subscription_id": "sub_01hv4rrk",
      "product_id": "pro_01hv4rrk"
    }
  }'
Qonversion request fieldSource
currencytransaction currency code
pricetransaction total
purchasedUnix-epoch seconds when the Paddle Checkout completed
paddle_store_data.typesubscription for recurring products, non_recurring for one-time purchases
paddle_store_data.transaction_idPaddle transaction id (txn_)
paddle_store_data.subscription_idPaddle subscription id (sub_). Required for subscription; omit for non_recurring
paddle_store_data.product_idPaddle product id (pro_)
See Send Paddle Purchases to Qonversion for the full request reference and the Web SDK alternative. Qonversion updates data on Paddle subscriptions automatically. Usually, it happens with a slight delay compared to its actual state in Paddle.

​
5. Test your integration

Verify the connection end to end using the Paddle sandbox before going live. See Test Purchases — Paddle.

​
Limitations

Proration Subscription changes such as upgrades or downgrades can result in prorated amounts. A prorated charge (typically on an upgrade) arrives as a transaction and is counted in revenue at its prorated amount. A prorated credit (typically on a downgrade) is issued by Paddle as an adjustment and is not reflected in Qonversion’s revenue. Cancellations Paddle supports cancelling a subscription immediately or at the end of the current billing period (similar to in-app subscriptions on the app stores). Qonversion treats the cancellation as the terminal “expired” event and updates the subscriber’s access accordingly. Coupons, discounts, and price changes Qonversion will take into account price changes, including discounts, applied to a subscription in revenue calculation. Refunds Qonversion tracks only full refunds. Proration or partial refunds are not supported currently.
Stripe Integration Web SDK