Create Subscription

Create a new subscription

POST/subscriptions

Use it in a workflow

Add a step and choose the Recurly connector.
Pick the Create Subscription action (under subscription).
Fill in the fields below, then reference the result from later steps as {{createSubscription.response.data}}.

Request

Request body

Enter the body as JSON in the step's Body field.

plan_codestringrequired

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

plan_idstring

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

business_entity_idstring

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.

business_entity_codestring

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.

accountanyrequired

price_segment_idstring

The price segment ID, e.g. `e28zov4fw0v2`.

billing_info_idstring

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.

shippingobject

addressobject14 fields

address_idstring

Assign a shipping address from the account's existing shipping addresses. If `address_id` and `address` are both present, `address` will be used.

method_idstring

The id of the shipping method used to deliver the subscription. If `method_id` and `method_code` are both present, `method_id` will be used.

method_codestring

The code of the shipping method used to deliver the subscription. If `method_id` and `method_code` are both present, `method_id` will be used.

amountnumber (float)

expected_first_delivery_atstring (date-time)

The expected date of the first delivery for the subscription.

collection_methodstring

One ofautomaticmanualDefault "automatic"

currencystringrequired

3-letter ISO 4217 currency code.

unit_amountnumber (float)

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.

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 use this flag.

Default false

quantityinteger

Optionally override the default quantity of 1.

Default 1

add_onsarray<object>

codestringrequired

If `add_on_source` is set to `plan_add_on` or left blank, then plan's add-on `code` should be used. If `add_on_source` is set to `item`, then the `code` from the associated item should be used.

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

Default 1

unit_amountnumber (float)

Allows up to 2 decimal places. Optionally, override the add-on's default unit amount. If the plan add-on's `tier_type` is `tiered`, `volume`, or `stairstep`, then `unit_amount` cannot be provided.

unit_amount_decimalstring (decimal)

Allows up to 9 decimal places. Optionally, override the add-on's default unit amount. If the plan add-on's `tier_type` is `tiered`, `volume`, or `stairstep`, then `unit_amount_decimal` cannot be provided. If `unit_amount_decimal` is provided, `unit_amount` cannot be provided.

tiersarray<object>4 fields

