Configure Subscriptions

Subscriptions is supported in your catalog by a set of product attributes. These attributes must be applied to a product type before the subscription configuration options are available for any individual product. Once products are enabled for subscriptions, you can set their subscription pricing.

Set Up Attributes

In order for any individual product to be enabled for subscriptions and/or trial periods, the relevant attributes must be enabled on its product type first. These are all out-of-the-box property attributes viewable at System > Schema > Product Attributes.

  • Subscription Mode: Allows a product to be enabled for either subscription-only purchase or both subscription and one-time purchase. If enabled, the Subscription Frequency is required to be set up as well.
  • Subscription Frequency: Determines the frequency options for the subscription. There are many possible values included by default, from weekly to annual, and any number of these values can be enabled on an individual subscription product. 
  • Trial Days: A number attribute that allows you to configure how many days a particular product is offered for a trial period, between 1 and 365.
  • Trial Product Code: A text attribute that allows you to specify a product code being offered for trial. This can be any product in the catalog.
  • Trial Product Variation Code: A text attribute that allows you to specify a variation product code being offered for trial. This can be any product in the catalog, but if a variant product code is selected then a Trial Product Code is also required.

Subscription Frequency

You can configure the Subscription Frequency attribute to support custom frequencies in addition to those included out-of-the-box. As with configuring any other list property attribute at System > Schema > Product Attributes, add a value by typing it in label:value format and saving your changes. The frequency for days must be a positive integer between 1-365, while frequencies in weeks must be a positive integer between 1-52. If you enter a value outside of this range, an error will not be displayed on the Product Attributes page but an error will be experienced when adding an item with that frequency to an order or cart.

Once added to the attribute and then enabled on subscription products as shown later in this guide, the custom frequencies will be selectable alongside out-of-the-box frequencies when adding items to the cart, configuring a subscription discount, or updating an existing subscription.

Configurable Bundle Attributes

Additional attributes are also required for subscriptions to support configurable bundles, which are sets of products that are ordered together as a single item. 

While there is a "Bundle" product usage type, configurable bundles for subscriptions are instead made by creating a "Standard" parent product with the bundled items as extras. Text or Boolean extras will remain associated to the parent product in a shipment, but product extras can be split into additional line items. To do this, the following property attributes should be added to the product type. Then one or both can be enabled on the standard product to configure the preferred extra behavior.

  • Split Extras in Shipments: Splits the price of the bundle between all product extras at the shipment level. These extras carry over to a shipment as individual line items, but are still displayed as one bundled item in the subscription and order details. This can only be enabled if the product's subscription mode is selected and the product has a nonzero price.
  • Split Extras in Subscriptions: "Flattens" the bundle into separate line items when creating the subscription. Each product extra will be displayed and treated as individual line items on the subscription and order details. This means that discounts, tax, and shipping refreshes will consider them separately. It is recommended for a flattened extra to be a single product instead of a product with multiple variations (such as a shirt with red and blue variations). 

You must assign extras to the parent product in order to create configurable bundles. Each product extra must be enabled for subscriptions in its product settings and have an individual price of $0 (because the total bundle price is set on the parent product and then distributed).

Custom Data Attributes

Attributes are also used to track custom data in subscriptions. Capturing custom data allows you to generate reporting data or track more insight about subscribers, such as their location, age, gender, birth date, or spending profile. For example, if you sell pet food to consumers then you may want to record their pet's name. If you are a B2B seller, then you may want to indicate the sales representative of the subscriber.

To create custom data attributes that can be used for subscription, set up a new order attribute and set its Apply Attribute To setting as either "Order and Subscription" or "Subscription Only". If you select Subscription Only, then this custom data will only be visible at the subscription level and will not appear on continuity orders. If you want this data to be included in continuity order attributes, then you should select Order and Subscription.

