Billing Plans API

Deprecation notice: The /v1/payments/billing-plans endpoints are deprecated. Use the /v1/billing/plans endpoints instead. For details, see Subscriptions Integration.
You use billing plans and billing agreements to create an agreement for a recurring PayPal or debit card payment for goods or services.

A billing plan includes payment definitions and other details. A plan can include only one regular payment definition and, optionally, a trial payment definition. Each definition determines how often and for how long a customer is charged.

A plan can specify a type, which indicates whether the payment definitions in the plan have a fixed or infinite number of payment cycles. The plan also defines merchant preferences including how much it costs to set up the agreement, the links where a customer can approve or can cancel the agreement, and the action if the customer's initial payment fails.

By default, a plan is not active when you create it. To activate it, you update its state to ACTIVE.

For more information, see Billing Plans and Agreements.
Important: The use of the PayPal REST /payments APIs to accept credit card payments is restricted. Instead, you can accept credit card payments with Braintree Direct.

Billing plans (resource group)

Use the /billing-plans resource to create, update, show details for, and list plans.

List billing plans

GET/v1/payments/billing-plans
Lists billing plans. To filter the plans that appear in the response, specify one or more optional query and pagination parameters.

Query parameters

  • page

    string

    The zero-indexed number of the first page that begins the set of pages that are returned in the response.

  • page_size

    string

    The number of plans to list on a single page. For example, if page_size is 10, each page shows ten plans. A valid value is a non-negative, non-zero integer.

  • status

    enum

    Filters the plans in the response by a plan status.

    Possible values: CREATED,ACTIVE,INACTIVE,ALL.

  • total_required

    string

    Indicates whether the response includes the total_items and total_pages fields. Value is yes or no.

Sample Request

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

Response

A successful request returns the HTTP 200 OK status code and a JSON response body that lists plans with details.
  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

    Read only.

  • plans

    array (contains the plan object)

    An array of plans.

  • total_items

    string

    The total number of plans in the list.

    Read only.

  • total_pages

    string

    The total number of pages in the response. The page_size request value determines how many plans appear on each page. The total_items and page_size request values are used to calculate the total number of pages in the response.

    Read only.

Sample Response

{
  "total_items": "166",
  "total_pages": "83",
  "plans": [
    {
      "id": "P-7DC96732KA7763723UOPKETA",
      "state": "ACTIVE",
      "name": "Plan with Regular and Trial Payment Definitions",
      "description": "Plan with regular and trial billing payment definitions.",
      "type": "FIXED",
      "create_time": "2017-08-22T04:41:52.836Z",
      "update_time": "2017-08-22T04:41:53.169Z",
      "links": [
        {
          "href": "https://api-m.sandbox.paypal.com//v1/payments/billing-plans/P-7DC96732KA7763723UOPKETA",
          "rel": "self",
          "method": "GET"
        }
      ]
    },
    {
      "id": "P-1TV69435N82273154UPWDU4I",
      "state": "INACTIVE",
      "name": "Plan with Regular Payment Definition",
      "description": "Plan with one regular payment definition, minimal merchant preferences, and no shipping fees or tax.",
      "type": "INFINITE",
      "create_time": "2017-08-22T04:41:55.623Z",
      "update_time": "2017-08-22T04:41:56.055Z",
      "links": [
        {
          "href": "https://api-m.sandbox.paypal.com//v1/payments/billing-plans/P-1TV69435N82273154UPWDU4I",
          "rel": "self",
          "method": "GET"
        }
      ]
    }
  ],
  "links": [
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/billing-plans?page_size=2&page=1&start=3&status=active",
      "rel": "start",
      "method": "GET"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/billing-plans?page_size=2&page=0&status=active",
      "rel": "previous_page",
      "method": "GET"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/billing-plans?page_size=2&page=2&status=active",
      "rel": "next_page",
      "method": "GET"
    },
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/billing-plans?page_size=2&page=82&status=active",
      "rel": "last",
      "method": "GET"
    }
  ]
}

Create billing plan

POST/v1/payments/billing-plans
Creates a billing plan. In the JSON request body, include the plan details. A plan must include at least one regular payment definition and, optionally, a trial payment definition. Each payment definition specifies a billing period, which determines how often and for how long the customer is charged. A plan can specify a fixed or infinite number of payment cycles. A payment definition can optionally specify shipping fee and tax amounts. The default state of a new plan is CREATED. Before you can create an agreement from a plan, you must activate the plan by updating its state to ACTIVE.

