Paddle Billing

How to Connect Your Paddle Account

After you register for a Churnkey account, you can connect it to your Paddle Billing 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 Billing. If you're looking for integration instructions for Paddle Classic, click here.

Start the connection process by selecting Paddle Billing in the Paddle Version section.

Step 2. Add your API Key and your Webhook Secret Key

Your API key is used to apply pauses, discounts, and cancellations to customer subscriptions on your behalf. Read all about how we use the API key below.

1. Create a new API Key for Churnkey at Paddle | Authentication. If you're operating in Sandbox mode, use this link instead.
   
2. Click the ellipsis button next to your newly-created API Key and copy it.
   
3. Enter your API Key in 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. Find your webhook URL on your Churnkey settings page and copy it.

2. Navigate to Paddle | Notifications or use this link for Sandbox mode.
3. Click “+ New destination” button on the top right corner.
4. Set the webhook URL to the one you copied in step 1.
   
5. Mark all checkboxes under the sections Transaction, Subscription, and Customer.
   
6. Save the destination.
   
7. After saving, click the ellipsis button next to it and select 'Edit destination'.
   
8. You will see a screen similar to the one for adding the destination, but it now includes an additional, read-only field: "Secret key". Please copy it.
   
9. Enter your Webhook Secret in Churnkey | Billing Provider

How is the Paddle connection used?

I. Add discounts to your cancel flow

After you connect Paddle (live mode), you’ll be able to offer your customers temporary discounts as part of your cancel flow. Please note that you will only see your Paddle coupons after you’ve connected your live Paddle account. We only pull in coupons from the live account, not your Stripe test account.

1. In the “Offers” tab of the flow builder, choose “Apply Paddle Coupon”
2. Choose the coupon you’d like to offer customers in the dropdown labeled “Paddle Coupon”
   

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. Pause a subscription
2. Apply a discount
3. Cancel a subscription
4. Extend a trial period
5. Switch plans

We'll look at each one of these in a little bit more detail.

Pause a Subscription

Churnkey uses Paddle’s built-in pause feature which will schedule a pause starting the next billing date, for the selected duration.

You can specify the maximum pause length allowed by customers while configuring your cancel flow.

When a customer chooses to temporarily pause their account, if a subscription ID was provided when initializing the Churnkey embed, the subscription under that ID will be canceled. If just a customer ID is provided, each active subscription will be paused.

If you would like to implement a custom function for handling pause events, you can do so using the handlePause callback (see Custom Callbacks).

Apply a Discount

In the Churnkey offer builder, you can offer specific discounts to customers. These discounts are populated based on the coupons that you have created in your Paddle account (in Paddle | Catalog | Discounts, or here for Sandbox mode).

When a customer accepts a discount, if a subscription ID was provided when initializing the Churnkey embed, the coupon will be applied to that subscription. If just a customer ID is provided, that coupon is applied directly to the Paddle customer account.

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 manage the cancellation of your customer's subscription. When a customer decides to cancel, we will schedule the subscription cancellation at the end of the current period.

When a customer chooses to cancel their account, if a subscription ID was provided when initializing the Churnkey embed, the subscription under that ID will be canceled. If just a customer ID is provided, each active, delinquent, and past due subscription will be canceled.

If you would like to implement a customer function for canceling subscriptions, you can do so using the handleCancel callback (see Custom Callbacks).

Extend a Trial Period

More information coming soon!

Switch plans

More information coming soon!

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.