HomeProduct DocsAPI ReferenceChangelog
RecurlyAPI GuidesRecurly.jsWebhooksAPI ReferenceSupportBook demo
API Reference

Create a new subscription

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params
string
required
length ≤ 50

You must provide either a plan_code or plan_id. If both are provided the plan_id will be used.

string
length ≤ 13

You must provide either a plan_code or plan_id. If both are provided the plan_id will be used.

string

The business_entity_id is the value that represents a specific business entity for an end customer. When business_entity_id is used to assign a business entity to the subscription, all future billing events for the subscription will bill to the specified business entity. Available when the Multiple Business Entities feature is enabled. If both business_entity_id and business_entity_code are present, business_entity_id will be used.

string

The business_entity_code is the value that represents a specific business entity for an end customer. When business_entity_code is used to assign a business entity to the subscription, all future billing events for the subscription will bill to the specified business entity. Available when the Multiple Business Entities feature is enabled. If both business_entity_id and business_entity_code are present, business_entity_id will be used.

account
object
required
string
length ≤ 50

The price segment ID, e.g. e28zov4fw0v2.

string

The billing_info_id is the value that represents a specific billing info for an end customer. When billing_info_id is used to assign billing info to the subscription, all future billing events for the subscription will bill to the specified billing info. billing_info_id can ONLY be used for sites utilizing the Wallet feature.

shipping
object

Create a shipping address on the account and assign it to the subscription.

string
enum
Defaults to automatic
Allowed:
string
required
length ≤ 3

3-letter ISO 4217 currency code.

float
0 to 1000000

Override the unit amount of the subscription plan by setting this value. If not provided, the subscription will inherit the price from the subscription plan for the provided currency.

boolean
Defaults to false

Determines whether or not tax is included in the unit amount. The Tax Inclusive Pricing feature (separate from the Mixed Tax Pricing feature) must be enabled to use this flag.

integer
≥ 0
Defaults to 1

Optionally override the default quantity of 1.

add_ons
array of objects
Add-ons
coupon_codes
array of strings

A list of coupon_codes to be redeemed on the subscription or account during the purchase.

Coupon codes
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
date-time

If set, overrides the default trial behavior for the subscription. When the current date time or a past date time is provided the subscription will begin with no trial phase (overriding any plan default trial). When a future date time is provided the subscription will begin with a trial phase ending at the specified date time.

date-time

If set, the subscription will begin on this specified date. The subscription will apply the setup fee and trial period, unless the plan has no trial. Omit this field if the subscription should be started immediately.

date-time

If present, this sets the date the subscription's next billing period will start (current_period_ends_at). This can be used to align the subscription’s billing to a specific day of the month. The initial invoice will be prorated for the period between the subscription's activation date and the billing period end date. Subsequent periods will be based off the plan interval. For a subscription with a trial period, this will change when the trial expires.

integer
≥ 1

The number of cycles/billing periods in a term. When remaining_billing_cycles=0, if auto_renew=true the subscription will renew and a new term will begin, otherwise the subscription will expire.

integer

If auto_renew=true, when a term completes, total_billing_cycles takes this value as the length of subsequent terms. Defaults to the plan's total_billing_cycles.

boolean
Defaults to true

Whether the subscription renews at the end of its term.

ramp_intervals
array of objects

The new set of ramp intervals for the subscription.

Ramp Intervals
string
enum
Allowed:
string

This will default to the Terms and Conditions text specified on the Invoice Settings page in your Recurly admin. Specify custom notes to add or override Terms and Conditions. Custom notes will stay with a subscription on all renewals.

string

This will default to the Customer Notes text specified on the Invoice Settings. Specify custom notes to add or override Customer Notes. Custom notes will stay with a subscription on all renewals.

string

If there are pending credits on the account that will be invoiced during the subscription creation, these will be used as the Customer Notes on the credit invoice.

string
length ≤ 50

For manual invoicing, this identifies the PO number associated with the subscription.

integer
≥ 0
Defaults to 0

Integer paired with Net Terms Type and representing the number
of days past the current date (for net Net Terms Type) or days after
the last day of the current month (for eom Net Terms Type) that the
invoice will become past due. For manual collection method, an additional 24 hours is
added to ensure the customer has the entire last day to make payment before
becoming past due. For example:

If an invoice is due net 0, it is due 'On Receipt' and will become past due 24 hours after it's created.
If an invoice is due net 30, it will become past due at 31 days exactly.
If an invoice is due eom 30, it will become past due 31 days from the last day of the current month.

For automatic collection method, the additional 24 hours is not added. For example, On-Receipt is due immediately, and net 30 will become due exactly 30 days from invoice generation, at which point Recurly will attempt collection.
When eom Net Terms Type is passed, the value for Net Terms is restricted to 0, 15, 30, 45, 60, or 90.

For more information on how net terms work with manual collection visit our docs page (https://docs.recurly.com/docs/manual-payments#section-collection-terms)
or visit (https://docs.recurly.com/docs/automatic-invoicing-terms#section-collection-terms) for information about net terms using automatic collection.

string
enum
Defaults to net

Optionally supplied string that may be either net or eom (end-of-month).
When net, an invoice becomes past due the specified number of Net Terms days from the current date.
When eom an invoice becomes past due the specified number of Net Terms days from the last day of the current month.

Allowed:
credit_application_policy
object

Controls whether credit invoices are automatically applied to new invoices.
The mode field determines the application behavior. When mode is all,
the optional allowed_origins array can restrict which credit invoice origins
are applied.

string
length ≤ 13

If present, this subscription's subsequent transactions will use the payment gateway with this code. To select a payment gateway to use when creating a Subscription, be sure to set the account.billing_info.gateway_code as well.

string
enum

An optional type designation for the payment gateway transaction created by this request. Supports 'moto' value, which is the acronym for mail order and telephone transactions.

Allowed:
string

A gift card redemption code to be redeemed on the purchase invoice.

boolean
Defaults to false

Optional field to be used only when needing to bypass the 60 second limit on creating subscriptions. Should only be used when creating subscriptions in bulk from the API.

proration_settings
object

Allows you to control how any resulting charges will be calculated and prorated.

string
length ≤ 255

Optionally overrides the suffix component of the composed transaction descriptor. If omitted, the suffix is derived from the subscription's plan name or the invoice description, with a Trial prefix on Visa trial conversions. Subject to gateway availability and payment method support.

Responses

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