Billing Plans(1)

?This API is currently not supported by our SDK

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.

operation/billing-plans.get Show billing plan details

get/v1/payments/billing-plans/{plan_id}

Try it

Shows details for a billing plan, by ID.

SecurityOauth2

Request

path Parameters


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

Responses

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

Request samples

cURL

Copy

curl -v -X GET https://api-m.sandbox.paypal.com/v1/payments/billing-plans/P-7DC96732KA7763723UOPKETA \
-H 'Authorization: Bearer access_token6V7rbVwmlM1gFZKW_8QtzWXqpcwQ6T5vhEGYNJDAAdn3paCgRpdeMdVYmWzgbKSsECednupJ3Zx5Xd-g'

Response samples

application/json

Sample 1 - 200 - Show Billing Plan DetailsSample 1 - 200 - Show Billing Plan Details

Copy

Expand allCollapse all

`{"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"

}

]

operation/billing-plans.patch Update billing plan

patch/v1/payments/billing-plans/{plan_id}

Try it

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.

SecurityOauth2

Request

path Parameters


plan_id required	string The ID of the billing plan to update.

Request Body schema: application/json

Array

| op
required | string

The operation.

Enum Value	Description
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:

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`, 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. | | | path | string
The JSON Pointer to the target document location at which to complete the operation. | | value | object (Patch Value)
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. |

Responses

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

Request samples

Payload
cURL

application/json

Sample 1 - 200 - Update Plan to Activate ItSample 1 - 200 - Update Plan to Activate It

Copy

Expand allCollapse all

[{"op": "replace",\ \ "path": "/",\ \ "value": {"state": "ACTIVE"\ \ }\ \ }\ \ ]

Response samples

application/json

Sample 1 - 200 - Update Plan to Activate ItSample 1 - 200 - Update Plan to Activate It

Copy

{ }

operation/billing-plans.post Create billing plan

post/v1/payments/billing-plans

Try it

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.

SecurityOauth2

Request

Request Body schema: application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json


