Paddle Classic

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.

Manage Paddle Connection

Step 1. Select Paddle Version

Paddle has two different versions: Paddle Classic and Paddle Billing.

• Unsure about the version you're using?
  • 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.

1. Create a new Auth Code for Churnkey at Paddle | AuthenticationNote: make sure to use this auth code instead of the SDK API key
2. 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.
3. Your Public Key is listed under Paddle | Public Key
4. 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.

1. Navigate to Paddle | Events
2. Click “+Add a new endpoint” under “URLs for receiving webhooks”
3. Set the webhook URL to https://billing.churnkey.co/e/src_SP8oUSlSZJab?appId=YOUR_CHURNKEY_APP_ID (please note to replace YOUR_CHURNKEY_APP_ID with 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.

1. In the “Offers” tab of the flow builder, choose “Apply Custom Discount”
2. 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.

🚀 Customer Segmentation Launch Details

Available attributes for segmentation

• Plan
• Price
• 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 subscription/users_cancel endpoint.

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.