On this page
No Headings
A list of plans, with details for each plan and a set of HATEOAS links.
objectplansarrayAn array of plans.
itemsobjectThe billing plan details. You can base one or more agreements on an active plan.
idstringThe ID of the plan.
namerequiredstringThe plan name.
descriptionrequiredstringThe plan description. Maximum length is 127 single-byte alphanumeric characters.
typerequiredstring"FIXED", "INFINITE"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.statestring"CREATED", "ACTIVE", "INACTIVE""CREATED"The plan status.
create_timestringThe date and time when the plan was created, in Internet date and time format.
update_timestringThe date and time when the plan was updated, in Internet date and time format.
payment_definitionsarrayA 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.
itemsobjectA 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.
idstringThe ID of the payment definition.
namerequiredstringThe payment definition name.
typerequiredstring"TRIAL", "REGULAR"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.
frequency_intervalrequiredstringThe interval at which the customer is charged. Value cannot be greater than 12 months.
frequencyrequiredstring"WEEK", "DAY", "YEAR", "MONTH"The frequency of the payment in this definition.
cyclesrequiredstringThe number of payment cycles. For infinite plans with a regular payment definition, set cycles to 0.
charge_modelsarrayAn array of shipping fees and taxes.
itemsobjectThe shipping fee and tax information.
idstringThe ID of the charge model.
typerequiredstring"TAX", "SHIPPING"The charge model type, which is tax or shipping.
amountrequiredobjectThe currency and amount for a financial transaction, such as a balance or payment due.
The currency and amount of the shipping fee or tax.
valuerequiredstringThe value, which might be:
JPY that are not typically fractional.TND that are subdivided into thousandths.amountrequiredobjectThe currency and amount for a financial transaction, such as a balance or payment due.
The currency and amount of the charge to make at the end of each payment cycle for this definition.
valuerequiredstringThe value, which might be:
JPY that are not typically fractional.TND that are subdivided into thousandths.termsarrayAn array of terms for this plan. Read-only and reserved for future use.
itemsobjectThe terms for the plan.
idstringThe ID of the terms.
typerequiredstring"MONTHLY", "WEEKLY", "YEARLY"The term type.
occurrencesrequiredstringThe number of times that money can be pulled during this term.
buyer_editablerequiredstringIndicates whether the customer can edit the amount in this term.
max_billing_amountrequiredobjectThe currency and amount for a financial transaction, such as a balance or payment due.
The currency and amount of the maximum billing amount for this term.
valuerequiredstringThe value, which might be:
JPY that are not typically fractional.TND that are subdivided into thousandths.amount_rangerequiredobjectThe currency and amount for a financial transaction, such as a balance or payment due.
The currency and amount range for this term.
valuerequiredstringThe value, which might be:
JPY that are not typically fractional.TND that are subdivided into thousandths.merchant_preferencesobjectThe 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_urlrequiredstringuriThe URL where the customer can cancel the agreement.
return_urlrequiredstringuriThe URL where the customer can approve the agreement.
notify_urlstringuriThe URL where the customer is notified that the agreement was created. Read-only and reserved for future use.
max_fail_attemptsstring"0"The maximum number of allowed failed payment attempts. The default value, which is 0, defines infinite failed payment attempts.
auto_bill_amountstring"YES", "NO""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.initial_fail_amount_actionstring"CONTINUE", "CANCEL""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 thesetup_feevalue as the initial amount to trigger theinitial_fail_amount_action.
accepted_payment_typestringThe payment types that are accepted for this plan. Read-only and reserved for future use.
char_setstringThe character set for this plan. Read-only and reserved for future use.
setup_feeobjectThe currency and amount for a financial transaction, such as a balance or payment due.
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.
valuerequiredstringThe value, which might be:
JPY that are not typically fractional.TND that are subdivided into thousandths.linksarrayAn array of request-related HATEOAS links.
itemsobjectThe request-related HATEOAS link information.
hrefrequiredstringThe 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.
relrequiredstringThe link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations.
methodstring"GET", "POST", "PUT", "DELETE", "HEAD", "CONNECT", "OPTIONS", "PATCH"The HTTP method required to make the related call.
total_itemsstringThe total number of plans in the list.
total_pagesstringThe 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.
linksarrayAn array of request-related HATEOAS links.
itemsobjectThe request-related HATEOAS link information.
hrefrequiredstringThe 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.
relrequiredstringThe link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations.
methodstring"GET", "POST", "PUT", "DELETE", "HEAD", "CONNECT", "OPTIONS", "PATCH"The HTTP method required to make the related call.