Billing Plans API
Deprecation notice: TheYou use billing plans and billing agreements to create an agreement for a recurring PayPal or debit card payment for goods or services./v1/payments/billing-plans
endpoints are deprecated. Use the/v1/billing/plans
endpoints instead. For details, see Subscriptions Integration.
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
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
is10
, 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.
total_required
string
Indicates whether the response includes the
total_items
andtotal_pages
fields. Value isyes
orno
.
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
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.
plans
array (contains the plan object)
An array of plans.
total_items
string
The total number of plans in the list.
total_pages
string
The total number of pages in the response. The
page_size
request value determines how many plans appear on each page. Thetotal_items
andpage_size
request values are used to calculate the total number of pages in the response.
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
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.
name
string
required
The plan name.
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, or0
, payment cycles.
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.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
merchant_preferences
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.
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
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.
description
string
The plan description. Maximum length is 127 single-byte alphanumeric characters.
id
string
The ID of the plan.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
merchant_preferences
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.
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.
terms
array (contains the terms object)
An array of terms for this plan. Read-only and reserved for future use.
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, or0
, payment cycles.
update_time
string
The date and time when the plan was updated, in Internet date and time format.
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
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
200 OK
status code with no JSON response body.Sample Response
200 OK
Show billing plan details
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
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.
description
string
The plan description. Maximum length is 127 single-byte alphanumeric characters.
id
string
The ID of the plan.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
merchant_preferences
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.
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.
terms
array (contains the terms object)
An array of terms for this plan. Read-only and reserved for future use.
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, or0
, payment cycles.
update_time
string
The date and time when the plan was updated, in Internet date and time format.
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
The currency and amount of the shipping fee or tax.
type
enum
required
The charge model type, which is tax or shipping.
id
string
The ID of the charge model.
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.
- An integer for currencies like
error
information_link
string
required
The URI to detailed information related to this error for the developer.
message
string
required
The message that describes the error.
name
string
required
The human-readable, unique name of the error.
debug_id
string
The PayPal internal ID. Used for correlation purposes.
details
array (contains the error_details object)
An array of additional details for the error.
error_details
field
string
required
The name of the field that caused the error.
issue
string
required
The reason for the error.
link_description
href
string
required
The complete target URL. To make the related call, combine the method with this URI Template-formatted link. For pre-processing, include the
$
,(
, and)
characters. Thehref
is the key HATEOAS component that links a completed call with a subsequent call.rel
string
required
The link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations.
method
enum
The HTTP method required to make the related call.
merchant_preferences
cancel_url
string
required
The URL where the customer can cancel the agreement.
return_url
string
required
The URL where the customer can approve the agreement.
accepted_payment_type
string
The payment types that are accepted for this plan. Read-only and reserved for future use.
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.
char_set
string
The character set for this plan. Read-only and reserved for future use.
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 theinitial_fail_amount_action
.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.
setup_fee
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 is0
.
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.
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 avalue
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 afrom
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, thefrom
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 afrom
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, thefrom
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 avalue
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 thevalue
value. For test,equal
indicates that the value at the target location and the value thatvalue
defines are of the same JSON type. The data type of the value determines how equality is defined:
For more information, see 4.6. test.Type Considered equal if both values strings Contain the same number of Unicode characters and their code points are byte-by-byte equal. numbers Are numerically equal. arrays Contain 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. objects Contain 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
, andnull
)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.
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
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
to0
.frequency
enum
required
The frequency of the payment in this definition.
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.
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.
charge_models
array (contains the charge_models object)
An array of shipping fees and taxes.
id
string
The ID of the payment definition.
plan
description
string
required
The plan description. Maximum length is 127 single-byte alphanumeric characters.
name
string
required
The plan name.
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, or0
, payment cycles.
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.
links
array (contains the link_description object)
An array of request-related HATEOAS links.
merchant_preferences
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.
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.
plan_list
links
array (contains the link_description object)
An array of request-related HATEOAS links.
plans
array (contains the plan object)
An array of plans.
total_items
string
The total number of plans in the list.
total_pages
string
The total number of pages in the response. The
page_size
request value determines how many plans appear on each page. Thetotal_items
andpage_size
request values are used to calculate the total number of pages in the response.
terms
The currency and amount range for this term.
buyer_editable
string
required
Indicates whether the customer can edit the amount in this term.
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.
id
string
The ID of the terms.
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.