Integrate Subscriptions
DocsCurrentLast updated: May 18th 2022, @ 6:02:27 pm
This guide walks you through a sample subscriptions integration.
Note: You can also create and manage subscriptions directly in your PayPal business account.
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:
- Catalog Products REST API creates goods or services for customers to subscribe to
- Subscriptions REST API creates a recurring payment plan
- PayPal JavaScript SDK creates a payment button
- PayPal Subscriptions doesn't support Indian Rupees (INR).
Use Postman to explore and test PayPal APIs.
1. Create product
To create a product for your subscription plan, copy the following code and modify it.
Sample request
Catalog Products API endpoint used: Create product
1curl -v -X POST https://api-m.sandbox.paypal.com/v1/catalogs/products2 -H "Content-Type: application/json" -H "Authorization: Bearer Access-Token" -H "PayPal-Request-Id: PRODUCT-18062020-001" -d '{3 "name": "Video Streaming Service",4 "description": "A video streaming service",5 "type": "SERVICE",6 "category": "SOFTWARE",7 "image_url": "https://example.com/streaming.jpg",8 "home_url": "https://example.com/home"9}'
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 duplicate requests if the API call is disrupted. - Optional: change parameters such as the name and description to represent your 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
The following sample request is an example of a subscription plan. You can modify the code to fit your subscription model.
Copy the code and try it out. You can 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 set up 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
Important: Only one
currency_code
is allowed per subscription plan. You'll need to make a new subscription plan to offer a subscription in another currency.
Subscriptions 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 duplicate requests if the API call is disrupted. - 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> <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.
4. Test flow
Test a transaction to see the subscription created in the merchant account.
Test the transaction as a buyer
Select the PayPal button on the page.
Use the sandbox personal login information from the Developer Dashboard to log in and simulate the buyer making a purchase.
In the Checkout window, notice the purchase amount in the upper right corner. USD is the default currency. You can customize the PayPal JavaScript SDK by adding a different currency code.
Availability: The JavaScript SDK
onShippingChange
function is not compatible with Subscriptions.Select the pull-down arrow next to the purchase amount. The subscription details are available for the buyer to review. It should appear similar to the following image:
Select the test credit card as the payment method and select Continue.
Select Agree & Subscribe to agree to the terms of the subscription.
Select OK to close the pop-up window that acknowledges the subscription.
Confirm the movement of funds from the buyer account
- Use the sandbox personal account you used to complete the purchase to log in to https://www.sandbox.paypal.com/myaccount/autopay/connect/. This URL takes you to the automatic payments page in the sandbox personal account.
- Confirm the subscription appears in the active automatic payment list. Select the active automatic payment to see the details of the subscription.
- Log out of the account.
Confirm the movement of funds to the merchant account
- Use the sandbox business account information from the Developer Dashboard to log in to https://www.sandbox.paypal.com/billing/subscriptions. This URL takes you to the subscriptions management page in the sandbox business account.
- Confirm the subscription made by the test buyer appears on the Subscriptions tab. Select the subscription to see the details of the subscription.
- Log out of the account.
Next steps
- Customize your subscription integration
- Test and go live with your subscription integration.
See also
- Catalog Products REST API and Subscriptions REST API - Use these APIs to add actions to your integration, such as updating the product description, editing the plan or subscription, deactivating the plan or subscription, and more.
- Subscriptions webhook events - Use webhooks to handle tasks triggered by subscription actions.