From Shopify to Commerce Layer: the case of Chilly's Bottles.

Orders

Subscriptions and order copies

Subscriptions allow merchants to offer regular purchases of a product or group of products. In this section you will learn how subscriptions work, performing order copies and placing them recursively.

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 subscriptions are defined by market and rely on the order subscription resource, which in turn leverage order copies to generate recurring orders.

How order copies work

Order copies generate a 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 order copying process

Order copying is an asynchronous process. You can check if it's pending, in progress, failed, or completed by inspecting the order copy status.

Copying promotions and discounts

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. If the source order's payment source is not reusable the 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, shipments are rebuilt and the first available shipping method is used. If in the meantime some items went out of stock the order copy fails, the error log shows an error, and the error count is incremented.

How order subscriptions work

Order subscriptions are created on top of a given source order and allow repeating it according to a specified frequency (from daily to yearly).

By default order 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.

As mentioned above, order subscriptions operations rely on order copies. When an order subscription is created, 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. Again, 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.

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 subscriptions and order copies 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, Checkout.com, and Stripe — more to come).