subscriptions

Subscriptions Plan Management

List plans

To list plans for a merchant, call /plans.

To filter the plans that the call returns, you can include one or more query parameters:

  • page. A non-zero integer index of the merchant's list of plans. Default is 1.
  • page_size. The number of plans to retrieve, beginning with the specified page. Default is 10.
  • total_required. Returns the total number of items and pages in the response. Default is false.

This sample request returns the first ten merchant plans:

curl -v -X GET https://api.sandbox.paypal.com/v1/billing/plans?page_size=2&page=1&total_required=true \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"

A successful request returns the HTTP 200 OK status code and a JSON response body.

  {
    "id": "P-5ML4271244454362WXNWU5NQ",
    "name": "Marketing Campaign Plan",
    "create_time": "2018-12-10T21:20:49Z",
    "links": [{
      "href": "https://api.paypal.com/v1/billing/plans/P-5ML4271244454362WXNWU5NQ",
      "rel": "self",
      "method": "GET"
    }]
  },
  {
    "id": "P-6LL4271454454362WXNWU5NQ",
    "name": "Marketing Campaign Basic Plan",
    "create_time": "2019-01-10T21:20:49Z",
    "links": [{
      "href": "https://api.paypal.com/v1/billing/plans/P-6LL4271454454362WXNWU5NQ",
      "rel": "self",
      "method": "GET"
    }]
  }
],
"links": [
  {
    "href": "https://api.paypal.com/v1/billing/plans?page_size=2&page=1",
    "rel": "self",
    "method": "GET"
  },
  {
    "href": "https://api.paypal.com/v1/billing/plans?page_size=2&page=2",
    "rel": "next",
    "method": "GET"
  },
  {
    "href": "https://api.paypal.com/v1/billing/plans?page_size=2&page=6",
    "rel": "last",
    "method": "GET"
  }
]

Show plan details

To show the details for a plan, call /plans id, where <id> is the plan ID.

This sample request show the details for a flat plan, by ID:

curl -v -X GET https://api.sandbox.paypal.com/v1/billing/plans/P-2UF78835G6983425GLSM44MA \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer Access-Token"

A successful request returns the HTTP 200 OK status code and a JSON response body.

{
      "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.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"
      }
    ]
  }

Update plan

You can update a plan in active or created state. These changes are applicable immediately for both existing subscriptions and new subscriptions. You cannot update an inactive plan.

You can replace these fields:

Attribute Operations
description replace
auto_bill_outstanding replace
taxes.percentage replace
payment_preferences.payment_failure_threshold replace

To update a plan call /plans id, where <id> is the plan ID. Include a PATCH request object that defines the fields to update.

A successful request returns the HTTP 204 No Content status code with no JSON response body.

This sample request updates the payment failure threshold to 7:

{
  curl -v -X PATCH https://api.sandbox.paypal.com/v1/billing/plans/P-7GL4271244454362WXNWU5NQ \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer Access-Token" \
  -d '[
    {
      "op": "replace",
      "path": "/payment_preferences/payment_failure_threshold",
      "value": 7
    }
  ]
}'

A successful request returns the HTTP 204 No Content status code with no JSON response body.

If the update succeeds, it triggers the BILLING.PLAN.UPDATED webhook.

Activate plan

To activate a plan, call /plans id/activate, where <id> is the plan ID.

Note: You cannot create a subscription for the plan until it is activated.

This sample request activates a plan, by ID:

curl -v -X POST https://api.sandbox.paypal.com/v1/billing/plans/P-7GL4271244454362WXNWU5NQ/activate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer Access-Token"

A successful request returns the HTTP 204 No Content status code with no JSON response body.

If the plan activation succeeds, it triggers the BILLING.PLAN.ACTIVATED webhook.

Deactivate plan

To deactivate a plan, call /plans id/deactivate, where <id> is the plan ID.

Note: You cannot create a subscription from a deactivated plan. However, you can continue to bill subscriptions until you cancel them or they expire.

This sample request deactivates a plan:

curl -v -X POST https://api.sandbox.paypal.com/v1/billing/plans/P-7GL4271244454362WXNWU5NQ/deactivate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer Access-Token"

A successful request returns the HTTP 204 No Content status code with no JSON response body.

If deactivation succeeds, it triggers the BILLING.PLAN.DEACTIVATED webhook.

Update pricing

You can revise the price of an existing plan seamlessly, without migrating your subscribers.

Call /update-pricing-schemes to make a one-time price change, up to a maximum of 20% of the original price.

The price change affects subscribers as follows:

  • New subscribers see the latest price.
  • For existing subscribers, a legal mandate requires that all existing consumers be informed of the price change 10 or more days in advance. Billing cycles within 10 days of the price change are not affected until the next billing cycle.

The API returns an error on the following operations:

  • When the price change is greater than 20% of original price.
  • When there are multiple updates on the same plan.

This sample request updates plan pricing:

curl -v -X POST https://api.sandbox.paypal.com/v1/billing/plans/P-2UF78835G6983425GLSM44MA/update-pricing-schemes \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer Access-Token" \
-d '{
  "pricing_schemes": [{
    "billing_cycle_sequence": 2,
    "pricing_scheme": {
      "fixed_price": {
        "value": "50",
        "currency_code": "USD"
        }
      }
    }
  ]
}'

A successful request returns the HTTP 204 No Content status code with no JSON response body.

The activation of a pricing change triggers the BILLING.PLAN.PRICING.CHANGE.ACTIVATED webhook.

Feedback