Once created, you can update these custom data attributes on individual subscriptions in the Subscription Details UI or Subscription API. However, the custom data is not editable when the subscription is in the Cancelled status, when ordering partial items now, or when updating the next order only.

Enable Product Types for Subscriptions

Using those product attributes, you have to enable product types for subscriptions before configuring subscription options for the individual products. At System > Schema > Product Types, you can apply these property attributes to any existing or new product type and select their possible values for that particular product type.

For example, the below ProductWithSubscriptionAttribute product type includes all five attributes. This means that any product belonging to the ProductWithSubscriptionAttribute type is able to be configured for subscription-only, subscription and one-time purchase, a trial period, and any of the default frequencies.The Product Types configuration page with subscription attributes

The difference between "1 Month" and "30 Days" frequencies is that the 1 Month option preserves the date so that orders are placed on the same day every month (such as July 15, August 15, September 15, and so forth). Meanwhile, a 30 Day frequency counts exactly 30 days between orders. 

Similar differences apply between other similar options, such as "4 Weeks" and "1 Month." A week counts as exactly 7 days.

Configure Products for Subscriptions

Once the product type supports subscriptions, you can enable subscriptions at the product level and select the subscription, frequency, and trial options that are offered for each product. This also applies to bundled products, which are treated as one product and can be subscribed to as one.

  1. Go to Main > Catalog > Products
  2. Select the product you want to offer subscriptions for.
  3. Go to the Properties configuration tab.
  4. Set the Subscription Mode to enable the product as either a subscription-only product (if this is selected, then one-time purchases will not be allowed for this item) or allow both subscription and one-time purchases. 
  5. If a subscription mode is enabled, then you are required to set available frequencies. Use the Subscription Frequency drop-down to select one or more frequencies for the product. The customer will be able to choose between these options when signing up for the subscription.
  6. If you want to enable trials for the product, enter the trial period length in Trial Days and the alternate Trial Product Code to be used for the trial version of the product. You cannot set a product code without configuring Trial Days.
  7. If applicable, you can also enter the Trial Product Variation Code if you are offering a variation of the base product for trial. If you select a variation code, then you are required to have also selected a Trial Product Code and Trial Days.
  8. Click Save.

This example shows a product that is enabled for both one-time purchases and subscriptions at a frequency of 1 Month, 3 Months, or 6 Months, and also offers a week-long trial period. If you do not want to offer a trial period on that particular product, you can simply leave those attributes blank.

The product configuration page with Subscription Mode, Frequency, Trial Days, and Trial Product Code fields

Configure Subscription Pricing

Subscription pricing is determined by price lists, and you can configure the preferred behavior of determining continuity order totals to account for any changes that may have happened since the initial subscription creation.

Subscription Price Lists

Price lists for configuring subscription pricing should always be made under an empty parent price list. This allows you to tie subscription discounts to the parent price list, so that all price lists will inherit that discount and you won't have to link the discount to every individual price list.

  1. Go to Main > Catalog > Price Lists to create new price lists and/or add products to a list according to the user guide. In the example below, Facewash is a subscription product.Close-up of a price list with a table of example price entries
  2. While viewing the price entry for a subscription product, note that there are separate configuration fields for one-time purchase and subscription Price and Sale Price values. These settings will override the default catalog pricing and allow you to offer the product at a reduced rate if purchased as part of a subscription rather than a one-time purchase.The Edit Price Entry module with callouts for Price, Sale Price, Subscription Price, and Subscription Sale Price fields
  3. Check the box next to any fields you want to use as an override and enter the appropriate price value. 
    • If you check a Price, then that field cannot be left blank. 
    • If you select the checkbox for a Sale Price and don't enter a value, then the catalog sale price will not be used either. This product will effectively have no sale price.
    • If a checkbox is not selected, then the item will use the catalog price or sale price.

You do not have to enter a value in the Price field if you want the one-time purchase price to default to the price set in the product catalog. In the above example, the catalog price is $10.00 and the price list's one-time purchase price is $9.00. If you left the Price blank, then one-time purchases would default to the base catalog price of $10.00. 

