Subscriptions Integration

To integrate the Subscriptions API, first set up your development environment and then create a product, plan, and subscription.

Availability: Customers who integrated with Subscriptions before April 2019 can access reference and support material in the archived Subscriptions integration guide.

Note: This integration is not supported for merchants in the gambling category.

Set up your development environment

Before you can integrate Subscriptions, you must set up your development environment. After you get a token that lets you access protected REST API resources, you create sandbox accounts to test your web and mobile apps. For details, see Get Started.

Then, return to this page to integrate Subscriptions.

1. Create a product

A product captures goods or services offered for a subscription.

The <ID> is either merchant-provided or system-generated and begins with PROD-xxxx.

Create your product by calling /products:

curl -v -X POST https://api.sandbox.paypal.com/v1/catalogs/products \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer Access-Token" \
  -H "PayPal-Request-Id: merchant-generated-ID \ // Optional and if passed, helps identify idempotent requests
-d '{
  "name": "Video Streaming Service",
  "description": "Video streaming service",
  "type": "SERVICE",
  "category": "SOFTWARE",
  "image_url": "https://example.com/streaming.jpg",
  "home_url": "https://example.com/home"
}'

A successful request returns the HTTP 201 Created status code with a JSON response body.

{
  "id": "PROD-XYAB12ABSB7868434",
      "name": "Video Streaming Service",
      "description": "Video streaming service",
      "type": "SERVICE",
      "category": "SOFTWARE",
      "image_url": "https://example.com/streaming.jpg",
      "home_url": "https://example.com/home",
      "create_time": "2019-01-10T21:20:49Z",
      "update_time": "2019-01-10T21:20:49Z",
      "links": [
        {
          "href": "https://api.paypal.com/v1/catalogs/products/72255d4849af8ed6e0df1173",
          "rel": "self",
          "method": "GET"
        },
        {
          "href": "https://api.paypal.com/v1/catalogs/products/72255d4849af8ed6e0df1173",
          "rel": "edit",
          "method": "PATCH"
        }
      ]
}

If creating a product succeeds, it triggers the CATALOG.PRODUCT.CREATED webhook.

2. Create a plan

You can associate multiple plans to a product. For example, a video streaming service can have three plans: basic, standard, and premium.

Create a plan by calling /plans. Plans are active by default.

This sample request creates a trial plan with a fixed pricing scheme. For user or seat-based pricing plans, set the quantity_supported attribute to true to indicate that customers can subscribe to this plan by providing the number of units they what to subscribe to.

curl -v -k -X POST https://api.sandbox.paypal.com/v1/billing/plans \
  -H "Accept: application/json" \
  -H "Authorization: Bearer Access-Token" \
  -H "PayPal-Request-Id: PLAN-18062019-001" \  // merchant generated ID, optional and needed for idempotent samples
  -H "Prefer: return=representation" \
  -H "Content-Type: application/json" \
  -d '{
      "product_id": "PROD-6XB24663H4094933M",
      "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
      }
    }'

curl -v -k -X POST https://api.sandbox.paypal.com/v1/billing/plans \
  -H "Accept: application/json" \
  -H "Authorization: Bearer Access-Token" \
  -H "PayPal-Request-Id: PLAN-18062019-001" \  // merchant generated ID, optional and needed for idempotent samples
  -H "Prefer: return=representation" \
  -H "Content-Type: application/json" \
  -d '{
        "product_id": "PROD-XXCD1234QWER65782",
        "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": {
          "service_type": "PREPAID",
          "auto_bill_outstanding": true,
          "setup_fee": {
            "value": "10",
            "currency_code": "USD"
          },
          "setup_fee_failure_action": "CONTINUE",
          "payment_failure_threshold": 3
        },
        "quantity_supported": true,
        "taxes": {
          "percentage": "10",
          "inclusive": false
        }
    }'

A successful request returns the HTTP 201 Created status code with a JSON response body that shows subscription details.

