Create plan

Creates a plan that defines pricing and billing cycle details for subscriptions.

Authorization

AuthorizationBearer <token>

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

Scopes

Manage plan & subscriptionhttps://uri.paypal.com/services/subscriptions

Header Parameters

Content-TypestringRequired

The media type. Required for operations with a request body. The value is `application/`, where the `format` is `json`.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

product_idstringRequired

The ID of the product created through Catalog Products API.

Match^PROD-[A-Z0-9]*$Length22 <= length <= 22

namestringRequired

The plan name.

Match^.*$Length1 <= length <= 127

statusenumOptional

The initial state of the plan. Allowed input values are CREATED and ACTIVE.

Match^[A-Z_]+$Length1 <= length <= 24

Allowed values

"CREATED"
"INACTIVE"
"ACTIVE"Default

descriptionstringOptional

The detailed description of the plan.

Match^.*$Length1 <= length <= 127

billing_cyclesobject<billing_cycle>[]Required

An array of billing cycles for trial billing and regular billing. A plan can have at most two trial cycles and only one regular cycle.

Items1 <= length <= 12

billing_cycle properties

5 properties

pricing_schemeobject<pricing_scheme>Optional

The active pricing scheme for this billing cycle. A free trial billing cycle does not require a pricing scheme.

pricing_scheme properties

3 properties

fixed_priceobject<money>Optional

The fixed amount to charge for the subscription. The changes to fixed amount are applicable to both existing and future subscriptions. For existing subscriptions, payments within 10 days of price change are not affected.

pricing_modelenumOptional

The pricing model for tiered plan. The `tiers` parameter is required.

Match^[A-Z_]+$Length1 <= length <= 24

Allowed values

"VOLUME"
"TIERED"

tiersobject<pricing_tier>[]Optional

An array of pricing tiers which are used for billing volume/tiered plans. pricing_model field has to be specified.

Items1 <= length <= 32

frequencyobject<frequency>Required

The frequency details for this billing cycle.

frequency properties

2 properties

interval_unitenumRequired

The interval at which the subscription is charged or billed.

Match^[A-Z_]+$Length1 <= length <= 24

Allowed values

"DAY"
"WEEK"
"MONTH"
"YEAR"

interval_countintegerOptional

The number of intervals after which a subscriber is billed. For example, if the `interval_unit` is `DAY` with an `interval_count` of `2`, the subscription is billed once every two days. The following table lists the maximum allowed values for the `interval_count` for each `interval_unit`:

`Interval unit`	Maximum interval count
`DAY`	365
`WEEK`	52
`MONTH`	12
`YEAR`	1

Default1Range1 <= value <= 365

tenure_typeenumRequired

The tenure type of the billing cycle. In case of a plan having trial cycle, only 2 trial cycles are allowed per plan.

Match^[A-Z_]+$Length1 <= length <= 24

Allowed values

"REGULAR"
"TRIAL"

sequenceintegerRequired

The order in which this cycle is to run among other billing cycles. For example, a trial billing cycle has a `sequence` of `1` while a regular billing cycle has a `sequence` of `2`, so that trial cycle runs before the regular cycle.

Range1 <= value <= 99

total_cyclesintegerOptional

The number of times this billing cycle gets executed. Trial billing cycles can only be executed a finite number of times (value between 1 and 999 for total_cycles). Regular billing cycles can be executed infinite times (value of 0 for total_cycles) or a finite number of times (value between 1 and 999 for total_cycles).

Default1Range0 <= value <= 999

payment_preferencesobject<payment_preferences>Required

The payment preferences for a subscription.

merchant_preferencesobject<merchant_preferences>Optional

The merchant preferences for a subscription.

taxesobject<taxes>Optional

The tax details.

quantity_supportedbooleanOptional

Indicates whether you can subscribe to this plan by providing a quantity for the goods or service.

Defaultfalse

Response Body

`application/json`

curl -X POST "https://example.com/v1/billing/plans" \  -H "Content-Type: string" \  -H "Content-Type: application/json" \  -d '{    "product_id": "stringstringstringstri",    "name": "string",    "billing_cycles": [      {        "frequency": {          "interval_unit": "DAY"        },        "tenure_type": "REGULAR",        "sequence": 1      }    ],    "payment_preferences": {}  }'

{  "id": "stringstringstringstringst",  "product_id": "stringstringstringstri",  "name": "string",  "status": "CREATED",  "description": "string",  "billing_cycles": [    {      "pricing_scheme": {        "version": 0,        "fixed_price": {          "currency_code": "str",          "value": "string"        },        "pricing_model": "VOLUME",        "tiers": [          {            "starting_quantity": "string",            "ending_quantity": "string",            "amount": {              "currency_code": "str",              "value": "string"            }          }        ],        "create_time": "stringstringstringst",        "update_time": "stringstringstringst"      },      "frequency": {        "interval_unit": "DAY",        "interval_count": 1      },      "tenure_type": "REGULAR",      "sequence": 1,      "total_cycles": 1    }  ],  "payment_preferences": {    "auto_bill_outstanding": true,    "setup_fee": {      "currency_code": "str",      "value": "string"    },    "setup_fee_failure_action": "CONTINUE",    "payment_failure_threshold": 0  },  "merchant_preferences": {    "return_url": "http://example.com",    "cancel_url": "http://example.com"  },  "taxes": {    "percentage": "string",    "inclusive": true  },  "quantity_supported": false,  "create_time": "stringstringstringst",  "update_time": "stringstringstringst",  "links": [    {      "href": "string",      "rel": "string",      "method": "GET"    }  ]}

