Integrate Subscriptions

DocsCurrentLast updated: May 18th 2022, @ 4:02:27 pm

Know before you code

Complete the steps in Get Started to get the following sandbox account information from the Developer Dashboard:
- Your client ID
- Your access token
- Your business account credentials
- Your personal account credentials
This client-side and server-side integration uses the following:
PayPal Subscriptions doesn't support Indian Rupees (INR).

Technical flow

Create a product to represent your goods or services.
Create a plan to represent the payment cycles for your subscription.
Use the PayPal JavaScript SDK to present the PayPal button. When the buyer selects the button, the subscription experience begins.
The buyer agrees and subscribes.
The button calls the PayPal Subscriptions API to create the subscription.
The buyer sees the subscription confirmation.

1. Create product

To create a product for your subscription plan, copy the following code and modify it.

Sample request

API endpoint used: Create product

curl -v -X POST https://api-m.sandbox.paypal.com/v1/catalogs/products \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <Access-Token>" \
  -H "PayPal-Request-Id: PRODUCT-18062020-001" \
  -d '{
  "name": "Video Streaming Service",
  "description": "A video streaming service",
  "type": "SERVICE",
  "category": "SOFTWARE",
  "image_url": "https://example.com/streaming.jpg",
  "home_url": "https://example.com/home"
}'

Modify the code

After you copy the code in the sample request, modify the following:

Change Access-Token to your access token.
Replace the sample ID for PayPal-Request-Id with a unique ID you generate. This ID helps prevent creating duplicate products in the event that the API call is disrupted. See also: API Idempotency.
Optional: Change the name, description, and more to represent your actual product.

Step result

A successful request results in the following:

A return status code of HTTP 201 Created.
A JSON response body that contains an ID for the product. You can use this ID to complete other actions through the REST API, such as creating a subscription plan.

Sample response

{
    "id": "PROD-5FD60555F23244316",
    "name": "Video Streaming Service",
    "description": "A video streaming service",
    "create_time": "2020-01-21T16:04:39Z",
    "links": [
        {
            "href": "https://api-m.sandbox.paypal.com/v1/catalogs/products/PROD-5FD60555F23244316",
            "rel": "self",
            "method": "GET"
        },
        {
            "href": "https://api-m.sandbox.paypal.com/v1/catalogs/products/PROD-5FD60555F23244316",
            "rel": "edit",
            "method": "PATCH"
        }
    ]
}

2. Create plan

Because PayPal's Subscriptions API is flexible, you can create a customized subscription plan to fit your business' needs. The following sample request is only one example of a subscription plan. You'll have to modify the code to fit your subscription's model.

Copy the code and try it out, but also review the subscription capabilities and the Create plan endpoint to determine how you might want to adjust this code for your use case.

Sample request

This sample request creates a subscription plan that:

Has a one-month free trial and continues as a 12-month, fixed-price subscription
Includes a $10 USD setup fee
Bills any outstanding balance at the next billing cycle
Allows the subscription to continue if the initial payment for the setup fails
Suspends the subscription after three consecutive payment failures
Includes a 10% tax in the billing amount

API endpoint used: Create plan

curl -v -k -X POST https://api-m.sandbox.paypal.com/v1/billing/plans \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <Access-Token>" \
  -H "Content-Type: application/json" \
  -H "PayPal-Request-Id: PLAN-18062020-001" \
  -d '{
      "product_id": "PROD-5FD60555F23244316",
      "name": "Basic Plan",
      "description": "Basic plan",
      "billing_cycles": [
        {
          "frequency": {
            "interval_unit": "MONTH",
            "interval_count": 1
          },
          "tenure_type": "TRIAL",
          "sequence": 1,
          "total_cycles": 1
        },
        {
          "frequency": {
            "interval_unit": "MONTH",
            "interval_count": 1
          },
          "tenure_type": "REGULAR",
          "sequence": 2,
          "total_cycles": 12,
          "pricing_scheme": {
            "fixed_price": {
              "value": "10",
              "currency_code": "USD"
            }
          }
        }
      ],
      "payment_preferences": {
        "auto_bill_outstanding": true,
        "setup_fee": {
          "value": "10",
          "currency_code": "USD"
        },
        "setup_fee_failure_action": "CONTINUE",
        "payment_failure_threshold": 3
      },
      "taxes": {
        "percentage": "10",
        "inclusive": false
      }
    }'

