From 77282eff04bbd4f4225d45b6e4183525bd65d952 Mon Sep 17 00:00:00 2001 From: Ed Shelley Date: Thu, 27 Nov 2025 17:10:15 +0100 Subject: [PATCH 1/3] first commit for paddle GA --- docs/web/guides/paddle-app-to-web.mdx | 2 - docs/web/integrations/paddle.mdx | 201 ++++++++++++++++++++++---- docs/web/payment-integrations.mdx | 7 +- docs/web/web-billing/web-sdk.mdx | 2 +- sidebars.ts | 2 +- 5 files changed, 177 insertions(+), 37 deletions(-) diff --git a/docs/web/guides/paddle-app-to-web.mdx b/docs/web/guides/paddle-app-to-web.mdx index 5f78048ed..6a9dff87f 100644 --- a/docs/web/guides/paddle-app-to-web.mdx +++ b/docs/web/guides/paddle-app-to-web.mdx @@ -19,10 +19,8 @@ This guide walks you through the setup for adding web purchases to your iOS app ## Current limitations -1. **Free trials** will not be displayed in the package selection page, or summarized in the checkout 1. **Product quantity:** Products purchased with a quantity of more than one (via the quantity adjustment in the Paddle checkout) will be reflected as a single product purchase in RevenueCat. 1. **Customization:** The Paddle overlay checkout only supports a single accent color customization. -1. **Product descriptions:** The "show product descriptions" setting in web purchase links currently has no effect with Paddle purchases. ## Before you begin (prerequisites) diff --git a/docs/web/integrations/paddle.mdx b/docs/web/integrations/paddle.mdx index ca46c9842..42f43da47 100644 --- a/docs/web/integrations/paddle.mdx +++ b/docs/web/integrations/paddle.mdx @@ -5,7 +5,7 @@ excerpt: Allow your users to subscribe to your app via Paddle hidden: false --- -RevenueCat currently supports web payments through Paddle. This allows you to let subscribers subscribe on your own website using Paddle, and automatically unlock access based on the Paddle subscription through the _Purchases SDK_. +RevenueCat currently supports web payments through Paddle. :::info April 2025 U.S. District Court Ruling on External Payment Options A recent U.S. District Court ruling found Apple in violation of a 2021 injunction meant to allow developers to direct users to external payment options, like Paddle. As a result, iOS developers are now permitted to guide users to web-based payment flows without additional Apple fees or restrictive design requirements. You can [find more details on the RevenueCat blog](https://revenuecat.com/blog/growth/introducing-web-paywall-buttons). @@ -13,50 +13,191 @@ A recent U.S. District Court ruling found Apple in violation of a 2021 injunctio For apps available outside the U.S. App Store, Apple still requires that digital goods and subscriptions be purchased through in-app purchases. Promoting or linking to alternative payment methods within the app for non-U.S. users may lead to app review rejection or removal. Always ensure external payment links are shown only to eligible U.S. users. -## 1. Create a new Paddle app +### Supported functionality: -Paddle has a different environment for sandbox and production. As environments are independent, you will need to create a new Paddle app for each environment and mark it as sandbox if it's connected to sandbox, otherwise it will be marked as production. +- **Importing Paddle purchases to RevenueCat**: Let subscribers purchase on your own website using Paddle, and automatically unlock mobile entitlements based on the Paddle subscription. +- **Embedded checkout (Web SDK)**: Use RevenueCat's [purchases-js SDK](../web-billing/web-sdk) to initialize a purchase in your web app that uses a Paddle checkout, and creates subscriptions in Paddle Billing. +- **Embedded checkout (Web Purchase Links)**: Create a [revenuecat-hosted purchase flow](../web-billing/web-purchase-links) which uses a Paddle checkout, and creates subscriptions in Paddle Billing. +- **Redemption Links**: Allow users to purchase anonymously without logging in, and handle purchase redemption in your mobile app. -![](/docs_images/web/paddle/new-app.png) +:::info Subscriptions, products and prices are managed in Paddle +For all of the above features, Paddle acts as the billing engine and merchant of record. This means that Paddle operates the subscription, sends receipts and emails to subscribers, and handles any subscription management. RevenueCat's Web Billing features such has Customer Portal, product configuration and tax handling are not used when integrating with Paddle. +::: + +## 1. Configure your Paddle account + +:::info Do this in Paddle, for: + +- Sandbox ([https://sandbox-vendors.paddle.com/](https://sandbox-vendors.paddle.com/)) +- Production ([https://login.paddle.com/](https://login.paddle.com/)) + ::: + +### Add a registered payment domain + +1. Go to the **Website approval** page under Checkout +1. Click **Add a new domain** +1. Enter `pay.rev.cat` +1. Click **Submit for Approval** + +:::info Domain approval required on production + +In your production account, You'll need to Wait for approval from after adding the payment domain. No approval is required on sandbox accounts. + +::: + +### Set a default payment link + +Go to the [Checkout settings](https://sandbox-vendors.paddle.com/checkout-settings) page under Checkout. + +If your Paddle account does not already have a default payment link set, enter `https://pay.rev.cat`. -### 1.1. Defining Paddle API Key permissions +If a default payment link is already configured (because you're using the account for other purposes) you can leave this unchanged. It will not affect your app-to-web purchases. -The minimum list of required [permissions](https://developer.paddle.com/api-reference/about/permissions) for the created API key are: +### Disable abandoned cart emails + +The RevenueCat Paddle Billing integration doesn't currently support Paddle's abandoned cart emails. You should disable them [here](https://developer.paddle.com/build/checkout/checkout-recovery#configure-checkout-recovery) + +### Add a new API key and define permissions + +1. Navigate to the [Authentication](https://sandbox-vendors.paddle.com/authentication-v2) page under Developer Tools +1. Click the **+ New API key** button +1. Give the new key a suitable name and description +1. **Important:** Set the key to NOT expire (differs from default) +1. Set the permissions according to the list below +1. Save the new key +1. Copy the key to your clipboard
- Show list -- `product.read` -- `price.read` -- `discount.read` -- `customer.read` -- `address.read` -- `business.read` -- `payment_method.read` -- `transaction.read` -- `subscription.read` -- `adjustment.read` -- `notification.read` -- `notification_setting.read` -- `notification_setting.write` -- `client_token.read` -- `client_token.write` + Minimum required API key permissions + +| Permission | Read | Write | +| ------------------------------ | :--: | :---: | +| Addresses | ☑ | ☐ | +| Adjustments | ☑ | ☐ | +| Businesses | ☑ | ☐ | +| Client-side tokens | ☑ | ☑ | +| Customer portal sessions | ☐ | ☐ | +| Customer authentication tokens | ☐ | ☐ | +| Customers | ☑ | ☐ | +| Discounts | ☑ | ☐ | +| Notification settings | ☑ | ☑ | +| Notifications | ☑ | ☐ | +| Notification simulations | ☐ | ☐ | +| Payment methods | ☑ | ☐ | +| Prices | ☑ | ☐ | +| Products | ☑ | ☐ | +| Reports | ☐ | ☐ | +| Subscriptions | ☑ | ☐ | +| Transactions | ☑ | ☐ | +
-## 2. Create products and prices on Paddle +:::warning leave key window open +If you close the modal showing the full API key, you will no longer be able to copy it — we recommend you leave this window open until you've saved the key in the RevenueCat config. +::: + +## 2. Create Paddle config in RevenueCat dashboard + +:::info Do this in RevenueCat, for: + +- Sandbox +- Production (separate config required) + +::: + +1. Log in to your RevenueCat account +1. Go to your project +1. Go to **Apps & providers** +1. Add a new web configuration +1. Select the Paddle provider +1. Click **Set secret**, paste your Paddle API key and click **Set** + +For this use case, we recommend selecting: + +**Automatic purchase tracking** — this tracks all purchases from the Paddle account using webhooks, with no additional setup required. +**Autogenerated user IDs** — because we're sending users directly from the mobile app, an app user ID will already be provided and associated to the purchase. + +Finally, click **Connect to Paddle** to initiate and test the connection. + +## 3. Create products and prices in Paddle + +:::info Do this in Paddle, for: + +- Sandbox ([https://sandbox-vendors.paddle.com/](https://sandbox-vendors.paddle.com/)) +- Production ([https://login.paddle.com/](https://login.paddle.com/)) + ::: + +:::info Product Mapping between RevenueCat and Paddle +A Price in Paddle maps to a Product in the RevenueCat system. So for example, if you create two prices under the same Paddle product, when you import or manually create the products in the RevenueCat dashboard, you'll notice two separate products. + +![](/docs_images/web/paddle/paddle_dashboard_prices.png) +![](/docs_images/web/paddle/revenuecat_paddle_product_mapping.png) + +::: + +1. Log in to the Paddle Dashboard +1. To create a new product, expand the **Catalog** section in the sidebar and click **Products**. +1. On the top right corner of the page, click **New Product**. +1. Enter the product name and any other optional details like a description then click **Save**. + +![](/docs_images/web/paddle/create-product.png) + +Then on the prices section, click **New Price**. +Enter details like the base price, the type of pricing (recurring or one-time), the billing period, and any trial periods you are offering and click **Save**. + +:::info "price name" is customer-facing label +The "price name" field defines to what is shown to users in the checkout, as a representation of what they're purchasing. +::: + +![](/docs_images/web/paddle/create-price.png) + +You can read more about **products and prices** in [Paddle's official documentation](https://developer.paddle.com/build/products/create-products-prices). + +## 5. Create entitlements in RevenueCat + +:::info Do this in RevenueCat, for: + +- Sandbox +- Production + ::: + +### What is an entitlement? + +RevenueCat Entitlements represent a level of access, features, or content that a user is "entitled" to, and are typically unlocked after a user purchases a product. + +Entitlements are used to ensure a user has appropriate access to content based on their purchases, without having to manage all of the product identifiers in your app code. For example, you can use entitlements to unlock "pro" features after a user purchases a subscription. + +Most apps only have one entitlement, unlocking all premium features. However, if you had two tiers of content such as Gold and Platinum, you would have 2 entitlements. + +[Read more about entitlements](../../getting-started/entitlements) + +### Adding an entitlement -You can create products and prices following the [Paddle Product Setup](/getting-started/entitlements/paddle-products) guide. +1. Go to the **Product catalog** in your RevenueCat dashboard, and select the **Entitlements** tab +1. Click **+ New entitlement** +1. Enter an identifier and description for the entitlement, and click **Add** -## 3. Create subscriptions on Paddle +### Attaching a product to your entitlement -The typical setup consists of a website that uses [Paddle checkout](https://developer.paddle.com/concepts/sell/self-serve-checkout) to tokenize the customer payment information, and send this information to your server. After that, your server will be able to subscribe your customer to a product. +1. Go to your previously created entitlenment and click **Attach** under associated products +1. In the table, check the product from your Paddle provider, and click **Attach** -On the server-side, you can use [Paddle's REST API](https://developer.paddle.com/api-reference/overview) or their library for your favorite programming language. +## 6. Create an offering & packages in RevenueCat -Alternatively, you can also use the Paddle dashboard for manually creating the subscriptions for testing. +:::info Do this in RevenueCat, for: -## 4. Add your Paddle products to your project's entitlements +- Sandbox +- Production + ::: -Add your Paddle products to your project's [entitlements](/getting-started/entitlements) to easily group the products for your app. RevenueCat will send Paddle subscriptions to your app the same way we do for the other app stores. +1. Go to the **Product catalog** in your RevenueCat dashboard, and select the **Offerings** tab +1. Click **New offering** to create a new offering +1. Enter a suitable identifier and display name +1. Under **Packages**, click **+ New Package** +1. Select an identifier that corresponds to the billing cycle of your subscription +1. Enter a description +1. In the products list, find your previously-created Paddle provider and select the corresponding Paddle product (this should correspond with the billing cycle you chose in the identifier) +1. Click **Save** ## 5. Send Paddle tokens to RevenueCat diff --git a/docs/web/payment-integrations.mdx b/docs/web/payment-integrations.mdx index 9f852f889..4d2c53e4f 100644 --- a/docs/web/payment-integrations.mdx +++ b/docs/web/payment-integrations.mdx @@ -7,11 +7,12 @@ hidden: false import ExternalButton from "@site/src/components/ExternalButton"; -RevenueCat currently offers a Stripe Billing and Paddle Billing integrations for syncing external subscriptions and transactions: +RevenueCat supports both Stripe Billing and Paddle Billing as 3rd party billing engine integrations: -See: [Stripe Billing integration](/web/integrations/stripe) and [Paddle Billing integration](/web/integrations/paddle) +- [Stripe Billing integration](/web/integrations/stripe) (external purchase syncing only) +- [Paddle Billing integration](/web/integrations/paddle) (external purchase syncing, embedded checkout in Web Purchase Links and Web SDK) -To request other payment provider integrations, contact our support team or your account manager: +To request other integrations, contact our support team or your account manager: Date: Fri, 28 Nov 2025 12:25:04 +0100 Subject: [PATCH 2/3] new use case-based structure --- docs/web/integrations/paddle.mdx | 187 ++++++++++++++++--------------- 1 file changed, 98 insertions(+), 89 deletions(-) diff --git a/docs/web/integrations/paddle.mdx b/docs/web/integrations/paddle.mdx index 42f43da47..59df6407b 100644 --- a/docs/web/integrations/paddle.mdx +++ b/docs/web/integrations/paddle.mdx @@ -5,59 +5,108 @@ excerpt: Allow your users to subscribe to your app via Paddle hidden: false --- -RevenueCat currently supports web payments through Paddle. +RevenueCat currently supports web payments through Paddle in a number of different configurations. :::info April 2025 U.S. District Court Ruling on External Payment Options A recent U.S. District Court ruling found Apple in violation of a 2021 injunction meant to allow developers to direct users to external payment options, like Paddle. As a result, iOS developers are now permitted to guide users to web-based payment flows without additional Apple fees or restrictive design requirements. You can [find more details on the RevenueCat blog](https://revenuecat.com/blog/growth/introducing-web-paywall-buttons). -::: For apps available outside the U.S. App Store, Apple still requires that digital goods and subscriptions be purchased through in-app purchases. Promoting or linking to alternative payment methods within the app for non-U.S. users may lead to app review rejection or removal. Always ensure external payment links are shown only to eligible U.S. users. +::: -### Supported functionality: +## Supported features: - **Importing Paddle purchases to RevenueCat**: Let subscribers purchase on your own website using Paddle, and automatically unlock mobile entitlements based on the Paddle subscription. -- **Embedded checkout (Web SDK)**: Use RevenueCat's [purchases-js SDK](../web-billing/web-sdk) to initialize a purchase in your web app that uses a Paddle checkout, and creates subscriptions in Paddle Billing. -- **Embedded checkout (Web Purchase Links)**: Create a [revenuecat-hosted purchase flow](../web-billing/web-purchase-links) which uses a Paddle checkout, and creates subscriptions in Paddle Billing. +- **Embedded Paddle checkout (Web SDK)**: Use RevenueCat's [purchases-js SDK](../web-billing/web-sdk) to initialize a purchase in your web app that uses a Paddle checkout, and creates subscriptions in Paddle Billing. +- **Embedded Paddle checkout (Web Purchase Links)**: Create a [revenuecat-hosted purchase flow](../web-billing/web-purchase-links) which uses a Paddle checkout, and creates subscriptions in Paddle Billing. - **Redemption Links**: Allow users to purchase anonymously without logging in, and handle purchase redemption in your mobile app. +- **Web Paywalls**: Present a RevenueCat paywall on the web, attache to a Paddle checkout. +- **Web Purchase Button**: Present a RevenueCat paywall on mobile, which links out to a Paddle web checkout. :::info Subscriptions, products and prices are managed in Paddle For all of the above features, Paddle acts as the billing engine and merchant of record. This means that Paddle operates the subscription, sends receipts and emails to subscribers, and handles any subscription management. RevenueCat's Web Billing features such has Customer Portal, product configuration and tax handling are not used when integrating with Paddle. ::: -## 1. Configure your Paddle account +### Current limitations + +We support purchases that contain only one product. Multiple products on a single purchase are not supported, including one-time setup fees that are included with a subscription purchase. + +## Use cases + +### Use case 1: Using Paddle to import purchases and grant entitlements + +If you want to use a non-RevenueCat purchase flow and simply import purchases in order to grant entitlments to users, follow these steps. This use case doesn't enable any purchases that happen within a RevenueCat purchase flow, but simply import purchases that happen in your Paddle account through external flows (e.g. you integrated Paddle's checkout into your website). + +1. Configure your Paddle account +1. Create a Paddle config in the RevenueCat dashboard and configure purchase tracking +1. Create products and prices in Paddle (skip if already created) +1. Import Paddle products to RevenueCat +1. Create entitlements in RevenueCat + +### Use case 2: Using a Paddle checkout in Web Purchase Links + +1. Configure your Paddle account +1. Create a Paddle config in the RevenueCat dashboard and configure purchase tracking +1. Create products and prices in Paddle (skip if already created) +1. Import Paddle products to RevenueCat +1. Create entitlements in RevenueCat +1. Create an offering and packages in RevenueCat +1. Create and configure a web purchase link for the offering + +### Use case 3: Using a Paddle checkout in an app-to-web flow with RevenueCat Paywalls -:::info Do this in Paddle, for: +1. Configure your Paddle account +1. Create a Paddle config in the RevenueCat dashboard and configure purchase tracking +1. Create products and prices in Paddle (skip if already created) +1. Import Paddle products to RevenueCat +1. Create entitlements in RevenueCat +1. Create an offering and packages in RevenueCat +1. Create a RevenueCat paywall with a web purchase button -- Sandbox ([https://sandbox-vendors.paddle.com/](https://sandbox-vendors.paddle.com/)) -- Production ([https://login.paddle.com/](https://login.paddle.com/)) +### Use case 4: Using a Paddle checkout with the Web SDK + +TBD + +## Step-by-step instructions + +Follow these sections according to the use case you're implementing (above). + +:::info Working with sandbox environments in Paddle +Paddle has entirely separate sandbox accounts that should be created and configured as standalone accounts. Some of the instructions below need to be repeated for both Sandbox and Production accounts. + +- 🟠 Sandbox dashboard URL: ([https://sandbox-vendors.paddle.com/](https://sandbox-vendors.paddle.com/)) +- 🟢 Production dashboard URL: ([https://login.paddle.com/](https://login.paddle.com/)) ::: -### Add a registered payment domain +## Configure your Paddle account + +:::info Do this in Paddle, for both sandbox and production accounts +::: + +#### Configure registered payment domains 1. Go to the **Website approval** page under Checkout 1. Click **Add a new domain** 1. Enter `pay.rev.cat` 1. Click **Submit for Approval** +1. If you're using RevenueCat's Web SDK to host purchases on your own domain, you should repeat the same steps with that domain. -:::info Domain approval required on production +:::warning Manual domain approval required on production -In your production account, You'll need to Wait for approval from after adding the payment domain. No approval is required on sandbox accounts. +In your production account, You'll need to wait for approval from after adding the payment domain. No approval is required on sandbox accounts. ::: -### Set a default payment link +#### Set a default payment link Go to the [Checkout settings](https://sandbox-vendors.paddle.com/checkout-settings) page under Checkout. -If your Paddle account does not already have a default payment link set, enter `https://pay.rev.cat`. - -If a default payment link is already configured (because you're using the account for other purposes) you can leave this unchanged. It will not affect your app-to-web purchases. +If your Paddle account does not already have a default payment link set, enter `https://pay.rev.cat`. If a default payment link is already configured (because you're using the account for other purposes) you can leave this unchanged. It will not affect your app-to-web purchases. -### Disable abandoned cart emails +#### Disable abandoned cart emails The RevenueCat Paddle Billing integration doesn't currently support Paddle's abandoned cart emails. You should disable them [here](https://developer.paddle.com/build/checkout/checkout-recovery#configure-checkout-recovery) -### Add a new API key and define permissions +#### Add a new API key and define permissions 1. Navigate to the [Authentication](https://sandbox-vendors.paddle.com/authentication-v2) page under Developer Tools 1. Click the **+ New API key** button @@ -96,36 +145,45 @@ The RevenueCat Paddle Billing integration doesn't currently support Paddle's aba If you close the modal showing the full API key, you will no longer be able to copy it — we recommend you leave this window open until you've saved the key in the RevenueCat config. ::: -## 2. Create Paddle config in RevenueCat dashboard +## Create Paddle config in RevenueCat dashboard and configure purchase tracking -:::info Do this in RevenueCat, for: - -- Sandbox -- Production (separate config required) - -::: - -1. Log in to your RevenueCat account +1. Log into your RevenueCat account 1. Go to your project 1. Go to **Apps & providers** 1. Add a new web configuration 1. Select the Paddle provider 1. Click **Set secret**, paste your Paddle API key and click **Set** +1. **Configure purchase tracking**: -For this use case, we recommend selecting: +For most use cases, we recommend selecting the following: -**Automatic purchase tracking** — this tracks all purchases from the Paddle account using webhooks, with no additional setup required. -**Autogenerated user IDs** — because we're sending users directly from the mobile app, an app user ID will already be provided and associated to the purchase. +- **Automatic purchase tracking** — this tracks all purchases from the Paddle account using webhooks, with no additional setup required. +- **Autogenerated user IDs** — because we're sending users directly from the mobile app, an app user ID will already be provided and associated to the purchase. Read more about [tracking purchases from server-to-server notifications](/platform-resources/server-notifications/paddle-server-notifications#tracking-new-purchases-using-paddle-server-notifications). Finally, click **Connect to Paddle** to initiate and test the connection. -## 3. Create products and prices in Paddle +#### Manual purchase tracking (optional, advanced) -:::info Do this in Paddle, for: +You can send your Paddle subscriptions to RevenueCat through the [POST receipt endpoint](/migrating-to-revenuecat/migrating-existing-subscriptions/receipt-imports). -- Sandbox ([https://sandbox-vendors.paddle.com/](https://sandbox-vendors.paddle.com/)) -- Production ([https://login.paddle.com/](https://login.paddle.com/)) - ::: +The only required fields when sending your Paddle purchase to the RevenueCat API are the following: + +- `fetch_token`: Your Paddle subscription ID (`sub_...`) OR your Paddle transaction ID (`txn_...`) +- `app_user_id`: The App User ID that the subscription should be applied to + +**Headers** + +- `X-Platform`: Should be set to `paddle`. +- `Authorization`: It should be `Bearer YOUR_REVENUECAT_PADDLE_APP_PUBLIC_API_KEY` + +import curlContent from "@site/code_blocks/getting-started/paddle_1.curl?raw"; + + + +## Create products and prices in Paddle + +:::info Do this in Paddle, for sandbox and production. +::: :::info Product Mapping between RevenueCat and Paddle A Price in Paddle maps to a Product in the RevenueCat system. So for example, if you create two prices under the same Paddle product, when you import or manually create the products in the RevenueCat dashboard, you'll notice two separate products. @@ -153,15 +211,9 @@ The "price name" field defines to what is shown to users in the checkout, as a r You can read more about **products and prices** in [Paddle's official documentation](https://developer.paddle.com/build/products/create-products-prices). -## 5. Create entitlements in RevenueCat +## Create entitlements in RevenueCat -:::info Do this in RevenueCat, for: - -- Sandbox -- Production - ::: - -### What is an entitlement? +#### What is an entitlement? RevenueCat Entitlements represent a level of access, features, or content that a user is "entitled" to, and are typically unlocked after a user purchases a product. @@ -171,24 +223,18 @@ Most apps only have one entitlement, unlocking all premium features. However, if [Read more about entitlements](../../getting-started/entitlements) -### Adding an entitlement +#### Adding an entitlement 1. Go to the **Product catalog** in your RevenueCat dashboard, and select the **Entitlements** tab 1. Click **+ New entitlement** 1. Enter an identifier and description for the entitlement, and click **Add** -### Attaching a product to your entitlement +#### Attaching a product to your entitlement 1. Go to your previously created entitlenment and click **Attach** under associated products 1. In the table, check the product from your Paddle provider, and click **Attach** -## 6. Create an offering & packages in RevenueCat - -:::info Do this in RevenueCat, for: - -- Sandbox -- Production - ::: +## Create an offering & packages in RevenueCat 1. Go to the **Product catalog** in your RevenueCat dashboard, and select the **Offerings** tab 1. Click **New offering** to create a new offering @@ -198,40 +244,3 @@ Most apps only have one entitlement, unlocking all premium features. However, if 1. Enter a description 1. In the products list, find your previously-created Paddle provider and select the corresponding Paddle product (this should correspond with the billing cycle you chose in the identifier) 1. Click **Save** - -## 5. Send Paddle tokens to RevenueCat - -:::danger Crucial step -Failure to complete this step will result in untracked Paddle subscriptions in RevenueCat. -::: - -The following sections provide step-by-step instructions for two methods of sending Paddle tokens to RevenueCat. Whether you prefer a manual integration through the API or automated processing using the "Track new purchases from server-to-sever notifications" feature, this section will guide you in setting up your configuration to ensure all purchases are tracked. - -### Manually through our API - -You can send your Paddle subscriptions to RevenueCat through the [POST receipt endpoint](/migrating-to-revenuecat/migrating-existing-subscriptions/receipt-imports). - -The only required fields when sending your Paddle purchase to the RevenueCat API are the following: - -- `fetch_token`: Your Paddle subscription ID (`sub_...`) OR your Paddle transaction ID (`txn_...`) -- `app_user_id`: The App User ID that the subscription should be applied to - -**Headers** - -- `X-Platform`: Should be set to `paddle`. -- `Authorization`: It should be `Bearer YOUR_REVENUECAT_PADDLE_APP_PUBLIC_API_KEY` - -import curlContent from "@site/code_blocks/getting-started/paddle_1.curl?raw"; - - - -### Track new purchases from server-to-server-notifications - -RevenueCat can automatically process Paddle tokens sent through server-to-server notifications. To enable automatic processing of Paddle purchases, ensure the following features are enabled: - -- [Paddle Server Notifications](/platform-resources/server-notifications/paddle-server-notifications) -- [Track new purchases from server-to-server notifications](/platform-resources/server-notifications/paddle-server-notifications#tracking-new-purchases-using-paddle-server-notifications) - -## Limitations of the Paddle integration - -- We support purchases that contain only one product. Multiple products on a single purchase are not supported. From a734cb53f34ed7a299f3c16fc168f4044d788b89 Mon Sep 17 00:00:00 2001 From: Ed Shelley Date: Fri, 28 Nov 2025 14:50:56 +0100 Subject: [PATCH 3/3] mostly complete paddle doc --- docs/web/integrations/paddle.mdx | 150 ++++++++++++++++++++++++++----- docs/web/web-billing/web-sdk.mdx | 15 ++-- 2 files changed, 136 insertions(+), 29 deletions(-) diff --git a/docs/web/integrations/paddle.mdx b/docs/web/integrations/paddle.mdx index 59df6407b..3c765d825 100644 --- a/docs/web/integrations/paddle.mdx +++ b/docs/web/integrations/paddle.mdx @@ -15,7 +15,7 @@ For apps available outside the U.S. App Store, Apple still requires that digital ## Supported features: -- **Importing Paddle purchases to RevenueCat**: Let subscribers purchase on your own website using Paddle, and automatically unlock mobile entitlements based on the Paddle subscription. +- **Import and sync external Paddle purchases**: Let subscribers purchase on your own website using Paddle, and use them to unlock mobile entitlements for your users. - **Embedded Paddle checkout (Web SDK)**: Use RevenueCat's [purchases-js SDK](../web-billing/web-sdk) to initialize a purchase in your web app that uses a Paddle checkout, and creates subscriptions in Paddle Billing. - **Embedded Paddle checkout (Web Purchase Links)**: Create a [revenuecat-hosted purchase flow](../web-billing/web-purchase-links) which uses a Paddle checkout, and creates subscriptions in Paddle Billing. - **Redemption Links**: Allow users to purchase anonymously without logging in, and handle purchase redemption in your mobile app. @@ -32,39 +32,52 @@ We support purchases that contain only one product. Multiple products on a singl ## Use cases +Choose the relevant use case below, then follow each section to implement it. + ### Use case 1: Using Paddle to import purchases and grant entitlements If you want to use a non-RevenueCat purchase flow and simply import purchases in order to grant entitlments to users, follow these steps. This use case doesn't enable any purchases that happen within a RevenueCat purchase flow, but simply import purchases that happen in your Paddle account through external flows (e.g. you integrated Paddle's checkout into your website). -1. Configure your Paddle account -1. Create a Paddle config in the RevenueCat dashboard and configure purchase tracking -1. Create products and prices in Paddle (skip if already created) -1. Import Paddle products to RevenueCat -1. Create entitlements in RevenueCat +1. [Configure your Paddle account](#configure-your-paddle-account) +1. [Create a Paddle config and configure purchase tracking](#create-a-paddle-config-and-configure-purchase-tracking) +1. [Create products and prices in Paddle](#create-products-and-prices-in-paddle) (skip if already created) +1. [Import Paddle products to RevenueCat](#import-paddle-products-to-revenuecat) +1. [Create entitlements in RevenueCat](#create-entitlements-in-revenuecat) ### Use case 2: Using a Paddle checkout in Web Purchase Links -1. Configure your Paddle account -1. Create a Paddle config in the RevenueCat dashboard and configure purchase tracking -1. Create products and prices in Paddle (skip if already created) -1. Import Paddle products to RevenueCat -1. Create entitlements in RevenueCat -1. Create an offering and packages in RevenueCat -1. Create and configure a web purchase link for the offering +1. [Configure your Paddle account](#configure-your-paddle-account) +1. [Create a Paddle config and configure purchase tracking](#create-a-paddle-config-and-configure-purchase-tracking) +1. [Configure purchase redemption on mobile with Redemption Links](#configure-purchase-redemption-on-mobile-with-redemption-links) (optional) +1. [Create products and prices in Paddle](#create-products-and-prices-in-paddle) (skip if already created) +1. [Import Paddle products to RevenueCat](#import-paddle-products-to-revenuecat) +1. [Create entitlements in RevenueCat](#create-entitlements-in-revenuecat) +1. [Create an offering and packages in RevenueCat](#create-an-offering--packages-in-revenuecat) +1. [Create and configure a web purchase link](#create-and-configure-a-web-purchase-link) +1. [Test the purchase flow in Sandbox](#testing-in-sandbox) ### Use case 3: Using a Paddle checkout in an app-to-web flow with RevenueCat Paywalls -1. Configure your Paddle account -1. Create a Paddle config in the RevenueCat dashboard and configure purchase tracking -1. Create products and prices in Paddle (skip if already created) -1. Import Paddle products to RevenueCat -1. Create entitlements in RevenueCat -1. Create an offering and packages in RevenueCat -1. Create a RevenueCat paywall with a web purchase button +1. [Configure your Paddle account](#configure-your-paddle-account) +1. [Create a Paddle config and configure purchase tracking](#create-a-paddle-config-and-configure-purchase-tracking) +1. [Create products and prices in Paddle](#create-products-and-prices-in-paddle) (skip if already created) +1. [Import Paddle products to RevenueCat](#import-paddle-products-to-revenuecat) +1. [Create entitlements in RevenueCat](#create-entitlements-in-revenuecat) +1. [Create an offering and packages in RevenueCat](#create-an-offering--packages-in-revenuecat) +1. [Create a RevenueCat paywall with a web purchase button](#create-and-configure-a-web-purchase-link) +1. [Test the purchase flow in Sandbox](#testing-in-sandbox) ### Use case 4: Using a Paddle checkout with the Web SDK -TBD +1. [Configure your Paddle account](#configure-your-paddle-account) +1. [Create a Paddle config and configure purchase tracking](#create-a-paddle-config-and-configure-purchase-tracking) +1. [Configure purchase redemption on mobile with Redemption Links](#configure-purchase-redemption-on-mobile-with-redemption-links) (optional) +1. [Create products and prices in Paddle](#create-products-and-prices-in-paddle) (skip if already created) +1. [Import Paddle products to RevenueCat](#import-paddle-products-to-revenuecat) +1. [Create entitlements in RevenueCat](#create-entitlements-in-revenuecat) +1. [Create an offering and packages in RevenueCat](#create-an-offering--packages-in-revenuecat) +1. Implement the purchases-js Web SDK in your web app or landing page +1. [Test the purchase flow in Sandbox](#testing-in-sandbox) ## Step-by-step instructions @@ -145,7 +158,7 @@ The RevenueCat Paddle Billing integration doesn't currently support Paddle's aba If you close the modal showing the full API key, you will no longer be able to copy it — we recommend you leave this window open until you've saved the key in the RevenueCat config. ::: -## Create Paddle config in RevenueCat dashboard and configure purchase tracking +## Create a Paddle config and configure purchase tracking 1. Log into your RevenueCat account 1. Go to your project @@ -180,6 +193,14 @@ import curlContent from "@site/code_blocks/getting-started/paddle_1.curl?raw"; +## Configure purchase redemption on mobile with Redemption Links + +:::info optional step to enable anonymous purchases +If you're building a web-to-app flow and want to enable purchases without a login, where users are deep-linked into the app post-purchase, you should configure Redemption Links. Without this, you'd need to append user IDs to web purchase links to identify the user. +::: + +Follow the [Redemption Links guide](../web-billing/redemption-links) to configure the customer URL scheme and purchase redemption step in the mobile SDK. + ## Create products and prices in Paddle :::info Do this in Paddle, for sandbox and production. @@ -211,6 +232,14 @@ The "price name" field defines to what is shown to users in the checkout, as a r You can read more about **products and prices** in [Paddle's official documentation](https://developer.paddle.com/build/products/create-products-prices). +## Import Paddle products to RevenueCat + +1. Go to the **Product catalog** in your RevenueCat dashboard, and select the **Products** tab +1. Find your previously added Paddle provider, and click **Import** +1. Check the products you want to use for your web purchases, and click **Import** + +The imported products should now be displayed under your Paddle provider on the Products page. + ## Create entitlements in RevenueCat #### What is an entitlement? @@ -244,3 +273,80 @@ Most apps only have one entitlement, unlocking all premium features. However, if 1. Enter a description 1. In the products list, find your previously-created Paddle provider and select the corresponding Paddle product (this should correspond with the billing cycle you chose in the identifier) 1. Click **Save** + +## Create and configure a web purchase link + +1. Click **Web** in the left menu of the **Project** dashboard +1. Click **Create web purchase link** +1. For the **Offering**, choose the offering you created earlier +1. For the **Payment provider**, choose the Paddle config you created earlier +1. Enter a suitable header and subheader for the package selection page, along with a link to terms & conditions + +:::info Package selection skipped by default for web-to-app purchases +When linking to a web purchase from a RevenueCat paywall, by default the package selection page will be skipped and subscribers will land directly on the checkout with the package selected. +::: + +### Configure the success redirect + +To redirect the subscriber back into to your app after the purchase, you can use a custom URL scheme (see instructions below). You could alternatively redirect the subscriber to a [Universal Link](https://developer.apple.com/documentation/xcode/supporting-universal-links-in-your-app), or your own custom page. + +**To add a custom URL scheme in iOS:** + +1. In Xcode, find your xcodeproj file — Info tab — **URL Types** section. +1. Then add your custom scheme in the **URL Schemes** field. + +**Adding your custom URL scheme in the web purchase link redirect:** + +Select the **Redirect to a custom success page** option, and enter your URL scheme in the format `YOUR_CUSTOM_SCHEME://`. + +:::warning Important: URL schemes on production can require app updates +In order to use a URL scheme on production, your users must be using a version of your app that has the URL scheme configured. Distribute app updates before enabling this feature. +::: + +#### Configure the repeat purchase behavior + +Define what happens when customers to purchase a product while they already have an active subscription or entitlement. For the app-to-web use case, it's recommended to choose **Show the success page**. + +:::info Re-purchasing same product not possible +Note that customers can't have more than one active subscription to the same product, or re-purchase a non-consumable product. +::: + +## Create a RevenueCat paywall with a web purchase button + +**If you have an existing mobile paywall configured:** + +1. Make sure your existing paywall is attached to the same offering you've configured for web purchases +1. Add a web purchase button to your paywall ([Read more](https://www.revenuecat.com/docs/tools/paywalls/creating-paywalls/web-purchase-button)) + +**If you don't have a mobile paywall configured:** + +1. Go to **Paywalls** in the RevenueCat dashboard +1. Select **+ New paywall** +1. Choose the offering you created earlier in this guide and click **Add** +1. [follow this detailed guide](../../tools/paywalls/creating-paywalls) on creating a paywall, and add the mobile packages you want to present. +1. Add a web purchase button to your paywall ([Read more](https://www.revenuecat.com/docs/tools/paywalls/creating-paywalls/web-purchase-button)) + +## Integrate the Web SDK into your web app + +Follow the [SDK integration guide](http://localhost:3030/docs/web/web-billing/web-sdk#sdk-configuration) to complete the integration. + +## Testing in Sandbox + +To test the web checkout in sandbox mode, make sure that you: + +- Have a paddle config created connected to a Paddle sandbox account +- Have products and entitlements from that sandbox account +- Have configured an offering +- Have created a web purchase link to present your products & packages (not required for Web SDK integrations) + +### Testing with a sandbox Web Purchase Link + +You can find the sandbox purchase URL by + +1. Click **Web** in the left menu of the **Project** dashboard +1. Click the name of your web purchase link in the **Web purchase links** table +1. Click **Share URL** +1. Append a user ID +1. Click **Copy sandbox URL** + +To complete purchases on sandbox, you can use [Paddle's test cards](https://developer.paddle.com/v1/concepts/payment-methods/credit-debit-card#test-payment-method) to simulate a real transaction. diff --git a/docs/web/web-billing/web-sdk.mdx b/docs/web/web-billing/web-sdk.mdx index 52049b007..2769be990 100644 --- a/docs/web/web-billing/web-sdk.mdx +++ b/docs/web/web-billing/web-sdk.mdx @@ -7,18 +7,19 @@ hidden: false :::warning Web SDK billing engine support -- RevenueCat Web Billing: supported ✅ -- Stripe Billing: not supported ❌ -- Paddle Billing: supported ✅ +- RevenueCat Web Billing: supported ✅ (requires Stripe account for payment gateway) +- Paddle Billing: supported ✅ (requires Paddle account) +- Stripe Billing: not yet supported ❌ ::: -RevenueCat's Web SDK allow you to easily sell subscriptions and other purchases in your web app. It utilizes Stripe as the payment gateway, so you'll need a Stripe account to connect with your RevenueCat account. +RevenueCat's Web SDK allow you to easily sell subscriptions and other purchases in your web app. Web Billing differs from external payment integrations in that it takes care of the purchase UI, the subscription management portal, and the recurring billing logic. -:::info Stripe fees with Web Billing -When using Web Billing, Stripe will still charge a [payment processing fee](https://stripe.com/pricing) for transactions, but you will not have to pay [Stripe Billing fees](https://stripe.com/billing/pricing). See [fee comparison](overview#fee-comparison) +:::info Fees +If you're using Web Billing, Stripe will still charge a [payment processing fee](https://stripe.com/pricing) for transactions, but you will not have to pay [Stripe Billing fees](https://stripe.com/billing/pricing). See [fee comparison](overview#fee-comparison) +If you're using Paddle, you'll be charged [Paddle's transaction fees](https://www.paddle.com/pricing). ::: ## Installation @@ -45,7 +46,7 @@ For example, use `Purchases.Purchases.configure()` instead of `Purchases.configu ## General setup -### Connect with Stripe +### Connect with billing provider To get started, you first need to [connect your Stripe account with RevenueCat](/web/connect-stripe-account), if you haven't already done so.