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:

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.

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.

About Jonathan LeBlanc

Jonathan LeBlanc is an Emmy award winning software engineer, author of the O’Reilly books “Identity and Data Security for Web Development” and "Programming Social Applications", and the Head of Global Developer Advocacy for PayPal. Specializing in identity, auth and security, hardware to web interconnectivity, and data mining techniques, as well as open source initiatives around social engagement, Jonathan works on the development of emerging initiatives towards building a more user-centric web.

Tagged with:

16 Responses to Subscriptions are Now Available in the PayPal REST APIs

  1. JJ De la Torre says:

    Great News !

    I have a question, is there a way to create Billings Plans in some part of the Merchant Contro Panel ? . . So in that way it would be easier to push a user or several users to an already defined Billing Plan template


  2. P.J. Steele says:

    Thanks for the post. It’s VERY helpful.

    What is the difference in “frequency_interval” and “cycles”

  3. Liam Carter says:

    Frequency_interval is the quanity of the frequency between billing
    So frequency_interval of 3 and frequency of MONTH would bill every 3 months
    The Cycles is how many billing runs do you want before the subscription finishes

  4. Liam Carter says:


    Great post and great feature.

    OK i have managed to sort out nearly all of what i need for the Agreements. One issue i have is the monies are not taken straight away.

    The subscription hasnt yet run and it has been a few hours.

    [cycles_completed] => 0

    [next_billing_date] => 2014-08-13T10:00:00Z

    Which has passed, i did add the agreement only a few hours ago. How do i make the subscription run straight away?

    If not the only other way i can see is that i set a set up fee and start the subscription 1 period ahead.

    Any Ideas?


  5. Andy Jones says:

    How would you specify an unlimited number of cycles? For example, when I’d want to continue the plan until it’s manually cancelled. Would it be a case of sending something like “cycles”: “9999999” for a monthly frequency?

  6. Liam Carter says:

    “type”: “infinite”,


    “cycles”: “0”,

  7. Andy Jones says:

    Excellent, thanks

  8. Liam Carter says:

    You’re welcome

  9. Andy Jones says:

    Am I right in assuming that IPN is still used to be notified when a payment is received using the BillingPlan method? If so, does the IPN contain details of the BillingPlan so I can update my customer account records to show payment history and manage access to the application where a payment is not received?

  10. Donovan McGillen says:

    Any response to this question? I’ve been trying to find this information myself. For example, if a user cancels the agreement, will we get a notification?

  11. Andy Jones says:

    well I’ve actually had a response back from PayPal integration support bod and frankly is a rediculous response…

    Hi Andy,

    We understand your concerns, the REST APIs and documentation is quite new and is not really helpful.

    We don’t recommend to use the REST API, we suggest to use the Classic API CreateRecurringPaymentsProfile API (how to set up a Recurring Payments Profile using Direct Payment).

    Basically when you have the “profileid” (generated by the API call), in the IPN message is coming back as “recurring_payment_id=”.

    Here an example of an IPN response with Recurring Payments:


    You will need to be sure that profile_status is “Active” and you will get as well the profileid in “recurring_payment_id”.

    I believe that you are testing the integration in Sandbox, please could you share with me the email business account? I will check your latests IPNs.



  12. Melanie Jutras says:

    I am trying to incorporate PayPal subscription payments using the paypalrestsdk with python in a django application. I understand that I need to set up billing plans (ie. a monthly plan for $10 a month and a yearly plan for $100 a month) I also understand that I then need to create a billing agreement which redirects the user to approve the agreement and which returns the agreement object which will give me the ability to access the plan information in order to update, suspend, reactivate the agreement. Most importantly, in order to get started, I need to execute the agreement. This is the part that confuses me. Do I execute the agreement each month (for my users who have agreed to monthly subscription) or do I execute the agreement one time in order to tell PayPal to automatically process the monthly payment? If the latter case is the answer then how would I know if a payment failed for some reason?

    Your input would be greatly appreciated!

  13. Hi,
    I’ve run into the same problem. Have you found a solution?

  14. JJ De la Torre says:

    Hi, I haven’t found.
    It seems like using the PayPay Payments Pro you can do that. I’m not sure, thought. I couldn’t test it because is not available in my country.

  15. JJ De la Torre says:

    Hi, nope, but i guess Paypal Payment Pro has that functionality

  16. Michael says:

    Can anybody please help me with my problem.

    I want to charge customer immediately, when I do subscription. How can I achieve that. setup_fee parameter is not working. It’s not charging immediately.