Pick the Convert Trial action (under subscription).
Fill in the fields below, then reference the result from later steps as {{convertTrial.response.data}}.
Request
Path parameters
subscription_idstringrequired
Subscription ID or UUID. For ID no prefix is used e.g. `e28zov4fw0v2`. For UUID use prefix `uuid-`, e.g. `uuid-123457890`.
Response
Returns 200 with an object. Read it in later steps with {{convertTrial.response.data.<field>}}.
idstring
objectstring
uuidstring
The UUID is useful for matching data with the CSV exports and building URLs into Recurly's UI.
accountobject
idstring
objectstring
codestring
The unique identifier of the account.
emailstring (email)
The email address used for communicating with this customer.
first_namestring
last_namestring
companystring
parent_account_idstring
bill_tostring
dunning_campaign_idstring
Unique ID to identify a dunning campaign. Used to specify if a non-default dunning campaign should be assigned to this account. For sites without multiple dunning campaigns enabled, the default dunning campaign will always be used.
planobject
Just the important parts.
idstring
objectstring
codestring
Unique code to identify the plan. This is used in Hosted Payment Page URLs and in the invoice exports.
namestring
This name describes your plan and will appear on the Hosted Payment Page and the subscriber's invoice.
statestring
One ofactivecanceledexpiredfailedfuturepaused
shippingobject
objectstring
addressobject19 fields
methodobject4 fields
amountnumber (float)
coupon_redemptionsarray<object>
Returns subscription level coupon redemptions that are tied to this subscription.
idstring
objectstring
Will always be `coupon`.
couponobject8 fields
statestring
One ofactiveinactive
remaining_durationobject3 fields
discountednumber (float)
The amount that was discounted upon the application of the coupon, formatted with the currency.
created_atstring (date-time)
pending_changeobject
idstring
The ID of the Subscription Change.
objectstring
subscription_idstring
The ID of the subscription that is going to be changed.
planobject4 fields
Just the important parts.
add_onsarray<object>18 fields
These add-ons will be used when the subscription renews.
unit_amountnumber (float)
tax_inclusiveboolean
This field is deprecated. Please do not use it.
Default false
quantityinteger
shippingobject4 fields
activate_atstring (date-time)
activatedboolean
Returns `true` if the subscription change is activated.
revenue_schedule_typestring
One ofat_range_endat_range_startevenlynever
invoice_collectionobject4 fields
business_entityobject4 fields
Business entity details
custom_fieldsarray<object>4 fields
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.
created_atstring (date-time)
updated_atstring (date-time)
deleted_atstring (date-time)
billing_infoobject1 fields
Accept nested attributes for three_d_secure_action_result_token_id
ramp_intervalsarray<object>5 fields
The ramp intervals representing the pricing schedule for the subscription.
next_bill_datestring (date-time)
If present, this sets the date the subscription's next billing period will start (`current_period_ends_at`). When combined with proration_settings, proration calculation should occur, only supported when timeframe is now.
current_period_started_atstring (date-time)
current_period_ends_atstring (date-time)
current_term_started_atstring (date-time)
The start date of the term when the first billing period starts. The subscription term is the length of time that a customer will be committed to a subscription. A term can span multiple billing periods.
current_term_ends_atstring (date-time)
When the term ends. This is calculated by a plan's interval and `total_billing_cycles` in a term. Subscription changes with a `timeframe=renewal` will be applied on this date.
trial_started_atstring (date-time)
trial_ends_atstring (date-time)
remaining_billing_cyclesinteger
The remaining billing cycles in the current term.
total_billing_cyclesinteger
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.
renewal_billing_cyclesinteger
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`.
auto_renewboolean
Whether the subscription renews at the end of its term.
Default true
ramp_intervalsarray<object>
The ramp intervals representing the pricing schedule for the subscription.
starting_billing_cycleinteger
Represents the billing cycle where a ramp interval starts.
remaining_billing_cyclesinteger
Represents how many billing cycles are left in a ramp interval.
starting_onstring (date-time)
ending_onstring (date-time)
unit_amountnumber (float)
Represents the price for the ramp interval.
paused_atstring (date-time)
Null unless subscription is paused or will pause at the end of the current billing period.
remaining_pause_cyclesinteger
Null unless subscription is paused or will pause at the end of the current billing period.
resume_atstring (date-time)
The date the subscription billing resumes following a pause. Null unless the subscription is paused or scheduled to be paused.
currencystring
3-letter ISO 4217 currency code.
revenue_schedule_typestring
One ofat_range_endat_range_startevenlynever
unit_amountnumber (float)
tax_inclusiveboolean
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 utilize this flag.
quantityinteger
add_onsarray<object>
idstring
objectstring
subscription_idstring
add_onobject11 fields
Just the important parts.
add_on_sourcestring
Used to determine where the associated add-on data is pulled from. If this value is set to
`plan_add_on` or left blank, then add-on data will be pulled from the plan's add-ons. If the associated
`plan` has `allow_any_item_on_subscriptions` set to `true` and this field is set to `item`, then
the associated add-on data will be pulled from the site's item catalog.
One ofplan_add_onitemDefault "plan_add_on"
quantityinteger
unit_amountnumber (float)
Supports up to 2 decimal places.
unit_amount_decimalstring (decimal)
Supports up to 9 decimal places.
revenue_schedule_typestring
One ofat_range_endat_range_startevenlynever
tier_typestring
The pricing model for the add-on. For more information,
[click here](https://docs.recurly.com/docs/billing-models#section-quantity-based). See our
[Guide](https://recurly.com/developers/guides/item-addon-guide.html) for an overview of how
to configure quantity-based pricing models.
One offlattieredstairstepvolumeDefault "flat"
usage_calculation_typestring
The type of calculation to be employed for an add-on. Cumulative billing will sum all usage records created in the current billing cycle. Last-in-period billing will apply only the most recent usage record in the billing period. If no value is specified, cumulative billing will be used.
One ofcumulativelast_in_period
usage_timeframestring
The time at which usage totals are reset for billing purposes.
One ofbilling_periodsubscription_termDefault "billing_period"
tiersarray<object>4 fields
If tiers are provided in the request, all existing tiers on the Subscription Add-on will be
removed and replaced by the tiers in the request. If add_on.tier_type is tiered or volume and
add_on.usage_type is percentage use percentage_tiers instead.
There must be one tier without an `ending_quantity` value which represents the final tier.
percentage_tiersarray<object>2 fields
If percentage tiers are provided in the request, all existing percentage tiers on the Subscription Add-on will be
removed and replaced by the percentage tiers in the request. Use only if add_on.tier_type is tiered or volume and
add_on.usage_type is percentage. There must be one tier without an `ending_amount` value which represents the final tier.
This feature is currently in development and requires approval and enablement, please contact support.
usage_percentagenumber (float)
The percentage taken of the monetary amount of usage tracked. This can be up to 4 decimal places. A value between 0.0 and 100.0. Required if add_on_type is usage and usage_type is percentage.
created_atstring (date-time)
updated_atstring (date-time)
expired_atstring (date-time)
add_ons_totalnumber (float)
subtotalnumber (float)
taxnumber (float)
Only for merchants using Recurly's In-The-Box taxes.
tax_infoobject
Only for merchants using Recurly's In-The-Box taxes.
typestring
Provides the tax type as "vat" for EU VAT, "usst" for U.S. Sales Tax, or the 2 letter country code for country level tax types like Canada, Australia, New Zealand, Israel, and all non-EU European countries. Not present when Avalara for Communications is enabled.
regionstring
Provides the tax region applied on an invoice. For U.S. Sales Tax, this will be the 2 letter state code. For EU VAT this will be the 2 letter country code. For all country level tax types, this will display the regional tax, like VAT, GST, or PST. Not present when Avalara for Communications is enabled.
ratenumber (float)
The combined tax rate. Not present when Avalara for Communications is enabled.
tax_detailsarray<object>7 fields
Provides additional tax details for Communications taxes when Avalara for Communications or Vertex Tax Breakdown is enabled or Canadian Sales Tax. Tax details will only be populated for the Invoice response when fetching a single invoice and not for the InvoiceList or LineItemList. Only populated for a single LineItem fetch when Avalara for Communications is enabled.
price_segment_idstring
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`.
totalnumber (float)
collection_methodstring
One ofautomaticmanualDefault "automatic"
po_numberstring
For manual invoicing, this identifies the PO number associated with the subscription.
net_termsinteger
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.
Default 0
net_terms_typestring
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.
One ofneteomDefault "net"
credit_application_policyobject
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.
modestringrequired
Determines which credit invoices are applied to invoices:
- `all`: All available credit invoices are applied (default)
- `none`: No credit invoices are applied automatically
One ofallnoneDefault "all"
allowed_originsarray<string>
Optional array of credit invoice origin types to allow when mode is `all`.
If not specified when mode is `all`, credits from all origins are applied.
Only valid when mode is `all`.
