Create Plan Add-On

post

https://{subdomain}.{domain}/v2/plans/{plan_code}/add_ons

Add an add-on to a plan. Only one add-on can be created in a single request.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

plan_code

string

required

Unique code to identify the plan.

Body Params

item_code

string

Item code for an existing active item to be used as an add-on on the plan. This will be unique identifier for add-on within the plan.

add_on_code

string

required

Add-on code. Max of 50 characters. If item_code present, add_on_code must be absent. If item_code is not present, add_on_code is required.

add_on_type

string

Whether the add-on type is Fixed (fixed), or Usage-Based (usage). If item_code is present, add_on_type must be absent.

default_quantity

integer

Defaults to 1

Default quantity for the hosted pages.

unit_amount_in_cents

array of objects

required

Array of unit amounts with their currency code. Max 10000000. Optional if item_code present and existing item has default pricing. If tiers is present, unit_amount_in_cents must be absent. Otherwise unit_amount_in_cents is required.

unit_amount_in_cents*

liability_gl_account_id

string

length ≤ 13

The ID of a general ledger account. General ledger accounts are
only accessible as a part of the Recurly RevRec Standard and
Recurly RevRec Advanced features.

revenue_gl_account_id

string

length ≤ 13

The ID of a general ledger account. General ledger accounts are
only accessible as a part of the Recurly RevRec Standard and
Recurly RevRec Advanced features.

performance_obligation_id

string

length ≤ 13

The ID of a performance obligation. Performance obligations are
only accessible as a part of the Recurly RevRec Standard and
Recurly RevRec Advanced features.

name

string

required

Add-on name. Max of 255 characters. If item_code present, name must be absent. If item_code is not present, name is required.

display_quantity_on_hosted_page

boolean

Defaults to false

Default quantity for hosted pages. Must be true if tier_type != flat.

accounting_code

string

Accounting code for invoice line items for the add-on, defaults to the value of add_on_code. Max of 20 characters. If item_code present, accounting_code must be absent.

revenue_schedule_type

string

Defaults to evenly

Optional field for setting a revenue schedule type if add_on_type = fixed. This will determine how revenue for the associated Plan Add-On should be recognized. When creating a Plan Add-On, available schedule types are never, evenly, at_range_start, or at_range_end. If item_code present, revenue_schedule_type must be absent.

tax_code

string

length ≤ 50

Optional field used by Avalara, Vertex, and Recurly's In-the-Box tax solution to determine taxation rules. You can pass in specific tax codes using any of these tax integrations. For Recurly's In-the-Box tax offering you can also choose to instead use simple values of unknown, physical, or digital tax codes. If item_code/item_id is part of the request then tax_code must be absent.

optional

boolean

Defaults to true

Whether the add-on is optional for the customer to include in their purchase on the hosted payment page. If false, the add-on will be included when a subscription is created through the Recurly UI. However, the add-on will not be included when a subscription is created through the API. Click here for how to create a subscription with add-ons using the API.

measured_unit_id

string

The id of the measured unit on your site associated with the add-on. If item_code present, measured_unit_id must be absent.

usage_type

string

If add_on_type = usage, you must set a usage_type, which can be price or percentage. If price, the price is defined in unit_amount_in_cents or by providing a tier_type and a set of tiers. If percentage, the percentage is defined in usage_percentage. If item_code is present, usage_type must be absent.

usage_percentage

string

^(100(\.0{1,4})?|\d{1,2}(\.\d{1,4})?)$

The percentage taken of the monetary amount of usage tracked. This can be up to 4 decimal places. A value between 0.0000 and 100. Required if add_on_type is usage, usage_type is percentage and tier_type = flat. Must be omitted otherwise. For percentage tiered add ons use the percentage_tiers object.

usage_timeframe

string

Defaults to billing_period

The time at which usage totals are reset for billing purposes. It may be set to either billing_period or subscription_term and only applies when tier_type is tiered.

tier_type

string

Defaults to flat

The pricing model for the add-on. Defaults to flat. Other options include tiered, volume or stairstep. Cannot be changed once saved. For more information, click here.

tiers

array of objects

If the tier_type is flat, then tiers must be absent. The tiers object must include one to many tiers with ending_quantity and unit_amount_in_cents for the desired currencies. There must be one tier with an ending_quantity of 999999999 which is the default if not provided.

Tiers

percentage_tiers

array of objects

Required if tier_type != "flat" and usage_type == "percentage".
Array of objects which must have at least one set of tiers
per currency and the currency code. The tier_type must be volume or tiered,
if not, it must be absent. There must be one tier without an ending_amount_in_cents value
which represents the final tier.

percentage_tiers

Response

201