Request body

  • description

    string

    required

    The plan description. Maximum length is 127 single-byte alphanumeric characters.

    Maximum length: 127.

  • name

    string

    required

    The plan name.

    Maximum length: 128.

  • type

    enum

    required

    The plan type. Indicates whether the payment definitions in the plan have a fixed number of or infinite payment cycles. Value is:

    • FIXED. The plan has a fixed number of payment cycles.
    • INFINITE. The plan has infinite, or 0, payment cycles.

    Possible values: FIXED,INFINITE.

    Maximum length: 20.

  • create_time

    string

    The date and time when the plan was created, in Internet date and time format.

  • id

    string

    The ID of the plan.

    Maximum length: 128.

  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

  • merchant_preferences

    object

    The merchant preferences for a plan, which define how much it costs to set up the agreement, the URLs where the customer can approve or cancel the agreement, the maximum number of allowed failed payment attempts, whether PayPal automatically bills the outstanding balance in the next billing cycle, and the action if the customer's initial payment fails.

  • payment_definitions

    array (contains the payment_definition object)

    A payment definition, which determines how often and for how long the customer is charged. Includes the interval at which the customer is charged, the charge amount, and optional shipping fees and taxes.

  • state

    enum

    The plan status.

    Possible values: CREATED,ACTIVE,INACTIVE.

  • terms

    array (contains the terms object)

    An array of terms for this plan. Read-only and reserved for future use.

  • update_time

    string

    The date and time when the plan was updated, in Internet date and time format.

Sample Request

curl -v -X POST https://api-m.sandbox.paypal.com/v1/payments/billing-plans/ \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "name": "Plan with Regular and Trial Payment Definitions",
  "description": "Plan with regular and trial payment definitions.",
  "type": "FIXED",
  "payment_definitions": [
    {
      "name": "Regular payment definition",
      "type": "REGULAR",
      "frequency": "MONTH",
      "frequency_interval": "2",
      "amount": {
        "value": "100",
        "currency": "USD"
      },
      "cycles": "12",
      "charge_models": [
        {
          "type": "SHIPPING",
          "amount": {
            "value": "10",
            "currency": "USD"
          }
        },
        {
          "type": "TAX",
          "amount": {
            "value": "12",
            "currency": "USD"
          }
        }
      ]
    },
    {
      "name": "Trial payment definition",
      "type": "TRIAL",
      "frequency": "WEEK",
      "frequency_interval": "5",
      "amount": {
        "value": "9.19",
        "currency": "USD"
      },
      "cycles": "2",
      "charge_models": [
        {
          "type": "SHIPPING",
          "amount": {
            "value": "1",
            "currency": "USD"
          }
        },
        {
          "type": "TAX",
          "amount": {
            "value": "2",
            "currency": "USD"
          }
        }
      ]
    }
  ],
  "merchant_preferences": {
    "setup_fee": {
      "value": "1",
      "currency": "USD"
    },
    "return_url": "https://example.com",
    "cancel_url": "https://example.com/cancel",
    "auto_bill_amount": "YES",
    "initial_fail_amount_action": "CONTINUE",
    "max_fail_attempts": "0"
  }
}'

Response

A successful request returns the HTTP 201 Created status code and a JSON response body that shows plan details.
  • create_time

    string

    The date and time when the plan was created, in Internet date and time format.

    Read only.

  • description

    string

    The plan description. Maximum length is 127 single-byte alphanumeric characters.

    Maximum length: 127.

  • id

    string

    The ID of the plan.

    Read only.

    Maximum length: 128.

  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

    Read only.

  • merchant_preferences

    object

    The merchant preferences for a plan, which define how much it costs to set up the agreement, the URLs where the customer can approve or cancel the agreement, the maximum number of allowed failed payment attempts, whether PayPal automatically bills the outstanding balance in the next billing cycle, and the action if the customer's initial payment fails.

  • name

    string

    The plan name.

    Maximum length: 128.

  • payment_definitions

    array (contains the payment_definition object)

    A payment definition, which determines how often and for how long the customer is charged. Includes the interval at which the customer is charged, the charge amount, and optional shipping fees and taxes.

  • state

    enum

    The plan status.

    Read only.

    Possible values: CREATED,ACTIVE,INACTIVE.

  • terms

    array (contains the terms object)

    An array of terms for this plan. Read-only and reserved for future use.

    Read only.

  • type

    enum

    The plan type. Indicates whether the payment definitions in the plan have a fixed number of or infinite payment cycles. Value is:

    • FIXED. The plan has a fixed number of payment cycles.
    • INFINITE. The plan has infinite, or 0, payment cycles.

    Possible values: FIXED,INFINITE.

    Maximum length: 20.

  • update_time

    string

    The date and time when the plan was updated, in Internet date and time format.

    Read only.

