Billing Plans (1)

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.

Show billing plan details

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

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 -v -X GET https://api-m.sandbox.paypal.com/v1/payments/billing-plans/P-7DC96732KA7763723UOPKETA \
Response samples
application/json
{
  • "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": {},
  • "create_time": "2017-06-16T07:40:20.940Z",
  • "update_time": "2017-06-16T07:40:20.940Z",
  • "links": []
}

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

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

TypeConsidered equal if both values
stringsContain the same number of Unicode characters and their code points are byte-by-byte equal.
numbersAre numerically equal.
arraysContain 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.
objectsContain 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
application/json
[
  • {
    • "op": "replace",
    • "path": "/",
    • "value": {
      • "state": "ACTIVE"
      }
    }
]

Create billing 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. 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/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"
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.

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
application/json
{
  • "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": {}
}
Response samples
application/json
{
  • "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": {},
  • "create_time": "2017-06-16T07:40:20.940Z",
  • "update_time": "2017-06-16T07:40:20.940Z",
  • "links": []
}

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

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.

Responses
200

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

Request samples 
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 \
Response samples
application/json
{}

Errors

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.

REQUIRED_SCOPE_MISSING

Message:
Access token does not have required scope.

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

UNAUTHORIZED_ACCESS

Message:
You don't have permission to access this resource.

Description: Pass a valid plan ID.

VALIDATION_ERROR

Message:
Invalid request - see details.

Description: A validation issue occurred with your request.

Definitions

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"
required
object (Currency)

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

{
  • "id": "string",
  • "type": "TAX",
  • "amount": {
    • "currency": "string",
    • "value": "string"
    }
}

Currency

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

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

{
  • "currency": "string",
  • "value": "string"
}

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.

Array of objects (Error Details)

An array of additional details for the error.

{
  • "name": "string",
  • "debug_id": "string",
  • "message": "string",
  • "information_link": "string",
  • "details": [
    • {
      • "field": "string",
      • "issue": "string"
      }
    ]
}

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.

{
  • "field": "string",
  • "issue": "string"
}

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.

object (Currency)

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

{
  • "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"
    }
}

Patch

The JSON patch object to apply partial updates to resources.

op
required
string

The operation.

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

TypeConsidered equal if both values
stringsContain the same number of Unicode characters and their code points are byte-by-byte equal.
numbersAre numerically equal.
arraysContain 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.
objectsContain 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.

{
  • "op": "add",
  • "path": "string",
  • "value": { },
  • "from": "string"
}

Patch Request

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

Array
op
required
string

The operation.

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

TypeConsidered equal if both values
stringsContain the same number of Unicode characters and their code points are byte-by-byte equal.
numbersAre numerically equal.
arraysContain 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.
objectsContain 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.

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

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.

Array of objects (Charge Model)

An array of shipping fees and taxes.

required
object (Currency)

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

{
  • "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"
    }
}

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.

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.

Array of objects (Terms)

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

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.

Array of objects (Link Description)

An array of request-related HATEOAS links.

{
  • "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"
      }
    ]
}

Plan List

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

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.

Array of objects (Link Description)

An array of request-related HATEOAS links.

{
  • "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"
      }
    ]
}

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.

required
object (Currency)

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

required
object (Currency)

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

{
  • "id": "string",
  • "type": "MONTHLY",
  • "occurrences": "string",
  • "buyer_editable": "string",
  • "max_billing_amount": {
    • "currency": "string",
    • "value": "string"
    },
  • "amount_range": {
    • "currency": "string",
    • "value": "string"
    }
}