Integration Guide

This is an in-depth guide on building a subscription billed service with Paddle. You can also get a basic overview of how to get started with subscriptions using our Quick Start guide.

In this guide, we’ll cover the following sections:

  1. Getting Started
  2. Changing Subscriptions

1 Getting Started

In this section we’ll create subscription plans, subscribe users to the plans, and then listen for subscription events / alerts to keep our system up to date. This first ‘Getting Started’ section is largely similar to the ‘Quick Start’ guide for subscriptions.

1.1 Creating Plans

A ‘Subscription Plan’ as you’ll hear it referred to within this guide is a billing cycle that a user can be subscribed to. For example: $30 per month. These plans are defined within the Subscription Plans area of your Paddle Dashboard.

From within the Subscription Plans section of your Paddle Dashboard click "New Subscription Plan".

new subscription plan

Once you have created your subscription plans, you can proceed to the next section.

1.2 Subscribing Customers to Plans

To remove your application from any PCI compliance scope, Paddle hosts the checkout and card entry pages for subscriptions.

You can direct these users to these pages by clicking on the "Checkout Link" option next to the subscription plan. You can use both standard checkout links or our Javascript pop-over / overlay checkout with these subscription checkouts.

Step 1: Grab your Checkout Link / Checkout ID: Click the "Checkout Link" button next to your subscription plan, here you’ll be able to find the Checkout Link and Checkout ID. You’ll need these for the next section.

Step 2: Send the User to the Checkout: The example below uses our Overlay Checkout (and assumes you’ve already included JQuery and our Checkout.js file on your page). We recommend passing in a User ID from your system via the passthrough variable, so you can identify this subscription and attach it to a user later.

<a href="#" class="paddle_button" data-product="496305" data-success="/thank-you/" data-passthrough="123">Subscribe</a>

In the above example 496305 is the ‘Checkout Product ID’ from the ‘Checkout Link’ popup for my subscription plan, and 123 is the ID of the user in my database. This User ID would be passed back to me with my subscription events, so I could easily associate subscription events with my users.

We’ve also included the parameter success, which is where the user will be redirected after a successful subscription. I’ve chosen to redirect to /thank-you/.

1.3 Keeping Your System In-sync

Once you’ve subscribed a user to a plan, you need to keep your database in-sync with their subscription status.

We recommend subscribing to all of the subscription events via webhook, from the ‘Alerts’ section within your Paddle Dashboard.

Upon new subscription signup the subscription_created is fired. From this event you can use the passthrough variable we set during the checkout to identify the user in your system and give them access to your website, application, and / or features accordingly. The other subscription events you’ll likely want to handle also are listed here.

You can find full documentation, including field / parameter references for each event in the Subscription Event / Alert documentation. You will find more detailed instructions on what you should do with each event there.

2 Changing Subscriptions

2.1 Working with Trial Periods

Should you use Paddle trial periods? We recommend Paddle’s trial periods if you’re happy to collect card information from the user up front and automatically bill the user when their trial period is over.

If you wish to provide a ‘card not required’ trial period, and prompt the user for card information at the end of their trial, we recommend you manage the trial period yourself and simply skip this step.

Using Paddle Trial Periods Trial periods are defined at a ‘Plan Level’. You specify the trial period as a number of days within the Paddle Dashboard when you create a plan.

When you define a plan with a trial period, every new customer that is subscribed to that plan will automatically receive that trial period.

While the user is in their trial period, the status parameter returned via the API, webhooks, and events will be set to a value of trialing.

Once a trial period is up, Paddle will attempt to charge the customer using the card details that were provided when the user subscribed to the plan. Assuming the payment succeeds, you’ll receive the following events:

  • subscription_payment_succeeded
  • subscription_updated (this will reflect a change in status from trialing to active)

2.2 Charging a Setup Fee

If you wish you can charge a setup fee for a subscription, or a price for the trial period. You set this by defining that amount within the Checkout URL that you pass the customer to when they subscribe to their subscriptions. Dependent on if you use Paddle trial periods or not, the ‘Setup Fee’ is treated differently:

Using Paddle Trial Period

The amount you define is charged immediately, once the trial expires the user will be billed the recurring amount for each billing cycle.

Not Using Paddle Trial Period

The amount you define is charged immediately, the user is then charged the recurring amount after one billing cycle has elapsed.

You can provide the setup fee as the price parameter within the checkout URL (or as data-price if you’re using overlay checkout). When defining amounts/prices you’re required to sign the URL with an auth parameter, see the documentation about using dynamic prices for more info.


<?php
  // The amount of the 'Setup Fee'
  $price = '39.00';

  // The 'Secret Key' and 'Product ID' associated with the Subscription Plan (click 'Product Link' button next to the plan in the dashboard)
  $checkout_secret_key = '1xpjlt9';
  $product_id = 496305;

  // MD5 Hash these two values to create your 'Auth Token':
  $auth = md5($price.$checkout_secret_key);

  // Compile your Checkout Link with these values:
  $checkout_link  = 'https://pay.paddle.com/checkout/'.$product_id.'?price='.$price.'&auth='.$auth;
?>

In the example above, the user would be billed $39.00 immediately, followed by $10.00 per month (as defined in the Paddle Dashboard).

2.3 Upgrades & Downgrades

Subscriptions can be changed by switching the plan to which a customer is subscribed. Typically this is either upgrading or downgrading the subscription, depending on the difference in price between the two plans.

