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.
Your Items dashboard contains the list of items defined in your Recurly item catalog. You can click on any item name to view detailed item information, edit the item, or disable the item.
Under the Configuration menu, select "Items" to access your main Items page. From there, click 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.
To add a new item to your catalog, you'll need to define the following parameters:
This is the name that will appear on the Hosted Account Management Page and the subscriber's invoice. (255 character limit. Please note that your payment gateway may also place limitations on charge names, so it may be best to avoid special characters without checking with your gateway provider.)
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. (Accepts numbers, lowercase letters, dashes, pluses, and underscores only. 50 character limit.)
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.)
A description of the item, this can be displayed to your customers outside Recurly if configured via the API.
This optional field can be used to help identify invoice line items in exports. (Accepts numbers, lowercase letters, dashes, pluses, and underscores only. 25 character limit.)
The default amount to be charged for this item if a different price isn't specified during charge creation.
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.
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.
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.
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.
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.
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.
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.
Items in your Catalog can be maintained via our API and webhook notifications.
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 Catalog feature is on version 2.24 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.
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.
Items in your catalog can be sold as one-time charges on Accounts and as Saved Item Add-Ons on Plans and Subscriptions. These charges can be created via the Purchases endpoint, the Line Items or Adjustments endpoints, or the Recurly Admin Console.
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.
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.
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.
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.
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 6 days ago