List Plan Add Ons

List a plan's add-ons

GET/plans/{plan_id}/add_ons

Use it in a workflow

Add a step and choose the Recurly connector.
Pick the List Plan Add Ons action (under add-on).
Fill in the fields below, then reference the result from later steps as {{listPlanAddOns.response.data}}.

Request

Path parameters

plan_idstringrequired

Plan ID or code. For ID no prefix is used e.g. `e28zov4fw0v2`. For code use prefix `code-`, e.g. `code-gold`.

Query parameters

idsarray<string>

Filter results by their IDs. Up to 200 IDs can be passed at once using commas as separators, e.g. `ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6`. **Important notes:** * The `ids` parameter cannot be used with any other ordering or filtering parameters (`limit`, `order`, `sort`, `begin_time`, `end_time`, etc) * Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request. * Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself.

limitinteger

Limit number of records 1-200.

Default 20

orderstring

Sort order.

One ofascdescDefault "desc"

sortstring

Sort field. You *really* only want to sort by `updated_at` in ascending order. In descending order updated records will move behind the cursor and could prevent some records from being returned.

One ofcreated_atupdated_atDefault "created_at"

begin_timestring (date-time)

Inclusively filter by begin_time when `sort=created_at` or `sort=updated_at`. **Note:** this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

end_timestring (date-time)

Inclusively filter by end_time when `sort=created_at` or `sort=updated_at`. **Note:** this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.

statestring

Filter by state.

One ofactiveinactive

Response

Returns 200 with an object. Read it in later steps with {{listPlanAddOns.response.data.<field>}}.

objectstring

Will always be List.

has_moreboolean

Indicates there are more results on subsequent pages.

nextstring

Path to subsequent page of results.

dataarray<object>

idstring

objectstring

plan_idstring

codestringrequired

The unique identifier for the add-on within its plan.

statestring

Add-ons can be either active or inactive.

One ofactiveinactive

namestringrequired

Describes your add-on and will appear in subscribers' invoices.

add_on_typestring

Whether the add-on type is fixed, or usage-based.

One offixedusage

usage_typestring

Type of usage, returns usage type if `add_on_type` is `usage`.

One ofpricepercentage

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

measured_unit_idstring

System-generated unique identifier for an measured unit associated with the add-on.

liability_gl_account_idstring

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_idstring

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_idstring

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

accounting_codestring

Accounting code for invoice line items for this add-on. If no value is provided, it defaults to add-on's code.

revenue_schedule_typestring

When this add-on is invoiced, the line item will use this revenue schedule. If `item_code`/`item_id` is part of the request then `revenue_schedule_type` must be absent in the request as the value will be set from the item.

One ofat_range_endat_range_startevenlynever

avalara_transaction_typeinteger

Used by Avalara for Communications taxes. The transaction type in combination with the service type describe how the add-on is taxed. Refer to [the documentation](https://help.avalara.com/AvaTax_for_Communications/Tax_Calculation/AvaTax_for_Communications_Tax_Engine/Mapping_Resources/TM_00115_AFC_Modules_Corresponding_Transaction_Types) for more available t/s types.

avalara_service_typeinteger

tax_codestring

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.

harmonized_system_codestring

The Harmonized System (HS) code is an internationally standardized system of names and numbers to classify traded products. The HS code, sometimes called Commodity Code, is used by customs authorities around the world to identify products when assessing duties and taxes. The HS code may also be referred to as the tariff code or customs code. Values should contain only digits and decimals.

display_quantityboolean

Determines if the quantity field is displayed on the hosted pages for the add-on.

Default false

default_quantityinteger

Default quantity for the hosted pages.

Default 1

optionalboolean

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.

currenciesarray<object>4 fields

itemobject6 fields

Just the important parts.

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_timeframestring

The time at which usage totals are reset for billing purposes.

One ofbilling_periodsubscription_termDefault "billing_period"

tiersarray<object>3 fields

percentage_tiersarray<object>2 fields

This feature is currently in development and requires approval and enablement, please contact support.

external_skustring

Optional, stock keeping unit to link the item to other inventory systems.

created_atstring (date-time)

updated_atstring (date-time)

deleted_atstring (date-time)

json

{
  "object": "string",
  "has_more": false,
  "next": "string",
  "data": [
    {
      "code": "string",
      "name": "string",
      "id": "string",
      "object": "string",
      "plan_id": "string",
      "state": "active",
      "add_on_type": "fixed",
      "usage_type": "price",
      "usage_calculation_type": "cumulative",
      "usage_percentage": 0,
      "measured_unit_id": "string",
      "liability_gl_account_id": "string"
    }
  ]
}

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

Was this page helpful?