{
  "id": "P-2UF78835G6983425GLSM44MA",
  "product_id": "PROD-6XB24663H4094933M",
  "name": "Basic Plan",
  "status": "ACTIVE",
  "description": "Basic plan",
  "billing_cycles": [
    {
      "frequency": {
        "interval_unit": "MONTH",
        "interval_count": 1
      },
      "tenure_type": "TRIAL",
      "sequence": 1,
      "total_cycles": 1
    },
    {
      "pricing_scheme": {
        "fixed_price": {
          "currency_code": "USD",
          "value": "10.00"
        }
      },
      "frequency": {
        "interval_unit": "MONTH",
        "interval_count": 1
      },
      "tenure_type": "REGULAR",
      "sequence": 2,
      "total_cycles": 12
    }
  ],
  "payment_preferences": {
    "auto_bill_outstanding": true,
    "setup_fee": {
      "currency_code": "USD",
      "value": "10.00"
    },
    "setup_fee_failure_action": "CONTINUE",
    "payment_failure_threshold": 3
  },
  "taxes": {
    "percentage": "10.00",
    "inclusive": false
  },
  "quantity_supported": false,
  "create_time": "2019-03-26T07:01:04Z",
  "update_time": "2019-03-26T07:01:04Z",
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/billing/plans/P-2UF78835G6983425GLSM44MA",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/billing/plans/P-2UF78835G6983425GLSM44MA",
      "rel": "edit",
      "method": "PATCH"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/billing/plans/P-2UF78835G6983425GLSM44MA/deactivate",
      "rel": "self",
      "method": "POST"
        }
      ]
    }

{
  "id": "P-2UF78835G6983425GLSM44MA",
  "product_id": "PROD-XYAB12ABSB7868434",
  "name": "Basic Plan",
  "status": "ACTIVE",
  "description": "Basic plan",
  "billing_cycles": [
    {
      "frequency": {
        "interval_unit": "MONTH",
        "interval_count": 1
      },
      "tenure_type": "TRIAL",
      "sequence": 1,
      "total_cycles": 1
    },
    {
      "pricing_scheme": {
        "fixed_price": {
          "currency_code": "USD",
          "value": "10.0"
        }
      },
      "frequency": {
        "interval_unit": "MONTH",
        "interval_count": 1
      },
      "tenure_type": "REGULAR",
      "sequence": 2,
      "total_cycles": 12
    }
  ],
  "payment_preferences": {
    "auto_bill_outstanding": true,
    "setup_fee": {
      "currency_code": "USD",
      "value": "10.0"
    },
    "setup_fee_failure_action": "CONTINUE",
    "payment_failure_threshold": 3
  },
  "taxes": {
    "percentage": "10.0",
    "inclusive": false
  },
  "quantity_supported": false,
  "create_time": "2019-03-26T07:01:04Z",
  "update_time": "2019-03-26T07:01:04Z",
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/billing/plans/P-2UF78835G6983425GLSM44MA",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/billing/plans/P-2UF78835G6983425GLSM44MA",
      "rel": "edit",
      "method": "PATCH"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/billing/plans/P-2UF78835G6983425GLSM44MA/deactivate",
      "rel": "self",
      "method": "POST"
    }
  ]
}

If creating a plan succeeds, it triggers the BILLING.PLAN.CREATED webhook.

3. Create a subscription

To create a subscription for a plan in active status, call /subscriptions. The buyer must consent to the subscription to activate it.

curl -v -k -X POST https://api.sandbox.paypal.com/v1/billing/subscriptions \
   -H "Accept: application/json" \
   -H "Authorization: Bearer Access-Token" \
   -H "PayPal-Request-Id: SUBSCRIPTION-21092019-001" \
   -H "Prefer: return=representation" \
   -H "Content-Type: application/json" \
   -d '{
      "plan_id": "P-2UF78835G6983425GLSM44MA",
      "start_time": "2019-03-27T06:00:00Z",
      "subscriber": {
        "name": {
          "given_name": "John",
          "surname": "Doe"
        },
        "email_address": "customer@example.com"
      },
      "auto_renewal": true,
      "application_context": {
        "brand_name": "example",
        "locale": "en-US",
        "shipping_preference": "SET_PROVIDED_ADDRESS",
        "user_action": "SUBSCRIBE_NOW",
        "payment_method": {
          "payer_selected": "PAYPAL",
          "payee_preferred": "IMMEDIATE_PAYMENT_REQUIRED"
        },
        "return_url": "https://example.com/returnUrl",
        "cancel_url": "https://example.com/cancelUrl"
      }
    }'

