Prerequisites

• Your site must have Credit Invoices, Only Bill What Changed, and Subscription Billing Terms enabled. Recurly sites created after July 26, 2018 have these features and item catalog enabled automatically.

Limitations

• Items are not supported for usage-based add-ons. For high-volume usage scenarios, use usage-based add-ons instead.

Definition

Key benefits

The items dashboard

Your items dashboard lists all items defined in your Recurly item catalog. Select any item name to view its details, edit it, or disable and re-enable it.

Create an item

Under the Configuration menu, select Items, then click Create New Item. Items can also be created via the v2 and v3 APIs. For large catalog imports, use the Multi-Item Upload Guide or contact Professional Services for assistance.

Define the following parameters when creating an item.

Item fields

Custom fields

Custom fields let you track additional item attributes beyond the standard fields — product variants, categories, family groupings, and more.

See the custom fields documentation for details on creating custom fields. To add one to your items, select Item as the Recurly Object when creating the field — it will then appear on the item form in the UI and through the API.

Item ID

When looking up an item via the API or in exports, you'll see a system-generated 19-character alphanumeric Item ID. This ID cannot be user-specified or edited.

Manage items

Editing items

Editing an item's attributes updates them going forward but does not affect past sales, existing plans, or existing subscriptions containing that item. For example, updating a default price changes it for new plans and charges only — previously created plans, subscriptions, and one-time charges keep their original price. Exports reflect item attributes as they were at the time of billing.

Items can be managed via the Items API and the Recurly Admin Console.

Disabling items

Disabling an item prevents it from being sold going forward. Existing uninvoiced charges for the item are not affected and should be removed manually if needed. Disabled items can still be edited to stay in sync with your system of record. Once re-enabled, an item can be actively sold again. Disabling and re-enabling can be done via the Admin Console and the API.

Webhooks for item management

Use item-specific webhook notifications with the Items API to keep your catalog in sync with downstream systems. Webhooks are available for item creation, updates, disables, and re-enables. See the webhook documentation for details.

Sell items

Items can be sold as one-time charges on accounts or as recurring charges (add-ons) on plans and subscriptions.

One-time item charges

When creating a one-time charge via the Admin Console, select Item as the charge type. Via the API, provide the appropriate item code. The charge description, product code, accounting code, tax settings, price, and revenue recognition all auto-populate from the item — though price and revenue recognition can be overridden for the individual charge.

One-time item charges can be created via the Purchases, Line Items, or Adjustments API endpoints.

Recurring item sales

Items can be sold on a recurring basis as add-ons on plans and subscriptions. Two approaches are available.

Selling items as plan add-ons

Configuring items as add-ons on a plan restricts what subscribers to that plan can select. To set this up, select the desired item(s) from the dropdown in the Plan Add-Ons section of the New Plan page, or provide the item code(s) when creating a plan via the API.

Add-on name, code, accounting code, tax settings, revenue recognition, and price all auto-populate from the item. The price can be overridden at the plan level. Item-based plan add-ons can be configured via the Plans or Plan Add-Ons endpoints and charged via Purchases or Subscriptions.

Quantity-based pricing for item add-ons

Items can be sold with fixed pricing or any available quantity-based pricing model when added to a plan. Select your pricing model and configure tiers as needed. Use the built-in calculator to validate that specific unit amounts charge as expected. Once saved, tiers and prices can be updated on the plan or subscription for personalized pricing. To change the pricing model itself, create a new add-on.

Selling items directly on subscriptions

If all catalog items should be available as potential add-ons, or if you manage item availability in your own platform, you can skip plan-level configuration and specify items directly on each individual subscription instead.

To enable this, check Add all items on subscriptions to this plan in the Plan Add-Ons section, or use the allow_any_item_on_subscriptions field in the API.

This makes all active catalog items available as add-ons on subscriptions to that plan. New items added to the catalog become available automatically; disabled items are blocked from new subscriptions. When creating a subscription, select or provide the items to include as recurring charges.

It's also possible to combine plan add-ons and direct subscription items on the same plan. The same item-based add-on can be added up to twice — once tied to the plan add-on and once configured directly on the subscription — supporting sales at multiple prices if needed. The add_on_source field in the API distinguishes between the two instances.

Item data and exports

Item usage across plans and subscriptions

Use the Items — Associated Plans and Items — Associated Subscriptions exports to see which plans and subscriptions contain a specific item. These are useful for assessing the impact of disabling or editing an item, and for analyzing pricing and packaging across your sales channels.

Item sales data

Item sales data is available in the Adjustments exports and via the Line Items and Adjustments API endpoints.

For purchases that include a catalog item, the item code, external SKU, and Recurly item ID are included in the export. The item code is also replicated in the Product Code field to support analysis across all sales channels.

API and client libraries

All item catalog functionality requires API version 2019-10-10 or above. We recommend always using the latest API version for the most up-to-date functionality.

v3 client libraries

Minimum versions required for item catalog support. Each card links to the minimum release — click "Latest releases" for the most recent version.

Legacy v2 API

For sites on the older v2 API, the following minimum versions apply.