> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.qonversion.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Paddle Integration

> Connect your Paddle account to Qonversion

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.

<Info>
  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.
</Info>

## 1. Connect your Paddle account to Qonversion

Find the **Paddle** card in the Stores tab of your project settings in the [Qonversion dashboard](https://dash.qonversion.io/project-settings/stores) 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](paddle-credentials) for where to get the API key.

<Info>
  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](paddle-credentials#required-permissions) (Notification settings read+write, plus read access on products, transactions, subscriptions, adjustments, and customers).
</Info>

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](https://vendors.paddle.com/products-v2) (or the [sandbox dashboard](https://sandbox-vendors.paddle.com/products-v2) for testing).

A Paddle product can have multiple prices — more about setting up Paddle catalog products in [Paddle official documentation](https://developer.paddle.com/build/products/create-products-prices).

You can use the Paddle dashboard to create a subscription manually, but the most common way is to use [Paddle Checkout](https://developer.paddle.com/build/checkout/build-overlay-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](https://developer.paddle.com/api-reference/overview).

## 3. Add your Paddle products to Qonversion

<Info>
  Skip this step if you are not using the [Qonversion Subscription Management mode](subscription-management-mode).
</Info>

Add your Paddle products to the [dashboard](https://dash.qonversion.io/entitlements/products) 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](https://vendors.paddle.com/products-v2).

## 4. Link Paddle purchases to a Qonversion user

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.

<CodeGroup>
  ```javascript Paddle.js overlay checkout theme={null}
  Paddle.Checkout.open({
    items: [{ priceId: 'pri_01hv4rrk', quantity: 1 }],
    customData: {
      qonversion_client_uid: '<QONVERSION_USER_ID>',
    },
  });
  ```
</CodeGroup>

<Info>
  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](initiate-purchase-paddle) for the customer-level fallback and how to obtain the Qonversion User ID.
</Info>

Alternatively, you can submit the completed purchase yourself from your server via the [API endpoint](/reference/overview), or from the browser with the [Qonversion Web SDK](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](initiate-purchase-paddle) for the full reference. Then send them to Qonversion:

<CodeGroup>
  ```bash curl theme={null}
  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"
      }
    }'
  ```
</CodeGroup>

| Qonversion request field             | Source                                                                                 |
| ------------------------------------ | -------------------------------------------------------------------------------------- |
| currency                             | transaction currency code                                                              |
| price                                | transaction total                                                                      |
| purchased                            | Unix-epoch seconds when the Paddle Checkout completed                                  |
| paddle\_store\_data.type             | `subscription` for recurring products, `non_recurring` for one-time purchases          |
| paddle\_store\_data.transaction\_id  | Paddle transaction id (`txn_`)                                                         |
| paddle\_store\_data.subscription\_id | Paddle subscription id (`sub_`). Required for `subscription`; omit for `non_recurring` |
| paddle\_store\_data.product\_id      | Paddle product id (`pro_`)                                                             |

See [Send Paddle Purchases to Qonversion](initiate-purchase-paddle) 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](test-purchase-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](stripe-integration)

[Web SDK](web-sdk)