# Subscriptions and order copies {% hint style="info" icon="lightbulb" %} Subscriptions generate recurring target orders from a source order — automatically via a subscription model with recurring order copies, or manually via simple order copies that clone the source order in full. {% endhint %} ## What is an ecommerce subscription service? A subscription-based ecommerce is a business model that allows customers to subscribe to products or services 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. Subscriptions are defined by market and rely on the [order subscription](/core-api-reference/order_subscriptions.md) resource. Starting from a source order, scheduled target orders are created. How this happens and the other resources involved depend on how you decide to handle subscription 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 that don't contain 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 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 without a frequency) and allow different subscription logic — for example, different frequencies for different items — within the same source order.
### What is a subscription model? A [subscription model](/core-api-reference/subscription_models.md) can be optionally associated with a market to determine how automatic order subscriptions using recurring order copies are generated. It defines which subscription frequencies are available for the market — enabling sales channels to specify one of them for order line items — and sets 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 each source order line item that has a frequency, each with its related order subscription item. At the subscription model level, you can decide whether the created subscriptions will be activated (default) or not — considering the source order as the first run — and whether they will be cancelled if the source order is cancelled (not the default behavior). ### 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 items for which you've specified a frequency, according to the strategy set at the subscription model level. The related order subscription items are also created and associated with the generated order subscriptions. The [automatic generation process](/how-tos/placing-orders/subscriptions.md) is triggered by using a specific attribute — giving you full control over when to do it, usually as soon as the source order is placed or shortly 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 otherwise at the subscription model level). Order subscription operations rely on [recurring order copies](#how-recurring-order-copies-work). For each automatically generated order subscription, some source order information is copied (e.g. addresses, customer payment source), 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. Between each run you can [edit the subscription](/how-tos/placing-orders/subscriptions/updating-the-subscriptions.md) (e.g. changing its frequency, expiration date, status, or associated order subscription items) to dynamically manage the next occurrences. ### What are order subscription items? [Order subscription items](/core-api-reference/order_subscription_items.md) 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 the source order's line items, whether it's the default price or computed according to a price frequency tier). If the subscription strategy is *by frequency*, as many order subscription items as the source order's line items with that specific frequency are generated for each order subscription. If the strategy is *by line items*, one order subscription item only is generated per order subscription. Order subscription items can be created, updated, and deleted, giving you full control over the next subscription occurrences — for example, adding or removing items for custom curation, or changing an item's quantity or unit price. ### How recurring order copies work [Recurring order copies](/core-api-reference/recurring_order_copies.md) are a type of order factory that generates a target order from the associated source order and order subscription (and related order subscription items), repeating it according to the frequency specified for the items — which 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 subsequent runs — those are built entirely from the associated order subscription and its order subscription items. Recurring order copies cannot be used standalone. They must always be associated with an [automatic order subscription](/core-api-reference/order_subscriptions.md#automatic-order-subscription-generation). ## Manual subscriptions A unique order subscription is manually generated starting from a source order that doesn't contain any line item with a frequency, in a market with no subscription model associated. All the information and line items of the source order are copied to generate identical target orders, which are then scheduled for placement with a specified frequency set directly on the order subscription.
### How to manually generate order subscriptions A [manually generated](/core-api-reference/order_subscriptions.md#manual-order-subscription-generation) order subscription can be created on top of a given source order and allows repeating it according to a specified frequency. By default, this type of subscription activates from a *placed* source order and stores the associated customer email. That order is considered the subscription's first run and all subsequent ones are scheduled from it. If you need full control over the subscription process, you can override the default behavior and extend order subscription creation to source orders that are not yet placed — in that case, you need to manually set the start time and remember to activate it. Order subscription operations rely on [order copies](#how-order-copies-work). 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 and place the target order manually instead. This is useful when you need to edit the next subscription occurrence (e.g. adding or removing line items for custom curation) and allows you to dynamically change the subscription content on each run. Order subscriptions that use recurring order copies can also be generated manually — 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](/core-api-reference/order_copies.md) are a type of order factory that generates a full copy of a source order — including all associated line items, line item options, and addresses — into a target order. The payment source is copied only if it is stored within the customer wallet (i.e. reusable). When copying an order you can set different options for how the process is performed: * **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 — for example, to provide *buy-it-again* options to customers, or any time you need to use an existing order as a template — or generated recursively as part of an order subscription. ## Monitoring the process Both recurring and simple order copying are asynchronous processes. You can check whether the copy is *pending*, *in progress*, *failed*, or *completed* by inspecting the order copy status. ## Promotions and discounts Recurring order copies never compute promotions and gift cards. You can apply promotions to the source order only — not to the automatically generated recurring target orders. To apply a discount based on the subscription frequency, you can set price frequency tiers or add order subscription items of type adjustment with a negative unit amount. Order copies create *frozen* copies of the source order, meaning promotion and discount line items are copied as-is without being recomputed. A recalculation occurs only if the target order is edited (e.g. by adding or removing line items). ## Reusing the payment source Except for wire transfers, automatic target order placement can only succeed if the source order comes with a payment source saved in the customer wallet. For both subscription types, 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 records an error, and the error count is incremented. ## Rebuilding the shipments Since product availability across stock locations may have changed by the time the target order is placed, shipments are rebuilt for both subscription types — based on order subscription items for recurring order copies, or cloned line items for simple order copies — and the first available shipping method is used. If any items have gone out of stock, the order copy or recurring order copy fails, the error log records 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 Subscriptions currently have no automatic retry policy. An error counter is available and incremented whenever the related order copy fails — for any reason — but the subscription remains active. You can always verify whether the last run was successful. If not, inspect the associated order copy's error log to fix any missing or incorrect data and manually place the order. As a best practice, attach webhooks on order subscription, recurring order copy, and order copy events to react promptly when something unexpected happens. ## Available payment gateways Since the success of order copies depends on whether the source order's payment source is saved in the customer wallet, subscriptions are available for payment gateways that support reusable payment sources — currently Adyen, Braintree, Stripe, and any external gateways with a properly configured token endpoint. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.commercelayer.io/data-model/orders/subscriptions-and-order-copies.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.