Skip to main content

Initial integration with Paddle

Adapty lets you manage subscriptions and purchases from both your mobile app and website in one place. The Paddle integration enables you to:

  • Collect subscription data from both in-app purchases and website purchases in a single system
  • Grant access to paid features in your mobile app to users who purchased on your website
  • View analytics and subscription data from all sales channels in one dashboard
note

Apple now allows US App Store apps to include links to external payment systems, though apps may still need to offer in-app purchases alongside external options. Check the current App Store guidelines for your region and app category.

To set up the Paddle integration, follow these steps:

1. Connect Paddle to Adapty​

The integration uses webhooks to send subscription data from Paddle to Adapty. To connect your Adapty and Paddle accounts, you'll need to:

  1. Provide your Paddle API keys.
  2. Add Adapty's webhook URL to Paddle.
note

The steps below apply to both Production and Test. You can configure both simultaneously. The links provided are for the Production environment — to get the Test environment links, simply add sandbox- at the beginning of each URL. For example, use https://sandbox-vendors.paddle.com/authentication-v2 instead of https://vendors.paddle.com/authentication-v2.

1.1. Get and add Paddle API keys​

  1. In Paddle, go to Developer Tools → Authentication and click New API key.
  1. Give the key a name and set the expiration date. For the API key to work with Adapty, you need to grant it the Read permission for all entities. Click Save.
  1. Click Copy key.
  1. In Adapty, go to App Settings → Paddle and paste the key in the Paddle API key section.
warning

If you set an expiration date for your Paddle API key, you must manually generate a new key and update it in Adapty before expiration. The integration will stop working without warning when the key expires, and users won't be able to make purchases.

1.2. Add events that will be sent to Adapty​

  1. Copy the Webhook URL from the same Paddle page in Adapty.
  2. In Paddle, go to Developer Tools → Notifications and click New destination to add a webhook.

  1. Enter a descriptive name for the webhook. We recommend including "Adapty" in it, so you can easily find it when needed.

  2. Paste the Webhook URL from Adapty into the URL field. Ensure you are using the webhook for the right environment.

  3. Set Notification type to Webhook.

  1. Select the following events:

    • subscription.created

    • subscription.updated

    • transaction.created

    • transaction.updated

    • adjustment.created

    • adjustment.updated

  1. Click Save destination to finalize the webhook setup.

1.3. Retrieve and add the webhook secret key​

  1. In the Notifications window, click the three dots next to the webhook you just created and select Edit destination.
  2. A new field called the Secret key will appear in the Edit destination panel. Copy it.

  1. In Adapty, go to App Settings → Paddle and paste the key into the Notification secret key field. This key is used to verify webhook data in Adapty.

1.4. Match Paddle customers with Adapty profiles​

Adapty needs to link each purchase to a customer profile so it can be used in your app. By default, profiles are created automatically when Adapty receives webhooks from Paddle. You can choose which value to use as the customer_user_id in Adapty:

  1. Default and recommended: The customer_user_id you pass in the custom_data field (see Paddle docs)
  2. The email from the Paddle Customer object (see Paddle docs)
  3. The Paddle Customer ID in the ctm-... format (see Paddle docs)
  4. Don't create profiles. Choose this option if you want to have more control over your customer profiles and handle it yourself.

You can configure which value to use in the Profile creation behavior field in App Settings → Paddle.

2. Add Paddle products to Adapty​

warning

Be sure to add your Paddle products to the Adapty Dashboard or add a Paddle product ID to your existing products. Adapty only tracks events for transactions tied to these products. If you skip this step, transaction events won't be created.

Paddle works in Adapty just like App Store and Google Play — it's another platform where you sell digital products. To configure it, add the relevant product_id and price_id values from Paddle in the Products section in Adapty.

In Paddle, product IDs look like pro_... and price IDs like pri_.... You'll find them in your Paddle product catalog once you open a specific product:

Once your products are added, the next step is ensuring Adapty can link the purchase to the right user.

3. Provide access to users on the mobile​

To ensure users who buy on the web get access on mobile, call Adapty.activate() or Adapty.identify() using the same customer_user_id you passed when the purchase was made. See Identifying users for details.

4. Test your integration​

Once everything's set up, you can test your integration. Transactions made in Paddle's Test environment will appear as Test in Adapty. Transactions from the Production environment will appear as Production.

Your integration is now complete. Users can purchase subscriptions on your website and automatically access premium features in your mobile app, while you track all subscription analytics from your unified Adapty dashboard.

Important considerations​

  • In Adapty's analytics, transaction amounts include taxes and Paddle fees, which differs from Paddle's dashboard where amounts are shown after taxes and fees. This means the numbers you see in Adapty will be higher than those in your Paddle dashboard.
  • Unlike other stores, refunds in Paddle only affect the specific transaction being refunded and do not automatically cancel the subscription. The subscription will continue to be active unless explicitly canceled.
  • You can also include variation_id in the custom_data field to attribute purchases to specific paywall instances. Adapty will process this data from webhooks and include it in analytics.

When working with paid trials in Paddle, you need to create two products in Adapty:

  1. Create a non-subscription product and link it to the Paddle price that charges for the trial period.
  2. Then create a subscription product (Monthly/Weekly/etc.) and link it to the Paddle price that has the free trial component.

From Paddle's perspective, this is one product with two prices in a single transaction - one price for the trial charge (e.g., $0.99) and another price for the free trial ($0.00).

From Adapty's perspective, this creates two separate events: a non-subscription purchase for the trial payment and a trial started event for the subscription product.

For example, when a user starts a $0.99 paid trial for a $9.99/month subscription, Paddle creates one transaction with both prices, while Adapty processes this as a non-subscription purchase of $0.99 (immediate payment) and a trial started event at $0.00 (future subscription at $9.99/month).

note

When users cancel a paid trial, you get the Trial expired and Trial renewal canceled events.

Get more from your Paddle data​

important

For your Paddle events to work with integrations, your users must be logged into the app using their App Store/Google Play account at least once.

Once you integrate with Paddle, Adapty is ready to provide insights right away. To make the most of your Paddle data, you can set up additional Adapty integrations to forward Paddle events—bringing all your subscription analytics into a single Adapty Dashboard.

Integrations you can use to forward and analyze your Paddle events:

Current limitations​

  • Cancellations: Paddle has two subscription cancellation options:

    1. Immediate cancellation: The subscription is canceled immediately.

    2. Cancellation at the end of the period: The subscription cancels at the end of the current billing period (similar to in-app subscriptions on the app stores).

  • Refunds: Adapty tracks full and partial refunds.

  • Grace period: Paddle has a fixed grace period of 30 days for billing issues, which cannot be customized. During this period, the subscription remains active even if there are billing issues. This means users will continue to have access to premium features for the full grace period duration, regardless of payment status.

    Note that for trials, there is no grace period - if there is a billing issue after a trial, the subscription will be cancelled immediately.

See also: