The Reference Docs Developer Hub

Welcome to the Reference Docs developer hub. You'll find comprehensive guides and documentation to help you start working with Reference Docs as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Item Catalog

If you sell standard offerings or combinations of offerings to many customers, organizing those in a Recurly catalog provides many benefits. You'll experience faster charge creation, easier management of offerings, and analytics about your offerings across all sales channels. Because your offerings may be physical, digital, or service-oriented, Recurly collectively calls these "Items".

Pre-Requisite Features

In order to use this feature, your site must be configured with the Credit Invoices, Only Bill What Changed, and Subscription Billing Terms features. Please contact us if you would like more information about upgrading to these features.

Recurly sites created after July 26, 2018 will automatically have these features and Item Catalog enabled.

Dashboard

Your Items dashboard contains the list of items defined in your Recurly item catalog. You can select any item name to view detailed item information, edit the item, or disable / re-enable the item.

Item Dashboard example

Item Dashboard example

Creating an Item

Under the Configuration menu, select "Items" to access your main Items page. From there, select Create New Item. Items can also be created via our v2 and v3 APIs. If you would like assistance importing a large item catalog into Recurly, our Professional Services organization is available to help or you can leverage our simple Multi-Item Upload Guide.

To add a new item to your catalog, you'll need to define the following parameters:

Item Name

This is the name that will appear on the Hosted Account Management Page and the subscriber's invoice. (255 character limit. Your payment gateway may also place limitations on charge names, avoid using special characters without checking with your gateway provider first.)

Item Code

This is the item's unique Recurly identifier and is used in Hosted Account Management Page URLs and to fetch items via the API. For merchants using the Product field in Vertex, that value should be entered here. (50 character limit. Accepts numbers, lowercase letters, dashes, pluses, and underscores only.)

External SKU

This optional field can be used to associate items in Recurly with other systems/platforms. External SKU can be re-used across items if desired. (50 character limit.)

Item Description

A description of the item, this can be displayed to your customers outside Recurly if configured via the API.

Accounting Code

This optional field can be used to help identify invoice line items in exports. (25 character limit. Accepts numbers, lowercase letters, dashes, pluses, and underscores only.)

Default Price

The default amount to be charged for this item if a different price isn't specified during charge creation.

Revenue Recognition

If the Revenue Recognition feature is enabled, this field specifies how invoiced charges from this item should be realized as revenue. The item's default revenue recognition schedule can be modified during charge creation.

Taxes

If taxation is enabled, these fields specify whether sales of this item should be taxed, and how they should be taxed. The value(s) specified will carry over to all sales of the item.

Custom Fields

Recurly's custom fields can be used to track additional item attributes or identifiers beyond those listed above. Use these to capture product variant details, product family/category, and more.

Custom Fields example

Custom Fields example

See our Custom Fields documentation for detailed information about creating custom fields in Recurly. To add a custom field to the items in your catalog, simply select "Item" as the Recurly Object when you create a custom field. The next time you create or edit an item in your catalog, you will see the custom field available on the UI form or through the API.

Item ID

When you look up an item in the API or in exports, you will see a 19-character alphanumeric Item ID. This is a system-generated ID to reference your item and cannot be user-specified or edited.

Disabling Items

Disabling an item will prevent it from being sold going forward. Existing uninvoiced charges with this item (both one-time charges and subscription charges) will not be affected and should be removed manually, if necessary. Disabled items can still be edited, to keep them up to date with your system of record should you choose to enable them again in the future. Once an item is re-enabled, it can be actively sold again. Items can be disabled and re-enabled via the Recurly Admin Console and the API.

Managing Items

Editing an item via the Recurly Admin Console or API will change the item's attributes going forward, but will not impact past sales of the item or existing plans or subscriptions containing the item. For example, if an item's default price is updated, previously-created plans, subscriptions, and one-time charges for the item will remain the same, whether they have been invoiced or not, but new plans and one-time charges for the item will default to the new item price. Exports that show item sales will reflect the item attributes at the time the item was billed.

Items in your Catalog can be maintained via our API and the Recurly Admin Console. Item alerts are available via our webhook notifications.

