Preview Subscription

post

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

Returns a preview for a new subscription applied to an account.
See above for information on available/required parameters.

For additional information regarding shipping fees, please see
the documentation

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

Tax previews

The Preview Subscription endpoint will return tax if your site's
taxable customer address is provided in the call. This may be the
Billing Information address or the Account Information address depending
on your site settings. Tax previews are supported for both Recurly Basic
taxes and if you are using your own Avalara account.

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

200

422Unprocessable Entity