Assuming the customer is currently subscribed with subscription ID 12345 to the Basic plan for $10/mo, which has an ID of 496305, and wants to upgrade to the Pro plan for $30/mo, which has an ID of 496307:


# The vendor_id and vendor_auth_code parameters can be found by creating access tokens in: https://vendors.paddle.com/account > "Integrations" tab.
curl -X POST -d 'vendor_id=123' \
             -d 'vendor_auth_code=1:54229abfcfa...' \
             -d 'subscription_id=12345' \
             -d 'plan_id=496307' \
             https://vendors.paddle.com/api/2.0/subscription/users/move

In the above example we’re moving Subscription ID 12345 from its current ‘Basic’ plan to a new plan 496307.

If the two plans you’re moving a subscription between have the same Billing Frequency (eg. both are monthly), the customer will retain the same billing dates. If the plans do not have the same billing frequency (eg. a customer is moving from monthly to yearly billing), the plan will be billed at a new interval, starting at the date of the change. As an example: You switch a customer from one monthly plan to another, the billing date does not change. However, if you switch a customer from a monthly, to an annual plan, the new annual billing date becomes the day of the switch.

If the change moves a customer into a situation where a payment is required (for example moving a customer to a different billing frequency, such as monthly to yearly), Paddle will automatically attempt a payment of the amount that is owed.

By far the most confusing aspect of plan changes is how existing payments are factored into the amount charged to the customer. By default, when changing plans, Paddle will prorate the subscription costs.

As an example, say the customer is billed on the 1st of every month, and you execute a plan change half way through the billing cycle (in this case, mid-month on a monthly cycle - eg. the 15th of the month). In this case the customer has already paid $10 and used half of that (because they’re half-way through the month). When the customer is switched to the new plan which has a price of $30.00, the unused portion of their previous cycle (in this case $5) is applied as a credit. The cost of the new plan for the rest of the billing cycle (ie. the remaining 15 days of the month) would be $15. Applying the $5.00 credit to this amount, results in a prorated cost of switching from the Basic to the Pro plan of $10. This amount will be added to their next billed amount.

The next billed amount, at the start of the next month would also reflect the payment required on the new plan for that upcoming month: $30. Thus the next billed amount would be for total of $40 ($30 for their upcoming billing cycle, and $10 for the prorated amount of their previous cycle).

Note that in this example of changing between monthly subscriptions the plan change would not alter the billing date or cycle. The customer will not be billed $40 at the point the plans are switched, the charge is reflected in the next billed amount (which remains on the same billing cycle as both plans have the same monthly billing frequency.

Changing plans will trigger a subscription_updated event.

2.4 Cancelling Subscriptions

To cancel a subscription, direct the user to the cancel_url that is passed to you via HTTP POST within the subscription_created event or use the Dashboard API.

A successful cancellation will trigger a subscription_cancelled event.

2.5 Payment Failures

As subscriptions are recurring payments, sometimes during a billing cycle payments fail. This can happen for a variety of reasons, such as a customers card details expiring, or their account temporarily having insufficient funds.

Within your Paddle Dashboard settings page, under the “Subscriptions” tab, we allow you to define the rules for retrying subscription payments. We recommend leaving a few days between each payment retry. That will typically allow any temporary issues (such as insufficient funds) to resolve themselves.

Each time a payment fails a subscription_payment_failed event is triggered. Use this event to monitor failed payments, update your records accordingly, and prompt the customer to enter new card information. You can prompt users to update their card / billing information by directing them to the update_url that is passed with the subscription_created event.

2.6 Changing the Payment Amount using Modifiers

You may wish to alter the amount that a user is charged either on a one-time or recurring basis.

Paddle allows this through the use of ‘modifiers’ that you can apply via our API to a subscription between billing cycles to change the next payment (or all future recurring payments).

In the example below we will add a one-time $10 modifier to a subscription. The user will be billed an additional $10 with their next bill.


curl -X POST -d 'vendor_id=123' \
             -d 'vendor_auth_code=1:54229abfcfa...' \
             -d 'subscription_id=12345' \
             -d 'modifier_recurring=false' \
             -d 'modifier_amount=10.00' \
             -d 'modifier_description=Example' \
             https://vendors.paddle.com/api/2.0/subscription/modifiers/create

To add a recurring modifier, simply set the modifier_recurring flag to true.

Below is an example response to the above API call:


{
    "success": true,
    "response": {
        "subscription_id": 12345,
        "modifier_id": 10
    }
}

When a modifier is successfully added, a modifier_id is returned. You should store this incase you wish to remove the modifier at some point in the future. If you wish to remove a modifier, you can use the following API call:


curl -X POST -d 'vendor_id=123' \
             -d 'vendor_auth_code=1:54229abfcfa...' \
             -d 'modifier_id=10' \
             https://vendors.paddle.com/api/2.0/subscription/modifiers/delete

If at any time you want to list the modifiers attached to a subscription you can call the /subscription/modifiers endpoint with a subscription parameter passing the Subscription ID:


url -X POST -d 'vendor_id=123' \
             -d 'vendor_auth_code=1:54229abfcfa...' \
             -d 'subscription_id=12345' \
             https://vendors.paddle.com/api/2.0/subscription/modifiers

The API will respond with a list of modifiers attached to the requested subscription:


{
    "success": true,
    "response": [
        {
            "modifier_id": 10,
            "subscription_id": 12345,
            "amount": "1.000",
            "currency": "USD",
            "is_recurring": false,
            "modifier_description": "Example Modifier"
        }
    ]
}
Was this page helpful?