Modify the code

After you copy the code in the sample request, modify the following:

Change Access-Token to your access token.
Change the value of the product_id parameter to the ID returned when you created the product.
Replace the sample ID for PayPal-Request-Id with a unique ID you generate. This ID helps prevent creating duplicate plans in the event that the API call is disrupted. See also: API Idempotency.
Optional: Change or add parameters in the Create plan request body to create a plan that meets your business needs. Some examples:
- Fixed vs. quantity (user or seat) pricing plans
- Free or discounted trials

Step result

A successful request results in the following:

A return status code of HTTP 201 Created.
A JSON response body containing a plan ID. Use the plan ID to complete other actions through the REST API, such as editing or deactivating the plan.
A subscription plan in the merchant's PayPal account in the On status.

Sample response

{
    "id": "P-17M15335A8501272JLXLLNKI",
    "product_id": "PROD-5FD60555F23244316",
    "name": "Basic Plan",
    "status": "ACTIVE",
    "description": "Basic plan",
    "create_time": "2020-01-21T16:09:13Z",
    "links": [
        {
            "href": "https://api-m.sandbox.paypal.com/v1/billing/plans/P-17M15335A8501272JLXLLNKI",
            "rel": "self",
            "method": "GET"
        },
        {
            "href": "https://api-m.sandbox.paypal.com/v1/billing/plans/P-17M15335A8501272JLXLLNKI",
            "rel": "edit",
            "method": "PATCH"
        },
        {
            "href": "https://api-m.sandbox.paypal.com/v1/billing/plans/P-17M15335A8501272JLXLLNKI/deactivate",
            "rel": "self",
            "method": "POST"
        }
    ]
}

To see how the result of this API call looks in the merchant account, use your sandbox business account credentials to log in to https://www.sandbox.paypal.com/billing/plans. The subscription plan reflects the plan number from the REST API call you made:

3. Create payment button

To start a subscription from your website, add the PayPal JavaScript SDK code and modify it. This code adds buttons to your website so your buyers can use PayPal or a debit or credit card.

Add and modify the code

Copy this code and paste it into a webpage to create the buttons. When your buyer selects a button, they are directed to PayPal to complete subscription agreement and payment.

  <!DOCTYPE html>
  <html>
    <head>
      <meta name="viewport" content="width=device-width, initial-scale=1"> <!-- Ensures optimal rendering on mobile devices. -->
    </head>

    <body>
      <script src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&vault=true&intent=subscription"></script>
      <!-- Add your client_id -->

      <div id="paypal-button-container"></div>

        <script>
          paypal.Buttons({
            createSubscription: function(data, actions) {
              return actions.subscription.create({
                'plan_id': 'YOUR_PLAN_ID' // Creates the subscription
              });
            },
            onApprove: function(data, actions) {
              alert('You have successfully created subscription ' + data.subscriptionID); // Optional message given to subscriber
            }
          }).render('#paypal-button-container'); // Renders the PayPal button
      </script>
    </body>
  </html>

In the code, replace the following values:
- YOUR_CLIENT_ID with your client ID.
- YOUR_PLAN_ID with the plan ID returned from the Create Plan API call.
Load the webpage to see the payment buttons, which should look similar to the following image:

Tip: To render more than one button on a single webpage, see multiple subscribe buttons for your website.

Step result

You have buttons on your website that create a subscription. You can move on to test the subscription flow.

Customize your Subscriptions integration.

Integrate Subscriptions

Know before you code

Technical flow

1. Create product

Sample request

Modify the code

Step result

Sample response

2. Create plan

Sample request

Modify the code

Step result

Sample response

3. Create payment button

Add and modify the code

Step result

Next