PayPal Step 1: Creating a Subscription Model using a Billing Plan (Node Sample)


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 full process for creating a subscription is detailed in the remarks of this topic.

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';

  '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){
        throw error;
    } else {
        // Activate the plan by changing status to Active
        paypal.billingPlan.update(, billingPlanUpdateAttributes, function(error, response){
            if (error) {
                throw error;
            } else {

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 ( 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.