Create Subscription

post

https://{subdomain}.recurly.com/v2/subscriptions

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

You may optionally pass a coupon_code with the subscription request. The subscription will only be created if the coupon code is valid for the given plan. In the future, to change the coupon that is applied, you will have to remove this coupon from the corresponding account and redeem the new coupon.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

plan_code

string

plan_code for the subscription

account

object

nested account attributes

subscription_add_ons

array

nested add ons

subscription_add_ons

coupon_code

string

Optional coupon code to apply to the new subscription. Please note, the subscription request will fail if the coupon is invalid

unit_amount_in_cents

integer

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.

currency

string

Currency for the subscription

quantity

integer

Optionally override the default quantity of 1

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. The date must be in the future.

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.

total_billing_cycles

integer

Renews the subscription for a specified number of cycles, then automatically cancels. Defaults to the subscription renewing indefinitely.

first_renewal_date

date-time

Indicates a date at which the first renewal should occur. Subsequent renewals 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 renew on the first of the month.

collection_method

string

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

net_terms

integer

Defaults to 0

Integer representing the number of days after an invoice's creation that the invoice will become past due. If an invoice's net terms are set to '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. Defaults to '0'.

po_number

string

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

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'.

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.

vat_reverse_charge_notes

string

VAT Reverse Charge Notes only appear if you have EU VAT enabled or are using your own Avalara AvaTax account and the customer is in the EU, has a VAT number, and is in a different country than your own. This will default to the VAT Reverse Charge Notes text specified on the Tax Settings page in your Recurly admin, unless custom notes were created with the original subscription. Specify custom notes with this tag to add or override VAT Reverse Charge Notes. Custom notes will stay with a subscription on all renewals.

bank_account_authorized_at

date-time

Merchants importing recurring subscriptions paid with ACH into Recurly can backdate the subscription's authorization with this attribute using an iso8601 timestamp. This timestamp is used for alerting customers to reauthorize in 3 years in accordance with NACHA rules. If a subscription becomes inactive or the billing info is no longer a bank account, this timestamp is cleared.

Headers

string

enum

Defaults to application/json

Generated from available response content types

Allowed:

Responses

200

400