Item Management via the API

Item management is supported via the Items API endpoint to keep your item catalog in Recurly in sync with your external system of record. This endpoint allows you to create new items; edit, disable, and re-enable existing items; and retrieve details for all items in your catalog or for a specific item.

In our API, functionality for the Catalog feature is on version 2019-10-10 and above.

  • Ruby Client version is 3.1.0
  • Node Client version is 3.1.0
  • Python Client version is 3.2.0
  • Dotnet Client version is 3.1.0
  • Java Client version is 3.1.0

For sites using our older v2 API, functionality for the Item Catalog and one-time item charges is on version 2.24 and above. Functionality for recurring item charges is on version 2.25 and above.

  • Ruby Client version is 2.18.5
  • Python Client version is 2.9.12
  • PHP Client version is 2.12.9
  • Dotnet Client version is 1.17.0

However, we recommend always updating to the latest version of the API so that you have the most up-to-date functionality.

Item Management via Webhooks

You can use our item-specific webhook notifications in conjunction with the Items API endpoint to help keep your items in Recurly in sync with any downstream systems. Webhooks are available for new item creation, item updates, and item disables and re-enables. Additional information about these item notifications is available in our webhook documentation.

Selling Items

Items in your catalog can be sold as one-time charges on Accounts and as Saved Item Add-Ons on Plans and Subscriptions.

One-Time Item Sales

Information about creating one-time charges can be found here. Simply select "Item" as the Charge Type when creating a one-time charge via the Admin Console, or send the appropriate Item Code when creating a charge via the API. These one-time item charges can be created via the Purchases endpoint, the Line Items or Adjustments endpoints, or the Recurly Admin Console.

The charge Description, Product Code, Accounting Code, and Tax settings will be auto-populated from the item. The Price and Revenue Recognition for the charge will also be auto-populated from the item, but these fields can be changed to reflect the desired values for this charge.

Creating a One-Time Item Charge

Creating a One-Time Item Charge

Recurring Item Sales

Coming Soon!

Currently, the only way to sell items in Recurly is through one-time purchases. Recurring Item Sales is coming soon. If you would like to be included in Early Access testing for this feature, please contact [email protected]

Items can be sold on a recurring basis via add-ons on plans and subscriptions. Select the item from the dropdown in the Billable Add-Ons section of the New Plan page, or send the appropriate Item Code when creating a plan via the API. These Saved Item add-on charges can be created via the [Purchases][22] endpoint, the Plans or Plan Add-Ons endpoints, the Subscriptions endpoint, or the Recurly Admin Console.

The Add-On Name, Add-On Code, Accounting Code, Tax settings, and Revenue Recognition for the add-on will be auto-populated from the item. The add-on Price will also be auto-populated from the item, but this value can be changed to reflect the desired price for this plan. More information about creating add-ons can be found here.

Creating a Recurring Item Add-On

Creating a Recurring Item Add-On

Item Usage Across Plans and Subscriptions

For easy visibility and analytics, you can see which plans and subscriptions contain a specific item from your catalog via the Items — Associated Plans and Items — Associated Subscriptions exports. Use these to identify the impact of disabling or editing an item, analyze pricing & packaging of an item across your sales channels, and more!

Item Sales Data

Information about item sales can be pulled from the Adjustments exports (Adjustments, Adjustments - Coupons, and Adjustments - Taxes) and from the Line Items and Adjustments API endpoints. Version details for the exports are listed below, and version details for the API endpoints are listed above.

  • Adjustments export version is 3
  • Adjustments - Coupons export version is 2
  • Adjustments - Taxes export version is 3

For any purchases that include an item from your catalog, the Item Code, External SKU, and Recurly's Item ID for that item will be displayed. The Item Code is also replicated in the Product Code field to support the analysis of item sales across all sales channels.

Updated 17 days ago

Item Catalog


If you sell standard offerings or combinations of offerings to many customers, organizing those in a Recurly catalog provides many benefits. You'll experience faster charge creation, easier management of offerings, and analytics about your offerings across all sales channels. Because your offerings may be physical, digital, or service-oriented, Recurly collectively calls these "Items".

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.