Creating a Subscription Service with PayPal (Part 1 of 2): The Billing Plan

This is the first of a two part tutorial on creating a subscription model. Over the next two posts, we will cover everything you’ll need to get started with subscriptions using the PayPal REST APIs:

• Creating billing plans to build a multi-use model for your subscription payments:
• Subscribing users to those billing plans via a billing agreement.

If you want to jump ahead and just get a complete example for parts 1 & 2, you can get it from the PayPal Developer Github repository.

When creating a subscription for a user, you first need to create and activate a billing plan that a user is then subscribed to using a billing agreement. The complete process for creating a subscription is to:

• Create a billing plan. This is a reusable model that outlines the details of the subscription.
• Activate the billing plan.
• When you want to create a subscription for a user, after the user has chosen that plan, you create a billing agreement using the ID of the billing plan that they should be subscribed to.
• Once created, you redirect the user to PayPal to confirm the subscription. Once confirmed, the user is redirected back to the merchant’s website.
• Lastly, you execute the billing agreement to begin the subscription.

Within this example, we’re going to be using the PayPal Node SDK. You can obtain it from NPM using the following command:

npm install paypal-rest-sdk

Within our .js file, we first set up our SDK configuration, which includes adding a requirement for the SDK, defining our client ID and secret from creating our application, and then configuring the SDK for the sandbox environment.

var paypal = require('paypal-rest-sdk');
var clientId = 'YOUR CLIENT ID';
var secret = 'YOUR SECRET';
paypal.configure({
  'mode': 'sandbox', //sandbox or live
  'client_id': clientId,
  'client_secret': secret
});

Next, we need to set up two JSON objects. The billingPlanAttribs object contains the information and payment breakdown for the billing plan that we can subscribe users to, and the billingPlanUpdateAttributes object contains values for setting the billing plan to an active state, allowing it to be used.
var billingPlanAttribs = {
    "name": "Food of the World Club Membership: Standard",
    "description": "Monthly plan for getting the t-shirt of the month.",
    "type": "fixed",
    "payment_definitions": [{
        "name": "Standard Plan",
        "type": "REGULAR",
        "frequency_interval": "1",
        "frequency": "MONTH",
        "cycles": "11",
        "amount": {
            "currency": "USD",
            "value": "19.99"
        }
    }],
    "merchant_preferences": {
        "setup_fee": {
            "currency": "USD",
            "value": "1"
        },
        "cancel_url": "http://localhost:3000/cancel",
        "return_url": "http://localhost:3000/processagreement",
        "max_fail_attempts": "0",
        "auto_bill_amount": "YES",
        "initial_fail_amount_action": "CONTINUE"
    }
};
var billingPlanUpdateAttributes = [{
    "op": "replace",
    "path": "/",
    "value": {
        "state": "ACTIVE"
    }
}];

Within the billingPlanAttribs object, there are some relevant pieces of information:

• name / description / type: Basic visual information to describe the plan, and the type of plan.
• payment_definitions: Information on how the plan should function and be billed. More details on fields here.
• merchant_preferences: Additional fee structures, redirect URLs, and settings for the subscription plan. More details on fields here.

With those objects in place, we can now create and activate the billing plan.
paypal.billingPlan.create(billingPlanAttribs, function (error, billingPlan){
    if (error){
        console.log(error);
        throw error;
    } else {
        // Activate the plan by changing status to Active
        paypal.billingPlan.update(billingPlan.id, billingPlanUpdateAttributes, 
            function(error, response){
            if (error) {
                console.log(error);
                throw error;
            } else {
                console.log(billingPlan.id);
            }
        });
    }
});
We call billingPlan.create(...), passing in the billingPlanAttribs object that we just created. If that is successful, the return object will contain information about the billing plan. For the sake of the example, we just need to use the billing plan ID in order to activate the plan for use.
Next, we call billingPlan.update(...), passing in the billing plan ID and the billingPlanUpdateAttributes object we created earlier. If that is successful, our billing plan is now active and ready to use.
In order to create a subscription for a user (or multiple users) on this plan, we'll need to reference the billing plan id (billingPlan.id above), so store that in a place that can be referenced easily.
In the second subscription step, we need to create a billing agreement based on the plan we just created and execute it to begin processing subscriptions for a user.
Stay tuned for part 2...