curl -v -k -X POST https://api.sandbox.paypal.com/v1/billing/subscriptions \
  -H "Accept: application/json" \
  -H "Authorization: Bearer Access-Token" \
  -H "PayPal-Request-Id: SUBSCRIPTION-21092019-001" \
  -H "Prefer: return=representation" \
  -H "Content-Type: application/json" \
  -d '{
        "plan_id": "P-4ML8771254154362WXNWU5BC",
        "start_time": "2018-11-01T00:00:00Z",
        "quantity": "20",
        "shipping_amount": {
            "currency_code": "USD",
            "value": "10.00"
        },
        "subscriber": {
          "name": {
              "given_name": "John",
              "surname": "Doe"
          },
          "email_address": "customer@example.com",
          "shipping_address": {
              "name": {
                  "full_name": "John Doe"
              },
              "address": {
                  "address_line_1": "2211 N First Street",
                  "address_line_2": "Building 17",
                  "admin_area_2": "San Jose",
                  "admin_area_1": "CA",
                  "postal_code": "95131",
                  "country_code": "US"
              }
          }
        },
        "auto_renewal": true,
        "application_context": {
          "brand_name": "example",
          "locale": "en-US",
          "shipping_preference": "SET_PROVIDED_ADDRESS",
          "user_action": "SUBSCRIBE_NOW",
          "payment_method": {
              "payer_selected": "PAYPAL",
              "payee_preferred": "IMMEDIATE_PAYMENT_REQUIRED"
          },
          "return_url": "https://example.com/returnUrl",
          "cancel_url": "https://example.com/cancelUrl"
        }
      }'

A successful request returns the HTTP 201 Created status code and a JSON response body that shows subscription details:

{
  "id": "I-KK24TMKLGR0P",
  "plan_id": "P-2UF78835G6983425GLSM44MA",
  "start_time": "2019-03-27T06:00:00Z",
  "subscriber": {
    "name": {
      "given_name": "John",
      "surname": "Doe"
    },
    "email_address": "customer@example.com"
  },
  "auto_renewal": true,
  "create_time": "2019-03-26T07:37:44Z",
  "links": [
    {
      "href": "https://www.sandbox.paypal.com/webapps/billing/subscriptions?ba_token=BA-5G371300PF745064S",
      "rel": "approve",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/billing/subscriptions/I-KK24TMKLGR0P",
      "rel": "edit",
      "method": "PATCH"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/billing/subscriptions/I-KK24TMKLGR0P",
      "rel": "self",
      "method": "GET"
    }
  ],
  "status": "APPROVAL_PENDING",
  "status_update_time": "2019-03-26T07:37:44Z"
}

{
  "id": "I-BW452GLLEP1G",
  "status": "APPROVAL_PENDING",
  "status_update_time": "2018-12-10T21:20:49Z",
  "plan_id": "P-4ML8771254154362WXNWU5BC",
  "start_time": "2018-11-01T00:00:00Z",
  "quantity": "20",
  "shipping_amount": {
      "currency_code": "USD",
      "value": "10.00"
  },
  "subscriber": {
    "name": {
      "given_name": "John",
      "surname": "Doe"
      },
      "email_address": "customer@example.com",
      "shipping_address": {
        "name": {
          "full_name": "John Doe"
          },
          "address": {
            "address_line_1": "2211 N First Street",
            "address_line_2": "Building 17",
            "admin_area_2": "San Jose",
            "admin_area_1": "CA",
            "postal_code": "95131",
            "country_code": "US"
          }
      }
  },
  "auto_renewal": true,
  "create_time": "2018-12-10T21:20:49Z",
  "links": [
    {
      "href": "https://www.paypal.com/webapps/billing/subscriptions?ba_token=BA-2M539689T3856352J",
      "rel": "approve",
      "method": "GET"
    },
    {
      "href": "https://api.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G",
      "rel": "edit",
      "method": "PATCH"
    },
    {
      "href": "https://api.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G",
      "rel": "self",
      "method": "GET"
    }
  ]
}

If creating a subscription succeeds, it triggers the BILLING.SUBSCRIPTION.CREATED webhook.

HATEOAS links

To redirect the buyer to log in to their PayPal account to approve the subscription, use the HATEOAS link from the response.

Example of HATEOAS URL:

GET https://www.paypal.com/webapps/billing/subscriptions?ba_token={BA-Token-ID}

Next

Enhance your integration.