name required	string<= 128 characters The plan name.
description required	string<= 127 characters The plan description. Maximum length is 127 single-byte alphanumeric characters.
type required	string<= 20 characters 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. Enum:"FIXED""INFINITE"
payment_definitions	Array of objects (Payment Definition) 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 (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.

Responses

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

Request samples

Payload
cURL

application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json

Sample 1 - 201 - Create Plan with Regular Payment Definition, Minimal Merchant Preferences, and No Shipping Fees or TaxSample 1 - 201 - Create Plan with Regular Payment Definition, Minimal Merchant Preferences, and No Shipping Fees or Tax

Copy

Expand allCollapse all

`{"name": "Simple Plan",

"description": "Plan with one regular payment definition, minimal merchant preferences, and no shipping fees or tax.",

"type": "FIXED",

"payment_definitions": [{"name": "Regular payment definition",

"type": "REGULAR",

"frequency": "MONTH",

"frequency_interval": "2",

"amount": {"value": "100",

"currency": "USD"

},

"cycles": "12"

}

],

"merchant_preferences": {"return_url": "https://example.com",

"cancel_url": "https://example.com/cancel"

}

Response samples

application/json

Copy

Expand allCollapse all

`{"id": "P-1TV69435N82273154UPWDU4I",

"state": "CREATED",

"name": "Simple Plan",

"description": "Plan with one regular payment definition, minimal merchant preferences, and no shipping fees or tax.",

"type": "FIXED",

"payment_definitions": [{"id": "PD-62U12008P21526502UPWDU4I",

"name": "Regular payment definition",

"type": "REGULAR",

"frequency": "MONTH",

"amount": {"currency": "USD",

"value": "100"

},

"charge_models": [ ],

"cycles": "12",

"frequency_interval": "2"

}

],

"merchant_preferences": {"setup_fee": {"currency": "USD",

"value": "0"

"max_fail_attempts": "0",

"return_url": "https://example.com",

"cancel_url": "https://example.com/cancel",

"auto_bill_amount": "NO",

"initial_fail_amount_action": "CONTINUE"

"create_time": "2017-06-16T09:05:06.161Z",

"update_time": "2017-06-16T09:05:06.161Z",

"links": [{"href": "https://api-m.sandbox.paypal.com/v1/payments/billing-plans/P-1TV69435N82273154UPWDU4I",

"rel": "self",

"method": "GET"

}

]

operation/billing-plans.list List billing plans

get/v1/payments/billing-plans

Try it

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

SecurityOauth2

Request

query Parameters


page	string Default:"0" The zero-indexed number of the first page that begins the set of pages that are returned in the response.
status	string Default:"CREATED" Filters the plans in the response by a plan status. Enum:"CREATED""ACTIVE""INACTIVE""ALL"
page_size	string Default:"10" 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.
total_required	string Default:"no" Indicates whether the response includes the `total_items` and `total_pages` fields. Value is `yes` or `no`.

Request Body schema: application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json

any

Responses

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

Request samples

Payload
cURL

application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json

Copy

{ }

Response samples

application/json

Sample 1 - 200 - List Billing PlansSample 1 - 200 - List Billing Plans

Copy

Expand allCollapse all

`{"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"

}

]

tag/Errors Errors

section/INTERNAL_SERVICE_ERROR INTERNAL_SERVICE_ERROR

Message:

An internal service error has occurred.

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

section/REQUIRED_SCOPE_MISSING REQUIRED_SCOPE_MISSING

Message:

Access token does not have required scope.

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

section/UNAUTHORIZED_ACCESS UNAUTHORIZED_ACCESS

Message:

You don't have permission to access this resource.

Description: Pass a valid plan ID.

section/VALIDATION_ERROR VALIDATION_ERROR

Message:

Invalid request - see details.

Description: A validation issue occurred with your request.

tag/Definitions Definitions

schema/charge_models Charge Model

The shipping fee and tax information.


id	string<= 128 characters The ID of the charge model.
type required	string<= 20 characters The charge model type, which is tax or shipping. Enum:"TAX""SHIPPING"
amount required	object (Currency) The currency and amount for a financial transaction, such as a balance or payment due.

Copy

Expand allCollapse all

`{"id": "string",

"type": "TAX",

"amount": {"currency": "string",

"value": "string"

}

schema/currency Currency

The currency and amount for a financial transaction, such as a balance or payment due.


currency required	string The three-character ISO-4217 currency code.
value required	string 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.

Copy

`{"currency": "string",

"value": "string"

schema/error Error

The error information.


name required	string The human-readable, unique name of the error.
debug_id	string The PayPal internal ID. Used for correlation purposes.
message required	string The message that describes the error.
information_link required	string The URI to detailed information related to this error for the developer.
details	Array of objects (Error Details) An array of additional details for the error.

Copy

Expand allCollapse all

`{"name": "string",

"debug_id": "string",

"message": "string",

"information_link": "string",

"details": [{"field": "string",

"issue": "string"

}

]

schema/error_details Error Details

The error details. Required for client-side 4XX errors.


field required	string The name of the field that caused the error.
issue required	string The reason for the error.

Copy

`{"field": "string",

"issue": "string"

schema/link_description Link Description

The request-related HATEOAS link information.


href required	string 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. The `href` is the key HATEOAS component that links a completed call with a subsequent call.
rel required	string The link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations.
method	string The HTTP method required to make the related call. Enum:"GET""POST""PUT""DELETE""HEAD""CONNECT""OPTIONS""PATCH"

Copy

`{"href": "string",

"rel": "string",

"method": "GET"

schema/merchant_preferences 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.


cancel_url required	string<uri><= 1000 characters The URL where the customer can cancel the agreement.
return_url required	string<uri><= 1000 characters The URL where the customer can approve the agreement.
notify_url	string<uri><= 1000 characters The URL where the customer is notified that the agreement was created. Read-only and reserved for future use.
max_fail_attempts	string Default:"0" The maximum number of allowed failed payment attempts. The default value, which is `0`, defines infinite failed payment attempts.
auto_bill_amount	string Default:"NO" 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. Enum:"YES""NO"
initial_fail_amount_action	string Default:"CONTINUE" 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`. Enum:"CONTINUE""CANCEL"
accepted_payment_type	string The payment types that are accepted for this plan. Read-only and reserved for future use.
char_set	string The character set for this plan. Read-only and reserved for future use.
setup_fee	object (Currency) The currency and amount for a financial transaction, such as a balance or payment due.

Copy

Expand allCollapse all

`{"cancel_url": "http://example.com",

"return_url": "http://example.com",

"notify_url": "http://example.com",

"max_fail_attempts": "0",

"auto_bill_amount": "YES",

"initial_fail_amount_action": "CONTINUE",

"accepted_payment_type": "string",

"char_set": "string",

"setup_fee": {"currency": "string",

"value": "string"

}

schema/patch Patch

The JSON patch object to apply partial updates to resources.

| op
required | string

The operation.

Enum Value	Description
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:

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`, 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.

Copy

Expand allCollapse all

`{"op": "add",

"path": "string",

"value": { },

"from": "string"

schema/patch_request Patch Request

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

Array

| op
required | string

The operation.

Enum Value	Description
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:

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`, 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.

Copy

Expand allCollapse all

[{"op": "add",\ \ "path": "string",\ \ "value": { },\ \ "from": "string"\ \ }\ \ ]

schema/payment_definition Payment Definition

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.


id	string<= 128 characters The ID of the payment definition.
name required	string<= 128 characters The payment definition name.
type required	string 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. Enum:"TRIAL""REGULAR"
frequency_interval required	string The interval at which the customer is charged. Value cannot be greater than 12 months.
frequency required	string The frequency of the payment in this definition. Enum:"WEEK""DAY""YEAR""MONTH"
cycles required	string The number of payment cycles. For infinite plans with a regular payment definition, set `cycles` to `0`.
charge_models	Array of objects (Charge Model) An array of shipping fees and taxes.
amount required	object (Currency) The currency and amount for a financial transaction, such as a balance or payment due.

Copy

Expand allCollapse all

`{"id": "string",

"name": "string",

"type": "TRIAL",

"frequency_interval": "string",

"frequency": "WEEK",

"cycles": "string",

"charge_models": [{"id": "string",

"type": "TAX",

"amount": {"currency": "string",

"value": "string"

}

}

],

"amount": {"currency": "string",

"value": "string"

}

schema/plan Plan

The billing plan details. You can base one or more agreements on an active plan.


id	string<= 128 characters The ID of the plan.
name required	string<= 128 characters The plan name.
description required	string<= 127 characters The plan description. Maximum length is 127 single-byte alphanumeric characters.
type required	string<= 20 characters 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. Enum:"FIXED""INFINITE"
state	string Default:"CREATED" The plan status. Enum:"CREATED""ACTIVE""INACTIVE"
create_time	string The date and time when the plan was created, in Internet date and time format.
update_time	string The date and time when the plan was updated, in Internet date and time format.
payment_definitions	Array of objects (Payment Definition) 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 of objects (Terms) An array of terms for this plan. Read-only and reserved for future use.
merchant_preferences	object (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.
links	Array of objects (Link Description) An array of request-related HATEOAS links.

Copy

Expand allCollapse all

`{"id": "string",

"name": "string",

"description": "string",

"type": "FIXED",

"state": "CREATED",

"create_time": "string",

"update_time": "string",

"payment_definitions": [{"id": "string",

"name": "string",

"type": "TRIAL",

"frequency_interval": "string",

"frequency": "WEEK",

"cycles": "string",

"charge_models": [{"id": "string",

"type": "TAX",

"amount": {"currency": "string",

"value": "string"

}

}

],

"amount": {"currency": "string",

"value": "string"

}

}

],

"terms": [{"id": "string",

"type": "MONTHLY",

"occurrences": "string",

"buyer_editable": "string",

"max_billing_amount": {"currency": "string",

"value": "string"

},

"amount_range": {"currency": "string",

"value": "string"

}

}

],

"merchant_preferences": {"cancel_url": "http://example.com",

"return_url": "http://example.com",

"notify_url": "http://example.com",

"max_fail_attempts": "0",

"auto_bill_amount": "YES",

"initial_fail_amount_action": "CONTINUE",

"accepted_payment_type": "string",

"char_set": "string",

"setup_fee": {"currency": "string",

"value": "string"

}

"links": [{"href": "string",

"rel": "string",

"method": "GET"

}

]

schema/plan_list Plan List

A list of plans, with details for each plan and a set of HATEOAS links.


plans	Array of objects (Plan) 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. The `total_items` and `page_size` request values are used to calculate the total number of pages in the response.
links	Array of objects (Link Description) An array of request-related HATEOAS links.

Copy

Expand allCollapse all

`{"plans": [{"id": "string",

"name": "string",

"description": "string",

"type": "FIXED",

"state": "CREATED",

"create_time": "string",

"update_time": "string",

"payment_definitions": [{"id": "string",

"name": "string",

"type": "TRIAL",

"frequency_interval": "string",

"frequency": "WEEK",

"cycles": "string",

"charge_models": [{"id": "string",

"type": "TAX",

"amount": {"currency": null,

"value": null

}

}

],

"amount": {"currency": "string",

"value": "string"

}

}

],

"terms": [{"id": "string",

"type": "MONTHLY",

"occurrences": "string",

"buyer_editable": "string",

"max_billing_amount": {"currency": "string",

"value": "string"

},

"amount_range": {"currency": "string",

"value": "string"

}

}

],

"merchant_preferences": {"cancel_url": "http://example.com",

"return_url": "http://example.com",

"notify_url": "http://example.com",

"max_fail_attempts": "0",

"auto_bill_amount": "YES",

"initial_fail_amount_action": "CONTINUE",

"accepted_payment_type": "string",

"char_set": "string",

"setup_fee": {"currency": "string",

"value": "string"

}

},

"links": [{"href": "string",

"rel": "string",

"method": "GET"

}

]

}

],

"total_items": "string",

"total_pages": "string",

"links": [{"href": "string",

"rel": "string",

"method": "GET"

}

]

schema/terms Terms

The terms for the plan.


id	string<= 128 characters The ID of the terms.
type required	string The term type. Enum:"MONTHLY""WEEKLY""YEARLY"
occurrences required	string The number of times that money can be pulled during this term.
buyer_editable required	string Indicates whether the customer can edit the amount in this term.
max_billing_amount required	object (Currency) The currency and amount for a financial transaction, such as a balance or payment due.
amount_range required	object (Currency) The currency and amount for a financial transaction, such as a balance or payment due.

Copy

Expand allCollapse all

`{"id": "string",

"type": "MONTHLY",

"occurrences": "string",

"buyer_editable": "string",

"max_billing_amount": {"currency": "string",

"value": "string"

"amount_range": {"currency": "string",

"value": "string"

}

Billing Plans(1) ​

operation/billing-plans.get Show billing plan details ​

path Parameters ​

operation/billing-plans.patch Update billing plan ​

path Parameters ​

Request Body schema: application/json ​

operation/billing-plans.post Create billing plan ​

Request Body schema: application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json ​

operation/billing-plans.list List billing plans ​

query Parameters ​

Request Body schema: application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json ​

tag/Errors Errors ​

section/INTERNAL_SERVICE_ERROR INTERNAL_SERVICE_ERROR ​

section/REQUIRED_SCOPE_MISSING REQUIRED_SCOPE_MISSING ​

section/UNAUTHORIZED_ACCESS UNAUTHORIZED_ACCESS ​

section/VALIDATION_ERROR VALIDATION_ERROR ​

tag/Definitions Definitions ​

schema/charge_models Charge Model ​

schema/currency Currency ​

schema/error Error ​

schema/error_details Error Details ​

schema/link_description Link Description ​

schema/merchant_preferences Merchant Preferences ​

schema/patch Patch ​

schema/patch_request Patch Request ​

schema/payment_definition Payment Definition ​

schema/plan Plan ​

schema/plan_list Plan List ​

schema/terms Terms ​

Billing Plans(1)

operation/billing-plans.get Show billing plan details

path Parameters

operation/billing-plans.patch Update billing plan

path Parameters

Request Body schema: application/json

operation/billing-plans.post Create billing plan

Request Body schema: application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json

operation/billing-plans.list List billing plans

query Parameters

Request Body schema: application/jsonmultipart/relatedmultipart/form-datamultipart/mixedapplication/json

tag/Errors Errors

section/INTERNAL_SERVICE_ERROR INTERNAL_SERVICE_ERROR

section/REQUIRED_SCOPE_MISSING REQUIRED_SCOPE_MISSING

section/UNAUTHORIZED_ACCESS UNAUTHORIZED_ACCESS

section/VALIDATION_ERROR VALIDATION_ERROR

tag/Definitions Definitions

schema/charge_models Charge Model

schema/currency Currency

schema/error Error

schema/error_details Error Details

schema/link_description Link Description

schema/merchant_preferences Merchant Preferences

schema/patch Patch

schema/patch_request Patch Request

schema/payment_definition Payment Definition

schema/plan Plan

schema/plan_list Plan List

schema/terms Terms