Item catalog

🚧

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.

Creating Items

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.

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.

Here's the content with the link converted to HTML syntax to open in a new window, while retaining the rest of the markdown:

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

Item management using 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 recurring charges (called add-ons) on Plans and Subscriptions. Each item can be sold via any channel for maximum flexibility and data tracking; the item itself is not "one-time" or "recurring".

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.

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 particular charge.

These one-time item charges can be created via the Purchases endpoint, the Line Items endpoint, or the Adjustments endpoint in Recurly's API.

Recurring Item Sales

Items can be sold on a recurring basis via add-ons on plans and subscriptions. If you prefer to have Recurly manage and enforce the specific items that can be sold on a plan, you can configure those available items as plan add-ons. If you do not limit the items that can be sold on a plan, or if you manage those restrictions on your own platform, you can bypass this configuration at the plan level, instead. Both approaches are detailed below.

Selling Items as Plan Add-Ons

Configuring items as add-ons on a plan restricts the offerings a subscriber to that plan can select. The only offerings available to the customer will be those add-ons specified on the plan. To sell items from your catalog as plan add-ons, select the desired item(s) from the dropdown in the Plan Add-Ons section of the New Plan page, or send the appropriate Item Code(s) 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.

In Recurly's API, item-based plan add-ons can be configured via the Plans or Plan Add-Ons endpoints and charged via the Purchases or Subscriptions endpoints. All plan add-on and subscription add-on configuration can also be done via the Recurly Admin Console.

Quantity-Based Pricing for Item Add-Ons

Items can be sold with fixed pricing or any of the available Quantity-Based Pricing models when added to a plan. Once you have selected your item, choose your pricing model and configure your tiers, if applicable. You can use the calculator to validate that specific unit amounts will charge as expected.

Once the pricing model has been saved, the specific tiers and prices can be updated on the plan or subscription to provide more personalized pricing. If you need to change the pricing model, create a new add-on.

Selling Items Directly on Subscriptions

Depending on your business model, it might make sense to avoid configuring item add-ons on your plans and simply specify the actual item(s) purchased on each individual customer subscription instead. If all of the items in your catalog are available as potential add-ons on a plan, if each of your customers has the ability to configure their own unique subscription offerings, or if you already control item availability in your own platform, this approach can provide much greater efficiency.

To support item sales directly on subscriptions, simply check the box in the Plan Add-Ons section of any plan to Add all items on subscriptions to this plan or utilize the allow_any_item_on_subscriptions field in our API.

This will make all of the active items in your catalog available as possible add-ons on subscriptions to that plan. Any items you add to your catalog in the future will automatically be available to use as a subscription add-on, and any items you disable in your catalog will be blocked from purchase on new subscriptions. When each individual subscription is created, simply select (via the Recurly Admin Console) or provide (via the API) the items that should be included in that subscription as recurring charges.

With this functionality enabled, it is still possible to configure both item-based and non-item-based add-ons on the plan, in addition to selling item-based add-ons directly on each subscription. Upon creating a subscription, you will be able to add the same item-based add-on up to twice, with one instance tied to the plan add-on and one instance configured directly on the subscription. This can support item sales at multiple prices, if desired. While item-based add-ons configured on the plan and on the subscription will look the same in the Recurly Admin Console, the add_on_source in the Recurly API will distinguish one from the other, if necessary.

When using the items direction on subscriptions capability, items can only be sold at a fixed price. If you want to leverage quantity-based pricing models, configure the item on the plan, and provide the quantity with the subscription. To help our product team prioritize supporting quantity-based pricing models for items directly on subscriptions, reach out to [email protected] and ask to be added to the feature request.

Items in our API and client libraries

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

• Ruby Client version is 3.9.0
• Node Client version is 3.10.0
• Python Client version is 3.8.0
• Dotnet Client version is 3.10.0
• Go Client version is 3.4.0
• Java Client version is 3.9.0
• PHP Client version is 3.4.0

For sites using our older v2 API, functionality for item creation and one-time item charges is on version 2.24 and above. Functionality for item-based plan add-ons is on version 2.25 and above. Flexibility around selling items directly on subscriptions is supported on version 2.27 and above.

• Ruby Client version is 2.18.10
• Python Client version is 2.9.17
• PHP Client version is 2.12.14
• Dotnet Client version is 1.17.5

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

Item data

For easy analysis, you can pull information about items and item sales from our API and exports.

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.

Limitations

• Items are not supported for usage-based add-ons. Charges for items can be added to the next invoice, but when you have a high-volume of usage use case, we recommend using usage based billing. If you need to log usage and have Recurly charge for that usage on the subsequent invoice, use our usage-based add-ons.