HomeProduct DocsAPI ReferenceChangelog
RecurlyAPI GuidesRecurly.jsWebhooksAPI ReferenceSupportBook demo
API Reference
RecurlyAPI GuidesRecurly.jsWebhooksAPI ReferenceSupportBook demo

Create a plan

post
https://v3.recurly.com/plans
Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params
string
required
length ≤ 50
/^[a-z0-9_+-]+$/

Unique code to identify the plan. This is used in Hosted Payment Page URLs and in the invoice exports.

string
required
length ≤ 255

This name describes your plan and will appear on the Hosted Payment Page and the subscriber's invoice.

string
enum
Defaults to fixed

A fixed pricing model has the same price for each billing period.
A ramp pricing model defines a set of Ramp Intervals, where a subscription changes price on
a specified cadence of billing periods. The price change could be an increase or decrease.

Allowed:
currencies
array of objects
required
length ≥ 1

Required only when pricing_model is 'fixed'.

Pricing*
string
length ≤ 3

3-letter ISO 4217 currency code.

float
0 to 1000000
deprecated

This field is deprecated, please use top level setup_fees instead. Amount of one-time setup fee automatically charged at the beginning of a subscription billing cycle. For subscription plans with a trial, the setup fee will be charged at the time of signup. Setup fees do not increase with the quantity of a subscription plan.

float
0 to 1000000

This field should not be sent when the pricing model is 'ramp'.

string
length ≤ 55
/^[a-z0-9_+-]+$/

The price segment ID or code. For ID no prefix is used e.g. e28zov4fw0v2. For requests, the code can also be used. Use prefix code-, e.g. code-gold.

boolean
Defaults to false
deprecated

This field is deprecated. Please do not use it.

ramp_intervals
array of objects
Ramp Intervals
setup_fees
array of objects
Setup Fees
add_ons
array of objects
Add Ons
string
enum
Defaults to months

Unit for the plan's billing interval.

Allowed:
integer
≥ 1
Defaults to 1

Length of the plan's billing interval in interval_unit.

string

Optional description, not displayed.

string
length ≤ 20
/^[a-z0-9_+-]+$/

Accounting code for invoice line items for the plan. If no value is provided, it defaults to plan's code.

string
enum
Allowed:
string
length ≤ 13

The ID of a general ledger account. General ledger accounts are
only accessible as a part of the Recurly RevRec Standard and
Recurly RevRec Advanced features.

string
length ≤ 13

The ID of a general ledger account. General ledger accounts are
only accessible as a part of the Recurly RevRec Standard and
Recurly RevRec Advanced features.

string
length ≤ 13

The ID of a performance obligation. Performance obligations are
only accessible as a part of the Recurly RevRec Standard and
Recurly RevRec Advanced features.

string
length ≤ 20
/^[a-z0-9_+-]+$/

Accounting code for invoice line items for the plan's setup fee. If no value is provided, it defaults to plan's accounting code.

string
enum
Allowed:
string
length ≤ 13

The ID of a general ledger account. General ledger accounts are
only accessible as a part of the Recurly RevRec Standard and
Recurly RevRec Advanced features.

string
length ≤ 13

The ID of a general ledger account. General ledger accounts are
only accessible as a part of the Recurly RevRec Standard and
Recurly RevRec Advanced features.

string
length ≤ 13

The ID of a performance obligation. Performance obligations are
only accessible as a part of the Recurly RevRec Standard and
Recurly RevRec Advanced features.

string
enum
Defaults to months

Units for the plan's trial period.

Allowed:
integer
≥ 0
Defaults to 0

Length of plan's trial period in trial_units. 0 means no trial.

boolean
Defaults to true

Allow free trial subscriptions to be created without billing info. Should not be used if billing info is needed for initial invoice due to existing uninvoiced charges or setup fee.

integer
≥ 0

Automatically terminate subscriptions after a defined number of billing cycles. Number of billing cycles before the plan automatically stops renewing, defaults to null for continuous, automatic renewal.

boolean
Defaults to true

Subscriptions will automatically inherit this value once they are active. If auto_renew is true, then a subscription will automatically renew its term at renewal. If auto_renew is false, then a subscription will expire at the end of its term. auto_renew can be overridden on the subscription record itself.

custom_fields
array of objects

The custom fields will only be altered when they are included in a request. Sending an empty array will not remove any existing values. To remove a field send the name with a null or empty value.

Custom fields
integer
≥ 0

Used by Avalara for Communications taxes. The transaction type in combination with the service type describe how the plan is taxed. Refer to the documentation for more available t/s types.

integer
≥ 0

Used by Avalara for Communications taxes. The transaction type in combination with the service type describe how the plan is taxed. Refer to the documentation for more available t/s types.

string
length ≤ 50

Optional field used by Avalara, Vertex, and Recurly's In-the-Box tax solution to determine taxation rules. You can pass in specific tax codes using any of these tax integrations. For Recurly's In-the-Box tax offering you can also choose to instead use simple values of unknown, physical, or digital tax codes.

string
length ≤ 25
^\d+(\.\d+)*$

The Harmonized System (HS) code is an internationally standardized system of names and numbers to classify traded products. The HS code, sometimes called Commodity Code, is used by customs authorities around the world to identify products when assessing duties and taxes. The HS code may also be referred to as the tariff code or customs code. Values should contain only digits and decimals.

boolean

true exempts tax on the plan, false applies tax on the plan.

string

Used by Vertex for tax calculations. Possible values are sale, rental, lease.

hosted_pages
object
boolean

Used to determine whether items can be assigned as add-ons to individual subscriptions.
If true, items can be assigned as add-ons to individual subscription add-ons.
If false, only plan add-ons can be used.

string

Unique ID to identify a dunning campaign. Used to specify if a non-default dunning campaign should be assigned to this plan. For sites without multiple dunning campaigns enabled, the default dunning campaign will always be used.

Responses

Updated 3 months ago

Did this page help you?
Language
Credentials
Basic
base64
:
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated 3 months ago

Did this page help you?