Subscriptions are Now Available in the PayPal REST APIs

As of today, I am happy to announce that subscription models (what we call billing plans and agreements) have launched as our newest piece of functionality in the PayPal REST APIs.

This long awaited feature will allow you to not just process one time payments, but instead set up and modify entire recurring payment cycles, including the ability to incorporate trial periods for greater product control.

How it Works

While there is a lot of new functionality to play with in this API release, let’s start by taking a look at how to get to the point of starting to bill a customer on a monthly basis, and also include a trial period for the product for people to try before they buy.

In its simplest form, how we make a subscription model work is a two step process:

1. Create a Billing Plan: Basically all you’re doing here is creating the billing template that you can use to subscribe users to a particular billing plan.
   Tip: You can have multiple billing plans set up at the same time.
2. Create a User Billing Agreement: Once you have the billing plan template in place, you can then use that template in the payment process to set up a recurring payment cycle for a user, such as monthly.

That’s pretty much the gist of it, create a billing plan, then assign a user to a particular plan (called a billing agreement) when you push them through to pay. Let’s dive a little bit deeper into these features, and see how each piece works.

Creating a Billing Plan

Let’s say we run a “Fruit of the Month” club, and we sell monthly subscriptions to ship a new assortment of unique fruits to people monthly. For new customers, we also offer a trial period where you can have the first month free, to take a look at the quality of the product. The request to the billing plan API would look something like this:

curl -v POST https://api.sandbox.paypal.com/v1/payments/billing-plans \
-H 'Content-Type:application/json' \
-H 'Authorization: Bearer {accessToken}' \
-d '{
    "name": "Fruit of the Month",
    "description": "10 Pound Box of Fruit",
    "type": "fixed",
    "payment_definitions": [
        {
            "name": "Standard Package",
            "type": "REGULAR",
            "frequency": "MONTH",
            "frequency_interval": "2",
            "amount": {
                "value": "50",
                "currency": "USD"
            },
            "cycles": "12",
            "charge_models": [
                {
                    "type": "SHIPPING",
                    "amount": {
                        "value": "8",
                        "currency": "USD"
                    }
                },
                {
                    "type": "TAX",
                    "amount": {
                        "value": "4",
                        "currency": "USD"
                    }
                }
            ]
        },
        {
            "name":"First Month Free Trial",
            "type":"TRIAL",
            "frequency":"MONTH",
            "frequency_interval":"1",
            "amount": { 
            "value" : "50",
            "currency" : "USD"
        },
        "cycles":"1",
        "charge_models": [
            {
                "type":"SHIPPING",
                "amount": { 
                    "value" :"8",
                    "currency" : "USD"
                }
            },
            {
                "type":"TAX",
                "amount": {
                    "value" :"4",
                    "currency" : "USD"
                }
            }
        ]
    }],
    "merchant_preferences": {
        "setup_fee": {
            "value": "1",
            "currency": "USD"
        },
        "return_url": "http://www.fruitofthemonth.com/complete",
        "cancel_url": "http://www.fruitofthemonth.com/cancel",
        "autobill_amount": "YES",
        "initial_amount_fail_action": "CONTINUE",
        "max_fail_attempts": "0"
    }
}'

Once you create the billing plan, you’ll get a JSON response back, which will include an ID referencing back to the billing plan. This is what we’re going to use when we push a user through to the payment step to reference what billing plan we want them signed up to, called a billing agreement.

Subscribing a User to a Billing Agreement

Next, let’s say a customer has come to our site and wants to subscribe to the “Fruit of the Month” club. She picks the plan that she wants to be a part of (let’s say a 10 pound box of fruit) and is subscribed using a billing agreement (essentially just subscribing a user to a billing plan) that we just set up by pushing her to PayPal to use her account.

curl -v POST https://api.sandbox.paypal.com/v1/payments/billing-agreements
-H 'Content-Type:application/json' \
-H 'Authorization: Bearer {accessToken}' \
-d '{
    "name": "Main Subscription",
    "description": "Fruit of the Month Subscription",
    "start_date": "2015-02-19T00:37:04Z",
    "plan": {
        "id": "P-0NJ10521L3680291SOAQIVTQ"
    },
    "payer": {
        "payment_method": "paypal"
    },
    "shipping_address": {
        "line1": "My Business",
        "line2": "1665 Biscayne rd",
        "city": "Miami",
        "state": "FL",
        "postal_code": "33141",
        "country_code": "US"
    }
}'

As you can see from the sample, we are sending a user through a standard PayPal payment method, passing in the new “plan” object within the request payload. That will reference the ID that we gained back when creating the billing plan above. We will get back a redirect URL to forward the user to in order to sign in to their PayPal account.

That’s pretty much it for our simple example. Between a billing plan and the user billing agreement, you can create any number of subscription scenarios for your customers.

Going Further

We’ve obviously just began to touch on all of the functionality that’s available to us with the new billing plan / billing agreement APIs. We can go further with mechanisms to suspend and revoke billing agreements, update parts of billing plans, and a number of other scenarios.

As you build out your subscription system, you can dive into more detail about the capabilities on the REST API docs.