Sample Response

{
  "id": "P-7DC96732KA7763723UOPKETA",
  "state": "CREATED",
  "name": "Plan with Regular and Trial Payment Definitions",
  "description": "Plan with regular and trial payment definitions.",
  "type": "FIXED",
  "payment_definitions": [
    {
      "id": "PD-0MF87809KK310750TUOPKETA",
      "name": "Regular payment definition",
      "type": "REGULAR",
      "frequency": "MONTH",
      "amount": {
        "currency": "USD",
        "value": "100"
      },
      "charge_models": [
        {
          "id": "CHM-89H01708244053321UOPKETA",
          "type": "SHIPPING",
          "amount": {
            "currency": "USD",
            "value": "10"
          }
        },
        {
          "id": "CHM-1V202179WT9709019UOPKETA",
          "type": "TAX",
          "amount": {
            "currency": "USD",
            "value": "12"
          }
        }
      ],
      "cycles": "12",
      "frequency_interval": "2"
    },
    {
      "id": "PD-03223056L66578712UOPKETA",
      "name": "Trial payment definition",
      "type": "TRIAL",
      "frequency": "WEEK",
      "amount": {
        "currency": "USD",
        "value": "9.19"
      },
      "charge_models": [
        {
          "id": "CHM-7XN63093LF858372XUOPKETA",
          "type": "SHIPPING",
          "amount": {
            "currency": "USD",
            "value": "1"
          }
        },
        {
          "id": "CHM-6JY06508UT8026625UOPKETA",
          "type": "TAX",
          "amount": {
            "currency": "USD",
            "value": "2"
          }
        }
      ],
      "cycles": "2",
      "frequency_interval": "5"
    }
  ],
  "merchant_preferences": {
    "setup_fee": {
      "currency": "USD",
      "value": "1"
    },
    "max_fail_attempts": "0",
    "return_url": "https://example.com",
    "cancel_url": "https://example.com/cancel",
    "auto_bill_amount": "YES",
    "initial_fail_amount_action": "CONTINUE"
  },
  "create_time": "2017-06-16T07:40:20.940Z",
  "update_time": "2017-06-16T07:40:20.940Z",
  "links": [
    {
      "href": "https://api-m.sandbox.paypal.com/v1/payments/billing-plans/P-7DC96732KA7763723UOPKETA",
      "rel": "self",
      "method": "GET"
    }
  ]
}

Update billing plan

PATCH/v1/payments/billing-plans/{plan_id}
Updates fields in a billing plan, by ID. In the JSON request body, include a patch object that specifies the operation to perform, one or more fields to update, and a new value for each updated field.

Path parameters

  • plan_id

    string

    required

    The ID of the billing plan to update.

Request body

  • patch_request

    array (contains the patch object)

    An array of JSON patch objects to apply partial updates to resources.

Sample Request

curl -v -X PATCH https://api-m.sandbox.paypal.com/v1/payments/billing-plans/P-6EM196669U062173D7QCVDRA/ \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '[
  {
    "op": "replace",
    "path": "/",
    "value": {
      "state": "ACTIVE"
    }
  }
]'

Response

