Create billing plan

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

Authorization

AuthorizationBearer <token>

FlowClient CredentialsToken URLhttps://api-m.sandbox.paypal.com/v1/oauth2/tokenInheader

Scopes

Create and manage a planhttps://uri.paypal.com/services/subscriptions

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

namestringRequired

The plan name.

Length0 <= length <= 128

descriptionstringRequired

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

Length0 <= length <= 127

typeenumRequired

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.

Length0 <= length <= 20Value in"FIXED" | "INFINITE"

payment_definitionsobject<payment_definition>[]Optional

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.

payment_definition properties

7 properties

namestringRequired

The payment definition name.

Length0 <= length <= 128

typeenumRequired

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.

Value in"TRIAL" | "REGULAR"

frequency_intervalstringRequired

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

frequencyenumRequired

The frequency of the payment in this definition.

Value in"WEEK" | "DAY" | "YEAR" | "MONTH"

cyclesstringRequired

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

charge_modelsobject<charge_models>[]Optional

An array of shipping fees and taxes.

amountobject<currency>Required

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

merchant_preferencesobject<merchant_preferences>Optional

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.

merchant_preferences properties

6 properties

cancel_urlstringRequired

The URL where the customer can cancel the agreement.

FormaturiLength0 <= length <= 1000

return_urlstringRequired

The URL where the customer can approve the agreement.

FormaturiLength0 <= length <= 1000

max_fail_attemptsstringOptional

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

Default"0"

auto_bill_amountenumOptional

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.

Default"NO"Value in"YES" | "NO"

initial_fail_amount_actionenumOptional

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

Default"CONTINUE"Value in"CONTINUE" | "CANCEL"

setup_feeobject<currency>Optional

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

Response Body

`application/json`

curl -X POST "https://example.com/billing-plans" \  -H "Content-Type: application/json" \  -d '{    "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"    }  }'

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

curl -X POST "https://example.com/billing-plans" \ -H "Content-Type: application/json" \ -d '{ "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" } }'

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

Authorization

Request Body

payment_definition properties

charge_models properties

currency properties

currency properties

merchant_preferences properties

currency properties

Response Body

`application/json`

`application/json`

On this page

On this page

On this page

Create billing plan

Authorization

Request Body

payment_definition properties

charge_models properties

currency properties

currency properties

merchant_preferences properties

currency properties

Response Body

`application/json`

`application/json`

On this page

On this page

Create billing plan

Authorization

Request Body

payment_definition properties

charge_models properties

currency properties

currency properties

merchant_preferences properties

currency properties

Response Body

201application/json

defaultapplication/json

On this page

On this page

On this page

If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more

Create billing plan

Authorization

Request Body

payment_definition properties

charge_models properties

currency properties

currency properties

merchant_preferences properties

currency properties

Response Body

201application/json

defaultapplication/json

On this page

On this page

`application/json`

`application/json`

`application/json`

`application/json`