Header Parameters

Content-TypestringRequired

The media type. Required for operations with a request body. The value is `application/`, where the `format` is `json`.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

product_idstringRequired

The ID of the product created through Catalog Products API.

Match^PROD-[A-Z0-9]*$Length22 <= length <= 22

namestringRequired

The plan name.

Match^.*$Length1 <= length <= 127

statusenumOptional

The initial state of the plan. Allowed input values are CREATED and ACTIVE.

Match^[A-Z_]+$Length1 <= length <= 24

Allowed values

"CREATED"
"INACTIVE"
"ACTIVE"Default

descriptionstringOptional

The detailed description of the plan.

Match^.*$Length1 <= length <= 127

billing_cyclesobject<billing_cycle>[]Required

An array of billing cycles for trial billing and regular billing. A plan can have at most two trial cycles and only one regular cycle.

Items1 <= length <= 12

billing_cycle properties

5 properties

pricing_schemeobject<pricing_scheme>Optional

The active pricing scheme for this billing cycle. A free trial billing cycle does not require a pricing scheme.

pricing_scheme properties

3 properties

fixed_priceobject<money>Optional

pricing_modelenumOptional

The pricing model for tiered plan. The `tiers` parameter is required.

Match^[A-Z_]+$Length1 <= length <= 24

Allowed values

"VOLUME"
"TIERED"

tiersobject<pricing_tier>[]Optional

An array of pricing tiers which are used for billing volume/tiered plans. pricing_model field has to be specified.

Items1 <= length <= 32

frequencyobject<frequency>Required

The frequency details for this billing cycle.

frequency properties

2 properties

interval_unitenumRequired

The interval at which the subscription is charged or billed.

Match^[A-Z_]+$Length1 <= length <= 24

Allowed values

"DAY"
"WEEK"
"MONTH"
"YEAR"

interval_countintegerOptional

`Interval unit`	Maximum interval count
`DAY`	365
`WEEK`	52
`MONTH`	12
`YEAR`	1

Default1Range1 <= value <= 365

tenure_typeenumRequired

The tenure type of the billing cycle. In case of a plan having trial cycle, only 2 trial cycles are allowed per plan.

Match^[A-Z_]+$Length1 <= length <= 24

Allowed values

"REGULAR"
"TRIAL"

sequenceintegerRequired

Range1 <= value <= 99

total_cyclesintegerOptional

Default1Range0 <= value <= 999

payment_preferencesobject<payment_preferences>Required

The payment preferences for a subscription.

merchant_preferencesobject<merchant_preferences>Optional

The merchant preferences for a subscription.

taxesobject<taxes>Optional

The tax details.

quantity_supportedbooleanOptional

Indicates whether you can subscribe to this plan by providing a quantity for the goods or service.

Defaultfalse

curl -X POST "https://example.com/v1/billing/plans" \ -H "Content-Type: string" \ -H "Content-Type: application/json" \ -d '{ "product_id": "stringstringstringstri", "name": "string", "billing_cycles": [ { "frequency": { "interval_unit": "DAY" }, "tenure_type": "REGULAR", "sequence": 1 } ], "payment_preferences": {} }'

{ "id": "stringstringstringstringst", "product_id": "stringstringstringstri", "name": "string", "status": "CREATED", "description": "string", "billing_cycles": [ { "pricing_scheme": { "version": 0, "fixed_price": { "currency_code": "str", "value": "string" }, "pricing_model": "VOLUME", "tiers": [ { "starting_quantity": "string", "ending_quantity": "string", "amount": { "currency_code": "str", "value": "string" } } ], "create_time": "stringstringstringst", "update_time": "stringstringstringst" }, "frequency": { "interval_unit": "DAY", "interval_count": 1 }, "tenure_type": "REGULAR", "sequence": 1, "total_cycles": 1 } ], "payment_preferences": { "auto_bill_outstanding": true, "setup_fee": { "currency_code": "str", "value": "string" }, "setup_fee_failure_action": "CONTINUE", "payment_failure_threshold": 0 }, "merchant_preferences": { "return_url": "http://example.com", "cancel_url": "http://example.com" }, "taxes": { "percentage": "string", "inclusive": true }, "quantity_supported": false, "create_time": "stringstringstringst", "update_time": "stringstringstringst", "links": [ { "href": "string", "rel": "string", "method": "GET" } ]}

billing_cycle properties

pricing_scheme properties

money properties

pricing_tier properties

money properties

frequency properties

payment_preferences properties

money properties

merchant_preferences properties

taxes properties

200application/json

201application/json

400application/json

401application/json

403application/json

422application/json

500application/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 plan

billing_cycle properties

pricing_scheme properties

money properties

pricing_tier properties

money properties

frequency properties

payment_preferences properties

money properties

merchant_preferences properties

taxes properties

200application/json

201application/json

400application/json

401application/json

403application/json

422application/json

500application/json

defaultapplication/json

On this page

On this page

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`