Billing Plans API

The currency and amount of the shipping fee or tax.

The charge model type, which is tax or shipping.

The ID of the charge model.

The three-character ISO-4217 currency code.

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.

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

The message that describes the error.

The human-readable, unique name of the error.

The PayPal internal ID. Used for correlation purposes.

An array of additional details for the error.

The name of the field that caused the error.

The reason for the error.

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.

The link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations.

The HTTP method required to make the related call.

The URL where the customer can cancel the agreement.

The URL where the customer can approve the agreement.

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

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.

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

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.

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

The URL where the customer is notified that the agreement was created. Read-only and reserved for future use.

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.

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

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

The JSON Pointer to the target document location at which to complete the operation.

The value to apply. The remove operation does not require a value.

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

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

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

The frequency of the payment in this definition.

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

The payment definition name.

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.

An array of shipping fees and taxes.

The ID of the payment definition.

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

The plan name.

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.

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

The ID of the plan.

An array of request-related HATEOAS links.

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.

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.

The plan status.

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

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

An array of request-related HATEOAS links.

An array of plans.

The total number of plans in the list.

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.

The currency and amount range for this term.

Indicates whether the customer can edit the amount in this term.

The currency and amount of the maximum billing amount for this term.

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

The term type.

The ID of the terms.