--- title: "Create plan" method: POST path: "/v1/billing/plans" tags: ["plans"] --- # Create plan `POST /v1/billing/plans` ## Request - Base URL: `https://api-m.sandbox.paypal.com` - URL: `https://api-m.sandbox.paypal.com/v1/billing/plans` - Auth: OAuth 2 - Client credentials - Token URL: `/api/oauth-proxy` scopes: `https://uri.paypal.com/services/subscriptions` - TypeScript: (a function with typed inputs; its response is checked against the schema) Creates a plan that defines pricing and billing cycle details for subscriptions. ## Headers - `Content-Type` string, required - `Prefer` string - `PayPal-Request-Id` string ## Request body - PlanRequestPOST: The create plan request details. - `product_id` string, required: The ID of the product created through Catalog Products API. - `name` string, required: The plan name. - `status` union: The initial state of the plan. Allowed input values are CREATED and ACTIVE. - 'CREATED': The plan was created. You cannot create subscriptions for a plan in this state. - 'INACTIVE': The plan is inactive. - 'ACTIVE': The plan is active. You can only create subscriptions for a plan in this state. - `description` string: The detailed description of the plan. - `billing_cycles` BillingCycle[], 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. - `pricing_scheme` PricingScheme: The pricing scheme details. - `version` integer: The version of the pricing scheme. - `fixed_price` Money: The currency and amount for a financial transaction, such as a balance or payment due. - `currency_code` string, required: The [three-character ISO-4217 currency code](/api/rest/reference/currency-codes/) that identifies the currency. - `value` string, required: The value, which might be:For the required number of decimal places for a currency code, see [Currency Codes](/api/rest/reference/currency-codes/). - `pricing_model` union: The pricing model for tiered plan. The `tiers` parameter is required. - 'VOLUME': A volume pricing model. - 'TIERED': A tiered pricing model. - `tiers` PricingTier[]: An array of pricing tiers which are used for billing volume/tiered plans. pricing_model field has to be specified. - `starting_quantity` string, required: The starting quantity for the tier. - `ending_quantity` string: The ending quantity for the tier. Optional for the last tier. - `amount` Money, required: The currency and amount for a financial transaction, such as a balance or payment due. - `currency_code` string, required: The [three-character ISO-4217 currency code](/api/rest/reference/currency-codes/) that identifies the currency. - `value` string, required: The value, which might be:For the required number of decimal places for a currency code, see [Currency Codes](/api/rest/reference/currency-codes/). - `create_time` string, ppaas_date_time_v3: The date and time, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). Seconds are required while fractional seconds are optional.
Note: The regular expression provides guidance but does not reject all invalid dates.
- `update_time` string, ppaas_date_time_v3: The date and time, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). Seconds are required while fractional seconds are optional.
Note: The regular expression provides guidance but does not reject all invalid dates.
- `frequency` Frequency, required: The frequency of the billing cycle. - `interval_unit` union, required: The interval at which the subscription is charged or billed. - 'DAY': A daily billing cycle. - 'WEEK': A weekly billing cycle. - 'MONTH': A monthly billing cycle. - 'YEAR': A yearly billing cycle. - `interval_count` integer: 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 unitMaximum interval count
DAY365
WEEK52
MONTH12
YEAR1
- `tenure_type` union, required: The tenure type of the billing cycle. In case of a plan having trial cycle, only 2 trial cycles are allowed per plan. - 'REGULAR': A regular billing cycle. - 'TRIAL': A trial billing cycle. - `sequence` integer, required: 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. - `total_cycles` integer: 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). - `payment_preferences` PaymentPreferences, required: The payment preferences for a subscription. - `auto_bill_outstanding` boolean: Indicates whether to automatically bill the outstanding amount in the next billing cycle. - `setup_fee` Money: The currency and amount for a financial transaction, such as a balance or payment due. - `currency_code` string, required: The [three-character ISO-4217 currency code](/api/rest/reference/currency-codes/) that identifies the currency. - `value` string, required: The value, which might be:For the required number of decimal places for a currency code, see [Currency Codes](/api/rest/reference/currency-codes/). - `setup_fee_failure_action` union: The action to take on the subscription if the initial payment for the setup fails. - 'CONTINUE': Continues the subscription if the initial payment for the setup fails. - 'CANCEL': Cancels the subscription if the initial payment for the setup fails. - `payment_failure_threshold` integer: The maximum number of payment failures before a subscription is suspended. For example, if `payment_failure_threshold` is `2`, the subscription automatically updates to the `SUSPEND` state if two consecutive payments fail. - `merchant_preferences` MerchantPreferences: The merchant preferences for a subscription. - `return_url` string, uri: The URL where the customer is redirected after the customer approves the payment. - `cancel_url` string, uri: The URL where the customer is redirected after the customer cancels the payment. - `taxes` Taxes: The tax details. - `percentage` string, ppaas_common_percentage_v2, required: The percentage, as a fixed-point, signed decimal number. For example, define a 19.99% interest rate as `19.99`. - `inclusive` boolean: Indicates whether the tax was already included in the billing amount. - `quantity_supported` boolean: Indicates whether you can subscribe to this plan by providing a quantity for the goods or service. ## Response `200` A successful request returns the HTTP `200 OK` status code and a JSON response body that shows billing plan details. - Plan: The plan details. - `id` string: The unique PayPal-generated ID for the plan. - `product_id` string: The ID for the product. - `name` string: The plan name. - `status` union: The plan status. - 'CREATED': The plan was created. You cannot create subscriptions for a plan in this state. - 'INACTIVE': The plan is inactive. - 'ACTIVE': The plan is active. You can only create subscriptions for a plan in this state. - `description` string: The detailed description of the plan. - `billing_cycles` BillingCycle[]: 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. - `pricing_scheme` PricingScheme: The pricing scheme details. - `version` integer: The version of the pricing scheme. - `fixed_price` Money: The currency and amount for a financial transaction, such as a balance or payment due. - `currency_code` string, required: The [three-character ISO-4217 currency code](/api/rest/reference/currency-codes/) that identifies the currency. - `value` string, required: The value, which might be:For the required number of decimal places for a currency code, see [Currency Codes](/api/rest/reference/currency-codes/). - `pricing_model` union: The pricing model for tiered plan. The `tiers` parameter is required. - 'VOLUME': A volume pricing model. - 'TIERED': A tiered pricing model. - `tiers` PricingTier[]: An array of pricing tiers which are used for billing volume/tiered plans. pricing_model field has to be specified. - `starting_quantity` string, required: The starting quantity for the tier. - `ending_quantity` string: The ending quantity for the tier. Optional for the last tier. - `amount` Money, required: The currency and amount for a financial transaction, such as a balance or payment due. - `currency_code` string, required: The [three-character ISO-4217 currency code](/api/rest/reference/currency-codes/) that identifies the currency. - `value` string, required: The value, which might be:For the required number of decimal places for a currency code, see [Currency Codes](/api/rest/reference/currency-codes/). - `create_time` string, ppaas_date_time_v3: The date and time, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). Seconds are required while fractional seconds are optional.
Note: The regular expression provides guidance but does not reject all invalid dates.
- `update_time` string, ppaas_date_time_v3: The date and time, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). Seconds are required while fractional seconds are optional.
Note: The regular expression provides guidance but does not reject all invalid dates.
- `frequency` Frequency, required: The frequency of the billing cycle. - `interval_unit` union, required: The interval at which the subscription is charged or billed. - 'DAY': A daily billing cycle. - 'WEEK': A weekly billing cycle. - 'MONTH': A monthly billing cycle. - 'YEAR': A yearly billing cycle. - `interval_count` integer: 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 unitMaximum interval count
DAY365
WEEK52
MONTH12
YEAR1
- `tenure_type` union, required: The tenure type of the billing cycle. In case of a plan having trial cycle, only 2 trial cycles are allowed per plan. - 'REGULAR': A regular billing cycle. - 'TRIAL': A trial billing cycle. - `sequence` integer, required: 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. - `total_cycles` integer: 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). - `payment_preferences` PaymentPreferences: The payment preferences for a subscription. - `auto_bill_outstanding` boolean: Indicates whether to automatically bill the outstanding amount in the next billing cycle. - `setup_fee` Money: The currency and amount for a financial transaction, such as a balance or payment due. - `currency_code` string, required: The [three-character ISO-4217 currency code](/api/rest/reference/currency-codes/) that identifies the currency. - `value` string, required: The value, which might be:For the required number of decimal places for a currency code, see [Currency Codes](/api/rest/reference/currency-codes/). - `setup_fee_failure_action` union: The action to take on the subscription if the initial payment for the setup fails. - 'CONTINUE': Continues the subscription if the initial payment for the setup fails. - 'CANCEL': Cancels the subscription if the initial payment for the setup fails. - `payment_failure_threshold` integer: The maximum number of payment failures before a subscription is suspended. For example, if `payment_failure_threshold` is `2`, the subscription automatically updates to the `SUSPEND` state if two consecutive payments fail. - `merchant_preferences` MerchantPreferences: The merchant preferences for a subscription. - `return_url` string, uri: The URL where the customer is redirected after the customer approves the payment. - `cancel_url` string, uri: The URL where the customer is redirected after the customer cancels the payment. - `taxes` Taxes: The tax details. - `percentage` string, ppaas_common_percentage_v2, required: The percentage, as a fixed-point, signed decimal number. For example, define a 19.99% interest rate as `19.99`. - `inclusive` boolean: Indicates whether the tax was already included in the billing amount. - `quantity_supported` boolean: Indicates whether you can subscribe to this plan by providing a quantity for the goods or service. - `create_time` string, ppaas_date_time_v3: The date and time, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). Seconds are required while fractional seconds are optional.
Note: The regular expression provides guidance but does not reject all invalid dates.
- `update_time` string, ppaas_date_time_v3: The date and time, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). Seconds are required while fractional seconds are optional.
Note: The regular expression provides guidance but does not reject all invalid dates.
- `links` LinkDescription[]: An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links). - `href` string, required: The complete target URL. To make the related call, combine the method with this [URI Template-formatted](https://tools.ietf.org/html/rfc6570) link. For pre-processing, include the `$`, `(`, and `)` characters. The `href` is the key HATEOAS component that links a completed call with a subsequent call. - `rel` string, required: The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which serves as an ID for a link that unambiguously describes the semantics of the link. See [Link Relations](https://www.iana.org/assignments/link-relations/link-relations.xhtml). - `method` 'GET' | 'POST' | 'PUT' | 'DELETE' | 'HEAD' | 'CONNECT' | 'OPTIONS' | 'PATCH': The HTTP method required to make the related call. ## Other responses - `201`: A successful request returns the HTTP `201 Created` status code and a JSON response body that shows billing plan details. - `400`: Bad Request. Request is not well-formed, syntactically incorrect, or violates schema. - `401`: Authentication failed due to missing authorization header, or invalid authentication credentials. - `403`: Authorization failed due to insufficient permissions. - `422`: The requested action could not be performed, semantically incorrect, or failed business validation. - `500`: An internal server error has occurred. - `default`: The default response. --- [API](https://skmtc.dev/paypal/apis/subscriptions.md) - [All operations](https://skmtc.dev/paypal/apis/subscriptions/llms.txt) - [OpenAPI document](https://skmtc.dev/paypal/apis/subscriptions/revisions/f8535d303786?raw)