If the plan add-on's `tier_type` is `flat`, then `tiers` must be absent. The `tiers` object must include one to many tiers with `ending_quantity` and `unit_amount`. There must be one tier without an `ending_quantity` value which represents the final tier. See our [Guide](https://recurly.com/developers/guides/item-addon-guide.html) for an overview of how to configure quantity-based pricing models.

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. There must be one tier without ending_amount value which represents the final tier. Use only if add_on.tier_type is tiered or volume and add_on.usage_type is percentage. 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. Must be omitted otherwise. `usage_percentage` does not support tiers. See our [Guide](https://recurly.com/developers/guides/usage-based-billing-guide.html) for an overview of how to configure usage add-ons.

revenue_schedule_typestring

One ofat_range_endat_range_startevenlynever

coupon_codesarray<string>

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

custom_fieldsarray<object>

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.

namestringrequired

Fields must be created in the UI before values can be assigned to them.

valuestringrequired

Any values that resemble a credit card number or security code (CVV/CVC) will be rejected.

source_record_typestring

The type of record a custom field was automatically copied from.

One ofaccountplanproductsubscription

source_record_idstring

The UUID of the record this custom field was automatically copied from. Only present when the field was copied from another record.

trial_ends_atstring (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.

starts_atstring (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_datestring (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.

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 new set of ramp intervals for the subscription.

starting_billing_cycleinteger

Represents the billing cycle where a ramp interval starts.

Default 1

unit_amountnumber (float)

Represents the price for the ramp interval.

revenue_schedule_typestring

One ofat_range_endat_range_startevenlynever

terms_and_conditionsstring

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.

customer_notesstring

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.

credit_customer_notesstring

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.

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

gateway_codestring

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.

transaction_typestring

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.

One ofmoto

gift_card_redemption_codestring

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

bulkboolean

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.

Default false

proration_settingsobject

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

chargestring

Determines how the amount charged is determined for this change

One offull_amountprorated_amountDefault "prorated_amount"

transaction_descriptor_suffixstring

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.

json

{
  "plan_code": "string",
  "account": null,
  "currency": "string",
  "plan_id": "string",
  "business_entity_id": "string",
  "business_entity_code": "string",
  "price_segment_id": "string",
  "billing_info_id": "string",
  "shipping": {
    "address": {
      "first_name": "string",
      "last_name": "string",
      "street1": "string",
      "city": "string",
      "postal_code": "string",
      "country": "string",
      "nickname": "string",
      "company": "string",
      "email": "string",
      "vat_number": "string",
      "phone": "string",
      "street2": "string"
    },
    "address_id": "string",
    "method_id": "string",
    "method_code": "string",
    "amount": 0,
    "expected_first_delivery_at": "2025-01-01T00:00:00Z"
  },
  "collection_method": "automatic",
  "unit_amount": 0,
  "tax_inclusive": false
}

Response

Returns 201 with an object. Read it in later steps with {{createSubscription.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

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

Default 0

net_terms_typestring

One ofneteomDefault "net"

credit_application_policyobject

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

json

{
  "id": "string",
  "object": "string",
  "uuid": "string",
  "account": {
    "id": "string",
    "object": "string",
    "code": "string",
    "email": "name@example.com",
    "first_name": "string",
    "last_name": "string",
    "company": "string",
    "parent_account_id": "string",
    "bill_to": "string",
    "dunning_campaign_id": "string"
  },
  "plan": {
    "id": "string",
    "object": "string",
    "code": "string",
    "name": "string"
  },
  "state": "active",
  "shipping": {
    "object": "string",
    "address": {
      "id": "string",
      "object": "string",
      "account_id": "string",
      "nickname": "string",
      "first_name": "string",
      "last_name": "string",
      "company": "string",
      "email": "string",
      "vat_number": "string",
      "phone": "string",
      "street1": "string",
      "street2": "string"
    },
    "method": {
      "id": "string",
      "object": "string",
      "code": "string",
      "name": "string"
    },
    "amount": 0
  },
  "coupon_redemptions": [
    {
      "id": "string",
      "object": "string",
      "coupon": {
        "id": "string",
        "object": "string",
        "code": "string",
        "name": "string",
        "state": "expired",
        "discount": {
          "type": "fixed",
          "percent": 0,
          "currencies": [
            {
              "currency": null,
              "amount": null
            }
          ],
          "trial": {
            "unit": "day",
            "length": 0
          }
        },
        "coupon_type": "bulk",
        "expired_at": "2025-01-01T00:00:00Z"
      },
      "state": "active",
      "remaining_duration": {
        "type": "forever",
        "expires_at": "2025-01-01T00:00:00Z",
        "redemptions_remaining": 0
      },
      "discounted": 0,
      "created_at": "2025-01-01T00:00:00Z"
    }
  ],
  "pending_change": {
    "id": "string",
    "object": "string",
    "subscription_id": "string",
    "plan": {
      "id": "string",
      "object": "string",
      "code": "string",
      "name": "string"
    },
    "add_ons": [
      {
        "id": "string",
        "object": "string",
        "subscription_id": "string",
        "add_on": {
          "id": "string",
          "object": "string",
          "code": "string",
          "name": "string",
          "add_on_type": "fixed",
          "usage_type": "price",
          "usage_percentage": 0,
          "measured_unit_id": "string",
          "item_id": "string",
          "external_sku": "string",
          "accounting_code": "string"
        },
        "add_on_source": "plan_add_on",
        "quantity": 0,
        "unit_amount": 0,
        "unit_amount_decimal": "string",
        "revenue_schedule_type": "at_range_end",
        "tier_type": "flat",
        "usage_calculation_type": "cumulative",
        "usage_timeframe": "billing_period"
      }
    ],
    "unit_amount": 0,
    "tax_inclusive": false,
    "quantity": 0,
    "shipping": {
      "object": "string",
      "address": {
        "id": "string",
        "object": "string",
        "account_id": "string",
        "nickname": "string",
        "first_name": "string",
        "last_name": "string",
        "company": "string",
        "email": "string",
        "vat_number": "string",
        "phone": "string",
        "street1": "string",
        "street2": "string"
      },
      "method": {
        "id": "string",
        "object": "string",
        "code": "string",
        "name": "string"
      },
      "amount": 0
    },
    "activate_at": "2025-01-01T00:00:00Z",
    "activated": false,
    "revenue_schedule_type": "at_range_end"
  },
  "current_period_started_at": "2025-01-01T00:00:00Z",
  "current_period_ends_at": "2025-01-01T00:00:00Z",
  "current_term_started_at": "2025-01-01T00:00:00Z"
}

Need more? See the Recurly guide for connection setup and behaviour shared by every action.

Was this page helpful?