Subscriptions and order copies

What is an ecommerce subscription service?

A subscription-based ecommerce is a business model that allows customers to subscribe to products or services they need on a recurring basis in exchange for regular payments.

The value of a subscription is not only in the resultant predictable revenue. Subscriptions help your business increase acquisition and retention, make purchase forecasting easier, and are a real opportunity to build a stronger brand community.

How Commerce Layer handles subscriptions

Commerce Layer lets you offer subscriptions to registered customers. Commerce Layer's subscriptions are defined by market and rely on the order subscription resource. Starting from a source order, scheduled target orders are created. How this happens and the other resources involved in the process depend on the way you decide to handle subscriptions management:

• Automatic subscriptions — a subscription model must be associated with the market. One or more order subscriptions with related order subscription items are generated from the source order’s line items that have a frequency set. Recurring order copies are used to generate recurring target orders.
• Manual subscriptions — can be used in markets with no subscription model associated, for orders not containing any line items with a frequency set. One order subscription is generated from the source order which is entirely cloned. Order copies are used to generate recurring target orders.

Automatic subscriptions

In this case, one or more order subscriptions are automatically generated at the order level via trigger attribute, based on the strategy specified in the subscription model associated with the market and on the source order’s line items for which you’ve set a frequency. This way you can activate subscriptions that exclude some of the source order’s items (the ones that don’t have a frequency) and allow different subscription logic (e.g. different frequencies for different items) within the same source order.

What is a subscription model?

A subscription model can be optionally associated with a market to determine how automatic order subscriptions using recurring order copies are generated for the market in question. The subscription model defines which are the subscription frequencies available for the market (enabling sales channels to specify one of them for the order line items) and set the subscription strategy, one of:

• By frequency — as many order subscriptions as the different frequencies specified for the source order’s line items are generated, each with the related order subscription items (default strategy).
• By line items — an order subscription is generated for any source order’s line item that has a frequency, each with the related order subscription item.

At the subscription model level, you can decide whether the created subscriptions will be activated (default behavior) or not — considering the source order as the first run — and if they will be cancelled in case the source order is cancelled (not happening by default).

How to automatically generate order subscriptions

If a subscription model is associated with the market, the necessary order subscriptions are automatically generated based on the order’s line item for which you’ve specified a frequency, accordingly to the strategy set at the subscription model level. The involved order subscription items will be also created and associated with the generated order subscriptions.

The automatic order subscription generation process is triggered manually by using a specific attribute (so that you have complete control over the moment when to do it — usually as soon as the source order is placed or after). The source order’s customer email is stored, that order is considered the subscription's first run, and the generated order subscriptions are activated (unless specified differently at the subscription model level).

In this case, order subscription operations rely on recurring order copies. For each automatically generated order subscription, some source order’s information is copied (e.g. addresses, customer payment source, etc.), the related order subscription items are created and associated with the order subscriptions, and — if the recurring order copy is successful — the target order is placed.

In between each run you can edit the subscription (e.g. changing its frequency, expiration date, status, associated order subscription items, etc.) to dynamically manage the next occurences.

What are order subscription items?

Order subscription items can be of type SKU, bundle, or adjustment and are used to generate the target order's line items involved in the subscription process. Like line items, they have a quantity and a unit price (inherited from from the source order's line items, whether it's the default one or computed according to a price frequency tier).

If the subscription strategy is by frequency, for each automatically generated order subscription as many order subscription items as the source order’s line items that have that specific frequency will be generated. If the subscription strategy is by line items, for each automatically generated order subscription one order subscription item only will be generated.

