Billing Plans API

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 must include at least 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.

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

  • name

    string

    required

    The plan name.

    Maximum length: 128.

  • description

    string

    required

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

    Maximum length: 127.

  • 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.

    Allowed values: FIXED, INFINITE.

    Maximum length: 20.

  • 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.
  • 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.
SDK samples: C#, JAVA, Node, PHP, Python

Sample Request

curl -v -X POST https://api.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.
  • id

    string

    The ID of the plan.

    Read only.

    Maximum length: 128.

  • name

    string

    The plan name.

    Maximum length: 128.

  • description

    string

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

    Maximum length: 127.

  • 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.

  • state

    enum

    The plan status.

    Read only.

    Possible values: CREATED, ACTIVE, INACTIVE.

    Default: CREATED.

  • create_time

    string

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

    Read only.

  • update_time

    string

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

    Read only.

  • 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.
  • terms

    array (contains the terms object)

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

    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.
  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

    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.sandbox.paypal.com/v1/payments/billing-plans/P-7DC96732KA7763723UOPKETA",
      "rel": "self",
      "method": "GET"
    }
  ]
}

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.

    Default: 0.

  • status

    enum

    Filters the plans in the response by a plan status.

    Allowed values: CREATED, ACTIVE, INACTIVE, ALL.

    Default: CREATED.

  • 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.

    Default: 10.

  • total_required

    string

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

    Default: no.

SDK samples: C#, Node, PHP, Python

Sample Request

curl -v -X GET https://api.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.
  • 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.

  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

    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.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.sandbox.paypal.com//v1/payments/billing-plans/P-1TV69435N82273154UPWDU4I",
          "rel": "self",
          "method": "GET"
        }
      ]
    }
  ],
  "links": [
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/billing-plans?page_size=2&page=1&start=3&status=active",
      "rel": "start",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/billing-plans?page_size=2&page=0&status=active",
      "rel": "previous_page",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/billing-plans?page_size=2&page=2&status=active",
      "rel": "next_page",
      "method": "GET"
    },
    {
      "href": "https://api.sandbox.paypal.com/v1/payments/billing-plans?page_size=2&page=82&status=active",
      "rel": "last",
      "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.
SDK samples: C#, JAVA, Node, PHP, Python

Sample Request

curl -v -X PATCH https://api.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.
SDK samples: C#, JAVA, Node, PHP, Python

Sample Request

curl -v -X GET https://api.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.
  • id

    string

    The ID of the plan.

    Read only.

    Maximum length: 128.

  • name

    string

    The plan name.

    Maximum length: 128.

  • description

    string

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

    Maximum length: 127.

  • 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.

  • state

    enum

    The plan status.

    Read only.

    Possible values: CREATED, ACTIVE, INACTIVE.

    Default: CREATED.

  • create_time

    string

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

    Read only.

  • update_time

    string

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

    Read only.

  • 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.
  • terms

    array (contains the terms object)

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

    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.
  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

    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.sandbox.paypal.com/v1/payments/billing-plans/P-7DC96732KA7763723UOPKETA",
      "rel": "self",
      "method": "GET"
    }
  ]
}

Common object definitions

charge_models

  • id

    string

    The ID of the charge model.

    Read only.

    Maximum length: 128.

  • type

    enum

    required

    The charge model type, which is tax or shipping.

    Possible values: TAX, SHIPPING.

    Maximum length: 20.

  • amount

    object

    required

    The currency and amount of the shipping fee or tax.

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

  • 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.

  • message

    string

    required

    The message that describes the error.

    Read only.

  • information_link

    string

    required

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

    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

  • 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.
  • 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.

  • 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.

  • max_fail_attempts

    string

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

    Default: 0.

  • 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.

    Default: NO.

  • 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.

    Default: CONTINUE.

  • accepted_payment_type

    string

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

    Read only.

  • char_set

    string

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

    Read only.

patch

  • op

    enum

    required

    The operation to complete.

    Possible values: add, remove, replace, move, copy, test.

  • 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.
  • from

    string

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

patch_request

  • patch_request

    array (contains the patch object)

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

payment_definition

  • id

    string

    The ID of the payment definition.

    Read only.

    Maximum length: 128.

  • 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.

  • frequency_interval

    string

    required

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

    enum

    required

    The frequency of the payment in this definition.

    Possible values: WEEK, DAY, YEAR, MONTH.

  • cycles

    string

    required

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

    object

    required

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

    array (contains the charge_models object)

    An array of shipping fees and taxes.

plan

  • id

    string

    The ID of the plan.

    Read only.

    Maximum length: 128.

  • name

    string

    required

    The plan name.

    Maximum length: 128.

  • description

    string

    required

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

    Maximum length: 127.

  • 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.

  • state

    enum

    The plan status.

    Read only.

    Possible values: CREATED, ACTIVE, INACTIVE.

    Default: CREATED.

  • create_time

    string

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

    Read only.

  • update_time

    string

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

    Read only.

  • 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.
  • terms

    array (contains the terms object)

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

    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.
  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

    Read only.

plan_list

  • 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.

  • links

    array (contains the link_description object)

    An array of request-related HATEOAS links.

    Read only.

terms

  • id

    string

    The ID of the terms.

    Read only.

    Maximum length: 128.

  • type

    enum

    required

    The term type.

    Possible values: MONTHLY, WEEKLY, YEARLY.

  • 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.
  • 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.

Additional API information

Error messages

In addition to 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.

Feedback

Have feedback?

Let us know.