Create Subscription

post

https://{subdomain}.{domain}/v2/subscriptions

Consider using Purchases

If you need to purchase multiple subscriptions at once or purchase a subscription along with additional charges or credits we recommend using the Create Purchase endpoint instead of this one. With it you can create an account, billing info, charges, credits and subscriptions, then invoice and collect payment in one step.

SUBSCRIPTION STARTS DATE

If you would like the subscription to start on a specified date, please set the trial_ends_at parameter in your API request. Recurly will ignore any trial period currently specified on the plan and begin charging the subscription on the date specified. This is useful for creating your own, custom trial intervals and for importing existing subscriptions from an external system.

CREATING AN ACCOUNT SIMULTANEOUSLY

To avoid paying multiple transaction fees, Recurly allows you to create a subscription, account and billing information in one API call. That way the billing information can be validated when charging for the subscription.

USING STORED BILLING INFO

You may create a subscription without specifying billing information if an account already has stored billing information.

REDEEMING A COUPON

Redeem coupon codes within the create subscription action as a convenience or as a way to make sure the coupon is only redeemed if the subscription transaction is successful.

If you are redeeming one coupon, pass in coupon_code:

<coupon_code>special1</coupon_code>

If you want to redeem multiple coupons, use the following format:

<coupon_codes>
  <coupon_code>special1</coupon_code>
  <coupon_code>special2</coupon_code>
</coupon_codes>

NOTE: You must have Multiple Coupons Per Account enabled in Coupon Settings in order to redeem multiple coupons in the create subscription action.

The coupon must have eligible charges that include the plan of the subscription you are creating. If the coupon has a redemption_resource of "subscription", it will automatically be tied to the subscription upon successful redemption.

If you are redeeming a free trial coupon and also setting a trial_ends_at in the request, the subscriptions trial will follow the trial_ends_at, not the coupon rules.

REDEEMING A GIFT CARD

Redeem a gift card redemption code within the create subscription action as a convenience or as a way to make sure the gift card is only redeemed if the subscription transaction is successful. Only one gift card redemption code can be redeemed in the request

Example XML Request:

<gift_card>
    <redemption_code>JHD776JENN99E6DD</redemption_code>
</gift_card>

Note that the subscription response will not include information about the gift card, but will add two new parameters, started_with_gift and converted_at.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

plan_code

string

required

length ≤ 50

Unique code to identify the plan. This code may only contain the following characters: [a-z 0-9 @ - _ .]. Max of 50 characters.

currency

string

required

length ≤ 3

3-letter ISO 4217 currency code.

account

object

required

quantity

integer

≥ 0

Defaults to 1

Optionally override the default quantity of 1.

unit_amount_in_cents

integer

0 to 10000000

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

total_billing_cycles

integer

≥ 0

The total number of billing cycles for the current subscription term.

renewal_billing_cycles

integer

≥ 0

The number of billing periods in the subscription's next term. Will default to the plan's total_billing_cycles unless specified.

revenue_schedule_type

string

enum

Optional field for setting a revenue schedule type. This will determine how revenue for the associated Subscription should be recognized. When creating a Subscription, available schedule types are never, evenly, at_range_start, or at_range_end. If no revenue_schedule_type is set, the Subscription will inherit the revenue_schedule_type from its Plan.

Allowed:

trial_ends_at

date-time

If set, overrides the default trial behavior for the subscription. This must be a date and time, preferably in UTC. If the date is in the past, the subscription will skip the trial.

imported_trial

boolean

Defaults to false

Indicates if the subscription is to be treated as an import for data analysis or a real trial. This value can only be changed on a trial subscription and is persisted for its lifetime.

starts_at

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.

next_bill_date

date-time

Indicates the subscription's next billing period start date. Subsequent billing period start dates will be offset from this date. The first invoice will be prorated appropriately so that the customer only pays for the portion of the first billing period for which the subscription applies. Useful for forcing a subscription to bill on the first of the month.

coupon_code

string

Optional coupon code to redeem on the account and discount the subscription. Please note, the subscription request will fail if the coupon is invalid.

terms_and_conditions

string

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

customer_notes

string

Optional notes field. This will default to the Customer Notes text specified on the Invoice Settings page in your Recurly admin. Specify custom notes with this tag to add or override Customer Notes. Custom notes will stay with a subscription on all renewals. Custom notes made on an invoice for a one time charge will not carry over to subsequent invoices.

bulk

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. Set to true or false. Defaults to false.

transaction_type

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:

subscription_add_ons

array of objects

Defaults to []

Nested add-on information for the subscription. When creating, the new subscription will have no add-ons unless specified.

subscription_add_ons

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

proration_settings

object

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

gift_card

object

The gift card object is required in order to redeem a redemption code.

po_number

string

Optional notes field. Attach a PO number to the invoice.

net_terms

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.

net_terms_type

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:

collection_method

string

enum

Defaults to automatic

Optional field to set the collection for an invoice as automatic or manual. The default is automatic if it's not set.

Allowed:

Responses

201CREATED

422Unprocessable Entity