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": "2020-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": "2020-02-26T07:01:04Z",
      "update_time": "2020-02-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.

To change the price plan, call /plans/ID/update-pricing-schemes where ID is the plan ID.

The price change affects subscribers as follows:

  • New subscribers see the latest price.

  • Existing subscribers are 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.

    Note: This 10-day rule is not applicable for direct card subscriptions.

  • If you change the pricing for a trial period, the price change does not affect subscribers currently in a trial period.

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.