How to Connect Your Paddle Account
After you register for a Churnkey account, you can connect it to your Paddle Classic account on our Settings | Billing Provider page. You can enter both live and sandbox credentials. The sandbox credentials are optional, but great to add if you want to test your cancel flow in a staging environment before going live with Churnkey.
Step 1. Select Paddle Version
Paddle has two different versions: Paddle Classic and Paddle Billing.
- If your Paddle account was created after August 8th, 2023, then you're using Paddle Billing.
- If it was created before that date, you're likely using Paddle Classic, unless you actively migrated to the newer version.
- For more information, visit Paddle Billing.
This documentation page is for Paddle Classic. If you're looking for integration instructions for Paddle Billing, click here.
Start the connection process by selecting Paddle Classic in the Paddle Version section.
Step 2. Add your Vendor ID, Public Key, and Auth Code to Churnkey
Your API key is used to apply discounts (via modifiers) to customer subscriptions on your behalf. Read all about how we use the API key below.
- Create a new Auth Code for Churnkey at Paddle | Authentication Note: make sure to use this auth code instead of the SDK API key
- Click “Reveal Auth Code” under “Active Integrations & Auth Codes” to show the Churnkey-specific Auth Code. Your vendor_id can also be found at the top of the same page.
- Your Public Key is listed under Paddle | Public Key
- Enter the above details under Churnkey | Billing Provider
Step 3. Add Webhook Notifications
In order for Churnkey to track reactivation rates (after accepted offers), and keep track of total boosted revenue from your cancel flow, you need to add a webhook in your Paddle account.
- Navigate to Paddle | Events
- Click “+Add a new endpoint” under “URLs for receiving webhooks”
- Set the webhook URL to
https://billing.churnkey.co/e/src_SP8oUSlSZJab?appId=YOUR_CHURNKEY_APP_ID(please note to replace
YOUR_CHURNKEY_APP_IDwith your App ID - your account specific URL can be found on your Churnkey settings page)
How is the Paddle connection used?
I. Add discounts to your cancel flow
After you connect Paddle, you’ll be able to offer your customers discounts as part of your cancel flow.
- In the “Offers” tab of the flow builder, choose “Apply Custom Discount”
- Choose the amount you’d like to offer customers and whether this is a one time or recurring discount.
II. Personalize cancel flows with customer attributes and segmentation
Use customer segmentation to reduce voluntary churn with targeted cancel flows. With segmentation, you can target specific customers based on subscription attributes and serve up unique cancel flows for each of them. After all, someone who signed up yesterday should be spoken to differently from a customer who’s been a paying subscriber for years.
You can use custom attributes to create different cancel flows for subscriptions in different currencies, tailoring the offers for each segment.
Available attributes for segmentation
- Subscription age
- Subscription creation date
- Billing interval (weekly, monthly, annual, etc)
- Trial vs Active subscription
III. Updating customer subscriptions on your behalf
When a customer goes through your cancel flow and either chooses to cancel their subscription or (hopefully) accept a discount offer, Churnkey will take care of the billing and subscription updates for you.
Churnkey is able to perform the following actions on your behalf:
1. Apply a discount 2. Cancel a subscription
We'll look at each one of these in a little bit more detail.
Apply a Discount
In the Churnkey offer builder, you can offer specific discounts to customers. While Paddle does allow you to create coupons within their dashboard, they do not allow these discounts to be applied through the API to existing subscriptions. Instead, Churnkey uses subscription modifiers to add a discount to existing subscriptions.
When a customer accepts a discount, a modifier will be added to the subscription (for the amount you specified when building you cancel flow).
If you would like to implement a customer function for applying discounts, you can do so using the
handleDiscount callback (see Custom Callbacks).
Cancel a Subscription
Churnkey can handle canceling your customer's subscription for you. Churnkey uses Paddle’s
If you would like to implement a customer function for canceling subscriptions, you can do so using the
handleCancel callback (see Custom Callbacks).
A Note on Subscription Pauses
Paddle does have a notion of subscription pauses. Currently, however, their API does not provide an option to pause a subscription for a limited period (e.g. pause a subscription for 2 months). Adding in this feature with custom workarounds is on the Churnkey roadmap, and we’ll keep all Paddle customers updated on this progress.
IV. Calculating boosted revenue
Once you’ve connected your Paddle account, you’ll be able to track customer reactivations and boosted revenue - that’s all the extra revenue you receive from customers who stayed on instead of canceling.
You can track boosted revenue on your Churnkey dashboard.
On this page
- Paddle Classic
- How to Connect Your Paddle Account
- Step 1. Select Paddle Version
- Step 2. Add your Vendor ID, Public Key, and Auth Code to Churnkey
- Step 3. Add Webhook Notifications
- How is the Paddle connection used?
- I. Add discounts to your cancel flow
- II. Personalize cancel flows with customer attributes and segmentation
- III. Updating customer subscriptions on your behalf
- Apply a Discount
- Cancel a Subscription
- A Note on Subscription Pauses
- IV. Calculating boosted revenue