> For the complete documentation index, see [llms.txt](https://docs.commercelayer.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.commercelayer.io/core-api-reference/2026-05/order_subscriptions.md).

# Order subscriptions

The order subscription object and the allowed CRUD operations on the related resource endpoint

Order subscriptions allow repeating a given source order according to a specified frequency: smaller is `hourly`, larger is `yearly`. If you need a custom frequency that is not in the list of allowed values, you can use a [crontab expression](https://crontab.guru/).

Order subscriptions can be generated [automatically](#automatic-order-subscription-generation) from the [line items](/core-api-reference/2026-05/line_items.md#choosing-line-items-that-generate-subscriptions) that have a frequency using a trigger attribute at the [order](/core-api-reference/2026-05/orders.md#automatic-subscriptions-generation) level, in which case [recurring order copies](/core-api-reference/2026-05/recurring_order_copies.md) are used as the order factory that generates the target orders.

To suspend or cancel an order subscription, you can use the `_deactivate` and `_cancel` trigger attributes.

Currently, order subscriptions have no retry policy: in case, for any reason, the order copy fails, the `errors_count` counter is incremented, but the subscription is kept `active` (unless expired, deactivated, or `cancelled`). As soon as the order copy process starts, the order subscription status is moved to `running` and moved back to `active` once the process is successfully completed.

It is possible to check the `succeeded_on_last_run` attribute to inspect the subscription's last run state: if `false`, you can inspect the last associated `recurring_order_copy` to fix any missing/bad data.

You can attach [webhooks](/core/real-time-webhooks.md#supported-events) on order subscription and recurring order copy events, to act promptly in case something unexpected happens. You can also set the `renewal_alert_period` attribute (expressed in **hours** — the minimum value is `1`, the maximum value is `720` e.g. **30 days**) so that the related webhook event is fired accordingly and you can send customers a notification about upcoming recurring orders associated with subscriptions.

## Automatic order subscription generation

To automatically generate order subscriptions based on a source order's line items with frequency, you need to associate a [subscription model](/core-api-reference/2026-05/subscription_models.md) with your market, then send the `_create_subscriptions` trigger attribute on the order. The source order is considered the subscription's first run. Some of its information is copied (e.g. addresses, payment sessions, etc.), the involved [order subscription items](/core-api-reference/2026-05/order_subscription_items.md) are created and associated with the generated order subscriptions, and — upon successful recurring order copy — the target order is placed.

{% hint style="info" %}
The `_create_subscriptions` trigger is only effective once the order is placed, so it can be sent together with the `_place` trigger or on a subsequent update.
{% endhint %}

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

By default, automatically generated order subscriptions are directly activated, unless [differently specified](/core-api-reference/2026-05/subscription_models.md#automatic-subscription-activation-and-cancellation) at the subscription model level.

{% hint style="warning" %}
When changing the subscription's frequency, make sure to also manually update the `next_run_at` attribute with the correct time in the future, otherwise the next subscription run might not happen when expected.
{% endhint %}

## Payment sessions

The subscription stores the payment instrument needed to fund each recurring run. At creation time, it is automatically derived by checking the source order's [payment sessions](/core-api-reference/2026-05/payment_sessions.md):

* If any of them is linked to a [payment wallet](/core-api-reference/2026-05/payment_wallets.md), that wallet is stored on the subscription and reused on every run.
* Otherwise, if any of them uses a non-vaultable [payment setting](/core-api-reference/2026-05/payment_settings.md), that payment setting is stored directly on the subscription instead.
* Failing that, if the source order's only payment is a single [gift card](/core-api-reference/2026-05/payment_setting_gift_cards.md) session, its payment setting and its code are both stored on the subscription, the latter in the `gift_card_code` attribute.

{% hint style="info" %}
A wallet always wins over a gift card on the same order: a gift card used once alongside another payment method is a one-off, not a recurring instrument. To renew on a gift card, set the gift card payment setting and code on the subscription explicitly.
{% endhint %}

{% hint style="warning" %}
A gift card payment setting requires a gift card code, and cannot be combined with a payment wallet. Passing a gift card code alongside any other payment setting is rejected with a `422 Unprocessable Entity` error.
{% endhint %}

The subscription can only auto-activate if its payment instrument is ready: a payment wallet or a payment setting must be present, and — for a gift card — the card must still resolve against the order and hold a balance that covers it. When it isn't, the subscription moves to `pending` status, records the reason among its errors, and must be activated again once the instrument is usable.

On each automatic run, a recurring order copy creates a single new payment session on the target order from the subscription's stored payment wallet, payment setting, or gift card code — it is not a copy of the source order's sessions. The new session is authorized automatically as part of the run — no manual [payment authorization](/core-api-reference/2026-05/payment_authorizations.md) is required. Free target orders are skipped entirely and no session is created.

{% hint style="info" %}
A subscription model is required to generate order subscriptions for orders using payment sessions, so runs always go through recurring order copies.
{% endhint %}

### Gift card coverage

Each run opens its own gift card session on the target order and checks that the card covers the renewal in full before committing to it. A card that can no longer be resolved (e.g. deleted or expired), or whose balance falls short of the target order total, fails the run: the target order is left unplaced, the gift card balance is left untouched, `errors_count` is incremented, and the subscription drops to `pending`.

{% hint style="info" %}
Top the card up — or update the subscription with a different gift card code — then send the `_activate` trigger attribute to resume it. Coverage is re-checked at that point, so a subscription only goes back to `active` if the card can actually pay.
{% endhint %}

## Unattended renewals

A renewal is a merchant-initiated payment: nobody is at a browser when it runs. Commerce Layer tells the gateway so, charging the stored instrument off session — no 3DS challenge and no CVC re-entry are attempted, and no client-side checkout step is involved.

{% hint style="warning" %}
An instrument that turns out to require customer authentication is declined for that run, rather than left waiting for a confirmation that nobody is there to give. The run fails and the subscription follows the usual failure path above.
{% endhint %}

{% hint style="info" %}
The instrument that makes this possible is either an existing payment wallet used to pay the source order, or one stored during that order's own checkout: when the payment session is created with `vaulting` set to `true` — after your storefront has collected the shopper's consent — the gateway returns a reusable token, which Commerce Layer turns into the payment wallet the subscription then renews on. Vaulting is never enabled automatically.
{% endhint %}

## Instrument-pending subscriptions

A subscription generated from a checkout whose payment session [asked for vaulting](/core-api-reference/2026-05/payment_sessions.md#vaulting-during-a-charge) is born without a payment instrument: the instrument is vaulted moments later, and for a vaultable gateway a linked payment wallet is the only thing that can pay a run. The same holds when the session didn't ask for vaulting at all, until a wallet is created for the customer. Such a subscription starts in `pending`, and — since runs only walk active subscriptions — nothing would look at it again.

When a payment wallet reaches `succeeded` status, it offers itself to that customer's pending subscriptions and activates the ones it can pay for. Candidates are matched through the source order they were created from, which must carry a payment session on the same payment setting as the wallet. This applies to every wallet, however it was created, and runs in the background shortly after it succeeds. An expired wallet is never offered.

{% hint style="info" %}
Only subscriptions created within the last **30 days**, and which resolved neither a payment wallet nor a payment setting of their own, are considered — so saving a new card doesn't revive a subscription abandoned months ago. Anything outside that window is still recoverable manually, by associating a payment wallet and sending the `_activate` trigger attribute.
{% endhint %}

<details>

<summary>How-to</summary>

Check the related [guide](/how-tos/placing-orders/subscriptions.md) to learn more about how to generate automatic subscriptions from a source order.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.commercelayer.io/core-api-reference/2026-05/order_subscriptions.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.