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.

Important: The use of the PayPal REST /payments APIs to accept credit card payments is restricted. Instead, you can accept credit card payments with:

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

Billing Plans (resource group)

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

Create 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.
A successful request returns the HTTP 201 Created status code and a JSON response body that shows plan details. 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

In the JSON request body, include the plan details including the following plan object properties:

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

    An array of payment definitions for this plan. 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.
  • merchant_preferences

    object

    The merchant preferences for a plan. Includes 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.js, 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": "http://www.paypal.com",
  "cancel_url": "http://www.paypal.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 including the plan state and an ID that uniquely identifies the plan. 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.

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

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

    An array of payment definitions for this plan. 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.
  • 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. Includes 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 object)

    HATEOAS links related to this call.

    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": "http://www.paypal.com",
    "cancel_url": "http://www.paypal.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"
    }
  ]
}

Update 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.
A successful request returns the HTTP 200 OK status code with no JSON response body.

Parameters

  • plan-id

    path string

    The ID of the billing plan to update.

Request

Before you can create an agreement from a plan, you must activate the plan by updating its state to ACTIVE.

  • items

    array (contains the json_patch object)

    JSON patch request to apply partial updates to resources.
SDK samples: C#, JAVA, Node.js, 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": "/merchant-preferences",
  "value": {
    "cancel_url": "http://www.cancel.com",
    "setup_fee": {
    "value": "5",
    "currency": "USD"
    }
  }
  }
]'

Response

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

Sample Response

200 OK

Show plan details

GET /v1/payments/billing-plans/plan-id
Shows details for a billing plan, by ID.
A successful request returns the HTTP 200 OK status code and a JSON response body that shows plan details.

Parameters

  • plan-id

    path string

    The ID of the billing plan for which to show details.
SDK samples: C#, JAVA, Node.js, 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.

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

    An array of payment definitions for this plan. 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.
  • 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. Includes 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 object)

    HATEOAS links related to this call.

    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": "http://www.paypal.com",
    "cancel_url": "http://www.paypal.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 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.
A successful request returns the HTTP 200 OK status code and a JSON response body that lists plans with details.

Parameters

The sample request filters the plans in the response to those with ACTIVE status.

  • page

    query_string string

    The zero-indexed number of the first page that begins the set of pages that are returned in the response. Default is 0.
  • status

    query_string enum

    Filters the plans in the response by a plan status.

    Possible values: CREATED, ACTIVE, INACTIVE.

  • page_size

    query_string 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 is 10.
  • total_required

    query_string string

    Indicates whether the response includes the total_items and total_pages fields. Value is yes or no.
SDK samples: C#, Node.js, PHP, Python

Sample Request

curl -v -X GET https://api.sandbox.paypal.com/v1/payments/billing-plans?page_size=3&status=ACTIVE&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 billing plans with plan details. The response includes a set of HATEOAS links that enable you to navigate to the first, last, previous, and next plan.

  • 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 object)

    HATEOAS links related to this call.

    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": "ACTIVE",
      "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"
    }
  ]
}

Common object definitions

charge_models

  • id

    string

    The ID of the charge model.

    Read only.

    Maximum length: 128.

  • type

    enum

    The charge model type, which is tax or shipping.

    Possible values: TAX, SHIPPING.

    Maximum length: 20.

  • amount

    object

    The amount.

currency

  • currency

    string

    The three-letter ISO 4217 alphabetic currency code.
  • value

    string

    The amount up to N digits after the decimal separator, as defined in ISO 4217 for the appropriate currency code.

json_patch

  • op

    enum

    The operation to perform.

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

  • path

    string

    A JSON pointer. References a location in the target document where the operation is performed.
  • value

    see description

    The value to apply. The remove operation does not require a value.
    Possible types: number, integer, string, boolean, null, array, object
  • from

    string

    A JSON pointer. References the location in the target document from which to move the value. Required for the move operation.

json_patch_request

  • items

    (contains the json_patch object)

    JSON patch request to apply partial updates to resources.

merchant_preferences

  • setup_fee

    object

    The fee to set up the agreement. This fee is the initial, non-recurring payment amount due immediately upon billing agreement creation. Can be used as the initial amount to trigger the initial_fail_amount_action. Default is 0.
  • cancel_url

    string

    The URL where the customer can cancel the agreement.

    Maximum length: 1000.

  • return_url

    string

    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. Default is 0, which allows infinite failed payment attempts.
  • 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. Default is NO.
    • YES. PayPal automatically bills the customer the outstanding balance.

      Possible values: YES, 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. Default is CONTINUE.
      • 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.

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

    payment_definition

    • id

      string

      The ID of the payment definition.

      Read only.

      Maximum length: 128.

    • name

      string

      The payment definition name.

      Maximum length: 128.

    • type

      enum

      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

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

      enum

      The frequency of the payment in this definition.

      Possible values: WEEK, DAY, YEAR, MONTH.

    • cycles

      string

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

      object

      The amount to charge 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

      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.

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

      An array of payment definitions for this plan. 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.
    • 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. Includes 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 object)

      HATEOAS links related to this call.

      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 object)

      HATEOAS links related to this call.

      Read only.

    terms

    • id

      string

      The ID of the terms.

      Read only.

      Maximum length: 128.

    • type

      enum

      The term type.

      Possible values: MONTHLY, WEEKLY, YEARLY.

    • max_billing_amount

      object

      The maximum amount to bill for this term.
    • occurrences

      string

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

      object

      The amount range for this term.
    • buyer_editable

      string

      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.