Order subscription items can be created, updated, and deleted so that you can have complete control in editing the next subscription occurrences (e.g. adding or removing items for custom curation, changing some item's quantity or even unit price, etc.).

How recurring order copies work

Recurring order copies are a type of order factory that generates a target order from the associated source order and order subscription (and related order subscription items) and allow repeating it according to the frequency specified for the items (must be one of those available for the market, as set at the subscription model level).

When copying an order recursively the source order is never reused to generate any next runs, which are built on top of the associated order subscription and related order subscription items only.

Recurring order copies cannot be used standalone, they must be always associated with an automatic order subscription.

Manual subscriptions

In this case, a unique order subscription is manually generated starting from a source order that doesn’t contain any line item with frequency, in a market associated with no subscription model. This way, all the information and line items of the source order are copied to generate identical target orders, which will then be scheduled for placement with a specified frequency, set directly on the order subscription.

How to manually generate order subscriptions

A manually generated order subscription can be created on top of a given source order and allow repeating it according to a specified frequency.

By default, this kind of subscriptions activate from a placed source order and store the associated customer email. That order is considered the subscription's first run and all the next ones are scheduled on it. If you need full control over the subscription process you can override the default behavior and extend the order subscription creation to source orders that are not placed yet. In this case, you need to manually set the time you want the subscription to start and remember to activate it.

In this case, order subscriptions operation rely on order copies. When an order subscription is created manually, the source order is copied, the related target order is created, and — at the end of the process — an attempt to place it is performed. You can choose not to follow this default process and decide to place the target order manually. This is extremely useful in all those cases where you need to edit the next subscription occurrence (e.g. adding o removing line items to provide custom curation) and allows you to dynamically change the subscription content on each run.

Order subscriptions that use recurring order copies can be generated manually too: you just need to set the relationship with an existing subscription model and a source order, create and associate the order subscription items, and specify the customer payment source.

How order copies work

Order copies are a type of order factory that generates a carbon copy of a source order and all of its associated line items, line item options, and addresses into a target order. The payment source is copied if stored within the customer wallet (i.e. reusable) only.

When copying an order you can set different options, based on how you want the process to be performed in terms of automatic actions on the source and target orders:

• Place target order — the target order is placed at the end of the process (if possible).
• Cancel source order — the source order is cancelled at the end of the process.

Order copies can be used standalone (e.g. to provide buy‑it‑again options to your customer, or in general anytime you need to use an existing order as a template for new ones) or generated recursively as part of an order subscription.

Monitoring the process

Both recurring and simple order copying are asynchronous processes. You can check if it's pending, in progress, failed, or completed by inspecting the order copy status.

Promotions and discounts

Recurring order copies never compute promotions and gift cards. That means that you can apply promotions to the source order only but not to the automatically generated recurring target orders. To apply a discount based on the subscription frequency you can set some price frequency tiers or add some order subscription items of type adjustment with negative unit amount.

Order copies create frozen copies of the source order. That means that promotions and discounts line items are copied as is, without being recomputed. A recalculation occurs only if the target order is edited (e.g. adding or removing line items).

Reusing the payment source

Except for the case of wire transfers, automatic target order placement can be successful only if the source order comes with a payment source saved in the customer wallet. In the case of both types of subscriptions, if the source order's payment source is not reusable the order copy or recurring order copy fails, the target order remains pending, the error log shows an error, and the error count is incremented.

Rebuilding the shipments

Since at the time of the target order placement the availability of some products among stock locations may have changed, for both types of subscriptions shipments are rebuilt (based on the related order subscription items in case recurring order copies, based on the cloned line items in case of simple order copies) of and the first available shipping method is used. If in the meantime some items went out of stock the order copy or recurring order copy fails, the error log shows an error, and the error count is incremented.

Subscriptions expiration

Active order subscriptions can be deactivated (temporarily suspended) or cancelled. An optional expiration date can always be defined if needed.

Subscriptions errors and retry policy

At the moment subscriptions come with no automatic retry policy. An error counter is available and it is incremented if the related order copy fails — whatever the reason — but the subscription remains active. You can always verify whether the subscription's last run was successful or not. If the latter, you need to inspect the associated order copy checking its error log to fix any missing or wrong data and manually place the order.

As a best practice, we recommend attaching webhooks on order subscription, recurring order copy, and order copy events to react promptly in case something unexpected happens.

Available payment gateways

Since order copies' success depends on whether the source order's payment source is saved in the customer wallet or not, subscriptions are available for those payment gateways that support reusable payment sources (currently Adyen, Braintree, Stripe, and any external gateways with a properly configured token endpoint — more to come).