A successful request returns the HTTP 200 OK status code with no JSON response body.

    Sample Response

    200 OK

    Show billing plan details

    GET/v1/payments/billing-plans/{plan_id}
    Shows details for a billing plan, by ID.

    Path parameters

    • plan_id

      string

      required

      The ID of the billing plan for which to show details.

    Sample Request

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

    Response

    A successful request returns the HTTP 200 OK status code and a JSON response body that shows plan details.
    • create_time

      string

      The date and time when the plan was created, in Internet date and time format.

      Read only.

    • description

      string

      The plan description. Maximum length is 127 single-byte alphanumeric characters.

      Maximum length: 127.

    • id

      string

      The ID of the plan.

      Read only.

      Maximum length: 128.

    • links

      array (contains the link_description object)

      An array of request-related HATEOAS links.

      Read only.

    • merchant_preferences

      object

      The merchant preferences for a plan, which define how much it costs to set up the agreement, the URLs where the customer can approve or cancel the agreement, the maximum number of allowed failed payment attempts, whether PayPal automatically bills the outstanding balance in the next billing cycle, and the action if the customer's initial payment fails.

    • name

      string

      The plan name.

      Maximum length: 128.

    • payment_definitions

      array (contains the payment_definition object)

      A payment definition, which determines how often and for how long the customer is charged. Includes the interval at which the customer is charged, the charge amount, and optional shipping fees and taxes.

    • state

      enum

      The plan status.

      Read only.

      Possible values: CREATED,ACTIVE,INACTIVE.

    • terms

      array (contains the terms object)

      An array of terms for this plan. Read-only and reserved for future use.

      Read only.

    • type

      enum

      The plan type. Indicates whether the payment definitions in the plan have a fixed number of or infinite payment cycles. Value is:

      • FIXED. The plan has a fixed number of payment cycles.
      • INFINITE. The plan has infinite, or 0, payment cycles.

      Possible values: FIXED,INFINITE.

      Maximum length: 20.

    • update_time

      string

      The date and time when the plan was updated, in Internet date and time format.

      Read only.

    Sample Response

    {
      "id": "P-7DC96732KA7763723UOPKETA",
      "state": "CREATED",
      "name": "Plan with Regular and Trial Payment Definitions",
      "description": "Plan with regular and trial payment definitions.",
      "type": "FIXED",
      "payment_definitions": [
        {
          "id": "PD-03223056L66578712UOPKETA",
          "name": "Trial payment definition",
          "type": "TRIAL",
          "frequency": "WEEK",
          "amount": {
            "currency": "USD",
            "value": "9.19"
          },
          "charge_models": [
            {
              "id": "CHM-6JY06508UT8026625UOPKETA",
              "type": "TAX",
              "amount": {
                "currency": "USD",
                "value": "2"
              }
            },
            {
              "id": "CHM-7XN63093LF858372XUOPKETA",
              "type": "SHIPPING",
              "amount": {
                "currency": "USD",
                "value": "1"
              }
            }
          ],
          "cycles": "2",
          "frequency_interval": "5"
        },
        {
          "id": "PD-0MF87809KK310750TUOPKETA",
          "name": "Regular payment definition",
          "type": "REGULAR",
          "frequency": "MONTH",
          "amount": {
            "currency": "USD",
            "value": "100"
          },
          "charge_models": [
            {
              "id": "CHM-1V202179WT9709019UOPKETA",
              "type": "TAX",
              "amount": {
                "currency": "USD",
                "value": "12"
              }
            },
            {
              "id": "CHM-89H01708244053321UOPKETA",
              "type": "SHIPPING",
              "amount": {
                "currency": "USD",
                "value": "10"
              }
            }
          ],
          "cycles": "12",
          "frequency_interval": "2"
        }
      ],
      "merchant_preferences": {
        "setup_fee": {
          "currency": "USD",
          "value": "1"
        },
        "max_fail_attempts": "0",
        "return_url": "https://example.com",
        "cancel_url": "https://example.com/cancel",
        "auto_bill_amount": "YES",
        "initial_fail_amount_action": "CONTINUE"
      },
      "create_time": "2017-06-16T07:40:20.940Z",
      "update_time": "2017-06-16T07:40:20.940Z",
      "links": [
        {
          "href": "https://api-m.sandbox.paypal.com/v1/payments/billing-plans/P-7DC96732KA7763723UOPKETA",
          "rel": "self",
          "method": "GET"
        }
      ]
    }

    Common object definitions

    charge_models

    • amount

      object

      required

      The currency and amount of the shipping fee or tax.

    • type

      enum

      required

      The charge model type, which is tax or shipping.

      Possible values: TAX,SHIPPING.

      Maximum length: 20.

    • id

      string

      The ID of the charge model.

      Read only.

      Maximum length: 128.

    currency

    • currency

      string

      required

    • value

      string

      required

      The value, which might be:

      • An integer for currencies like JPY that are not typically fractional.
      • A decimal fraction for currencies like TND that are subdivided into thousandths.
      For the required number of decimal places for a currency code, see Currency codes - ISO 4217.

    error

    • information_link

      string

      required

      The URI to detailed information related to this error for the developer.

      Read only.

    • message

      string

      required

      The message that describes the error.

      Read only.

    • name

      string

      required

      The human-readable, unique name of the error.

      Read only.

    • debug_id

      string

      The PayPal internal ID. Used for correlation purposes.

      Read only.

    • details

      array (contains the error_details object)

      An array of additional details for the error.

      Read only.

    error_details

    • field

      string

      required

      The name of the field that caused the error.

    • issue

      string

      required

      The reason for the error.

    merchant_preferences

    • cancel_url

      string

      required

      The URL where the customer can cancel the agreement.

      Maximum length: 1000.

    • return_url

      string

      required

      The URL where the customer can approve the agreement.

      Maximum length: 1000.

    • accepted_payment_type

      string

      The payment types that are accepted for this plan. Read-only and reserved for future use.

      Read only.

    • auto_bill_amount

      enum

      Indicates whether PayPal automatically bills the outstanding balance in the next billing cycle. The outstanding balance is the total amount of any previously failed scheduled payments. Value is:

      • NO. PayPal does not automatically bill the customer the outstanding balance.
      • YES. PayPal automatically bills the customer the outstanding balance.

      Possible values: YES,NO.

    • char_set

      string

      The character set for this plan. Read-only and reserved for future use.

      Read only.

    • initial_fail_amount_action

      enum

      The action if the customer's initial payment fails. Value is:

      • CONTINUE. The agreement remains active and the failed payment amount is added to the outstanding balance. If auto-billing is enabled, PayPal automatically bills the outstanding balance in the next billing cycle.
      • CANCEL PayPal creates the agreement but sets its state to pending until the initial payment clears. If the initial payment clears, the pending agreement becomes active. If the initial payment fails, the pending agreement is canceled.
      Note: You can use the setup_fee value as the initial amount to trigger the initial_fail_amount_action.

      Possible values: CONTINUE,CANCEL.

    • max_fail_attempts

      string

      The maximum number of allowed failed payment attempts. The default value, which is 0, defines infinite failed payment attempts.

    • notify_url

      string

      The URL where the customer is notified that the agreement was created. Read-only and reserved for future use.

      Read only.

      Maximum length: 1000.

    • setup_fee

      object

      The currency and amount of the set-up fee for the agreement. This fee is the initial, non-recurring payment amount that is due immediately when the billing agreement is created. Can be used as the initial amount to trigger the initial_fail_amount_action. The default for the amount is 0.

    patch

    • op

      enum

      required

      The operation.

      The possible values are:

      • add. Depending on the target location reference, completes one of these functions:
        • The target location is an array index. Inserts a new value into the array at the specified index.
        • The target location is an object parameter that does not already exist. Adds a new parameter to the object.
        • The target location is an object parameter that does exist. Replaces that parameter's value.
        The value parameter defines the value to add. For more information, see 4.1. add.
      • remove. Removes the value at the target location. For the operation to succeed, the target location must exist. For more information, see 4.2. remove.
      • replace. Replaces the value at the target location with a new value. The operation object must contain a value parameter that defines the replacement value. For the operation to succeed, the target location must exist. For more information, see 4.3. replace.
      • move. Removes the value at a specified location and adds it to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to move the value. For the operation to succeed, the from location must exist. For more information, see 4.4. move.
      • copy. Copies the value at a specified location to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to copy the value. For the operation to succeed, the from location must exist. For more information, see 4.5. copy.
      • test. Tests that a value at the target location is equal to a specified value. The operation object must contain a value parameter that defines the value to compare to the target location's value. For the operation to succeed, the target location must be equal to the value value. For test, equal indicates that the value at the target location and the value that value defines are of the same JSON type. The data type of the value determines how equality is defined:
        TypeConsidered equal if both values
        stringsContain the same number of Unicode characters and their code points are byte-by-byte equal.
        numbersAre numerically equal.
        arraysContain the same number of values, and each value is equal to the value at the corresponding position in the other array, by using these type-specific rules.
        objectsContain the same number of parameters, and each parameter is equal to a parameter in the other object, by comparing their keys (as strings) and their values (by using these type-specific rules).
        literals (false, true, and null)Are the same. The comparison is a logical comparison. For example, whitespace between the parameter values of an array is not significant. Also, ordering of the serialization of object parameters is not significant.
        For more information, see 4.6. test.
    • from

      string

      The JSON Pointer to the target document location from which to move the value. Required for the move operation.

    • path

      string

      The JSON Pointer to the target document location at which to complete the operation.

    • value

      number,integer,string,boolean,null,array,object

      The value to apply. The remove operation does not require a value.

    patch_request

    • patch_request

      array (contains the patch object)

      An array of JSON patch objects to apply partial updates to resources.

    payment_definition

    • amount

      object

      required

      The currency and amount of the charge to make at the end of each payment cycle for this definition.

    • cycles

      string

      required

      The number of payment cycles. For infinite plans with a regular payment definition, set cycles to 0.

    • frequency

      enum

      required

      The frequency of the payment in this definition.

      Possible values: WEEK,DAY,YEAR,MONTH.

    • frequency_interval

      string

      required

      The interval at which the customer is charged. Value cannot be greater than 12 months.

    • name

      string

      required

      The payment definition name.

      Maximum length: 128.

    • type

      enum

      required

      The payment definition type. Each plan must have at least one regular payment definition and, optionally, a trial payment definition. Each definition specifies how often and for how long the customer is charged.

      Possible values: TRIAL,REGULAR.

    • charge_models

      array (contains the charge_models object)

      An array of shipping fees and taxes.

    • id

      string

      The ID of the payment definition.

      Read only.

      Maximum length: 128.

    plan

    • description

      string

      required

      The plan description. Maximum length is 127 single-byte alphanumeric characters.

      Maximum length: 127.

    • name

      string

      required

      The plan name.

      Maximum length: 128.

    • type

      enum

      required

      The plan type. Indicates whether the payment definitions in the plan have a fixed number of or infinite payment cycles. Value is:

      • FIXED. The plan has a fixed number of payment cycles.
      • INFINITE. The plan has infinite, or 0, payment cycles.

      Possible values: FIXED,INFINITE.

      Maximum length: 20.

    • create_time

      string

      The date and time when the plan was created, in Internet date and time format.

      Read only.

    • id

      string

      The ID of the plan.

      Read only.

      Maximum length: 128.

    • links

      array (contains the link_description object)

      An array of request-related HATEOAS links.

      Read only.

    • merchant_preferences

      object

      The merchant preferences for a plan, which define how much it costs to set up the agreement, the URLs where the customer can approve or cancel the agreement, the maximum number of allowed failed payment attempts, whether PayPal automatically bills the outstanding balance in the next billing cycle, and the action if the customer's initial payment fails.

    • payment_definitions

      array (contains the payment_definition object)

      A payment definition, which determines how often and for how long the customer is charged. Includes the interval at which the customer is charged, the charge amount, and optional shipping fees and taxes.

    • state

      enum

      The plan status.

      Read only.

      Possible values: CREATED,ACTIVE,INACTIVE.

    • terms

      array (contains the terms object)

      An array of terms for this plan. Read-only and reserved for future use.

      Read only.

    • update_time

      string

      The date and time when the plan was updated, in Internet date and time format.

      Read only.

    plan_list

    • links

      array (contains the link_description object)

      An array of request-related HATEOAS links.

      Read only.

    • plans

      array (contains the plan object)

      An array of plans.

    • total_items

      string

      The total number of plans in the list.

      Read only.

    • total_pages

      string

      The total number of pages in the response. The page_size request value determines how many plans appear on each page. The total_items and page_size request values are used to calculate the total number of pages in the response.

      Read only.

    terms

    • amount_range

      object

      required

      The currency and amount range for this term.

    • buyer_editable

      string

      required

      Indicates whether the customer can edit the amount in this term.

    • max_billing_amount

      object

      required

      The currency and amount of the maximum billing amount for this term.

    • occurrences

      string

      required

      The number of times that money can be pulled during this term.

    • type

      enum

      required

      The term type.

      Possible values: MONTHLY,WEEKLY,YEARLY.

    • id

      string

      The ID of the terms.

      Read only.

      Maximum length: 128.

    Additional API information

    Error messages

    In addition to the common HTTP status codes that the REST APIs return, the Billing Plans API can return the following errors.

    • INTERNAL_SERVICE_ERROR

      An internal service error has occurred.

      Resend the request at another time. If this error continues, contact PayPal Merchant Technical Support.

    • REQUIRED_SCOPE_MISSING

      Access token does not have required scope.

      Use the scope required for this request type to get buyer consent.

    • UNAUTHORIZED_ACCESS

      You don't have permission to access this resource.

      Pass a valid plan ID.

    • VALIDATION_ERROR

      Invalid request - see details.

      A validation issue occurred with your request.