For more details about using price lists, see the Price Lists guide.

Continuity Order Pricing

Pricing is stored on the subscription at creation, meaning that by default the total will remain the same for continuity orders (unless a recalculation is triggered by editing the subscription, such as adjusting the quantity) and will not be refreshed if the price list changes. To offer more flexible and customer-friendly pricing for continuity orders, your settings can be configured to:

  • Update pricing at the moment a continuity order is created by applying the latest item prices.
  • Honor the lowest available total price by comparing the updated continuity order total with the original subscription total.

This pricing behavior is configured with two site settings under the Subscriptions tab at System > Settings > General. Both of these settings are applied whenever a continuity order is created, which includes orders generated by actions such as Order Now, setting the Next Order Date, and Update Next Order Only.

  • Apply Latest Item Price on Continuity Order: When enabled, the system refreshes the item price for each item on the continuity order (which fetches the latest price list information), along with any applicable discounts and taxes. This setting is also applied when creating a continuity order from Order Partial Items Now action. 
  • Apply Best Price on Continuity Order: When enabled, the system compares the continuity order's total with the original subscription total and applies whichever is lowest to the order.

For example, a continuity order is expected to be $50 per the original subscription price. Between the original subscription's creation and the continuity order's creation date, an item's pricing changes. When creating the continuity order, Apply Latest Item Price on Continuity Order refreshes the pricing for each item. This results in a calculated continuity order total that could be $75 (if prices went up) or $40 (if prices went down). Apply Best Price on Continuity Order then compares the original subscription total ($50) with this newly calculated continuity order total and the lower of the two is applied to the order. If the calculated total was $75, then the original $50 would be applied. If the calculated total was $40, then $40 would be applied.

The Subscriptions tab of the site settings, displaying three continuity order configurations.

Other Site Settings

Other optional configurations for subscriptions are also available in your site settings, as seen above.

  • Order Now Resets Next Order Date: When enabled, the next order date will be reset based on the current date and frequency whenever the Order Now action is performed on a subscription. If disabled, the next order date that already exists will remain unchanged. This is enabled by default.
  • Create Continuity Order _ Days Before Next Order Date: Continuity orders will be created this many days before the next order date. If left blank, continuity orders will be created on the next order date.
  • Update Next Order Date Up to _ Days From Existing Next Order Date: The next order cannot be set any further out than this limit when the date is manually updated. For example, if the date is August 24 and the next order date is September 2, and this configuration is set to 7 days, the next order cannot be changed to any date later than September 9. You will not be able to extend the next order date again until the next continuity order is placed, though it can be moved closer.
  • Pause Subscription for _ Continuity Orders: A paused subscription will be automatically reactivated after this many continuity orders have passed and cannot be paused again until the next continuity order is placed. It can still be manually reactivated at any point before this limit is reached. If left blank, the subscription will remain paused indefinitely until manually reactivated.
  • Skip Subscription _ Times: The ability to skip a continuity order will be disabled once this amount of skips has been made in a row. When this happens, a continuity order must be placed before the subscription can be skipped again.
  • Allow Order All or Partial Items Now Once Every _ Days: After ordering either all or partial items now, both of these actions will be restricted for this amount of days. For example, if a full order is created on September 20 and this setting is configured as 10 days, then both the entire order and partial order actions will not be available until September 30.
  • Send Subscription Reminder _ Days Before Next Order: The subscription order reminder email will be sent to customers this many days before their next order. This email template must also be enabled in the Email section of the site settings.
  • Send Email _ Days Before Paused Subscription is Re-Activated: The subscription pause limit reached email will be sent to customers this many days before their paused subscription is automatically re-activated.
  • Send Email Reminder Every _ Days for Paused Subscriptions: The recurring subscription paused reminder email will be sent to customers at this interval until the subscription is reactivated.