Recurring Orders overview

Ask about this Page
Copy for AI
View as Markdown

Overview of the concepts related to Recurring Orders and the checkout process.

A Recurring Order defines the schedule and configuration for automatically creating and placing future Orders at regular, predefined intervals on behalf of a customer. It acts as the base for generating new Orders according to the specified recurrence schedule.
Learn more about using Recurring Orders for B2B replenishment in our self-paced Implement B2B purchase flows module.

General concepts

Recurrence Policies

A Recurrence Policy lets you define a schedule for selling recurring products at specific prices. The recurring order can occur on a specific day of every month, or at fixed intervals. You define Recurrence Policies on individual Line Items and Custom Line Items as well as individual prices (both Standalone and Embedded).

A Project can have multiple Recurrence Policies at the same time and they can be reused across different Recurring Orders.

A Recurrence Policy can also define minDaysBetweenOrders to limit how soon after the last Order an early Order can be requested. It does not change the schedule.

You have two options for choosing a schedule:

Standard schedules

Within each standard schedule, you define the intervalUnit, for example Days, Weeks, or Months, and also the value field, which represents the number of intervals between orders.
Order frequencyValueInterval unit
Daily1Days
Weekly1Weeks
Monthly1Months
Every 10 days10Days
Every 2 weeks2Weeks
Every 3 months3Months

Day of month schedules

To schedule a Recurring Order on a specific day of the month, you can use the DayOfMonthSchedule.

Recurring items

Line Items and Custom Line Items carry information about possible recurrence. For each recurring item, you define when or how often the item should be ordered, as well as the pricing mode using a Recurrence Policy.

Define a schedule or interval

To set the schedule or interval:

Define a price selection mode

A Recurring Order can span several months, resulting in the generation of multiple scheduled orders over time. When selling a product over an extended period, it's common for its price to change—sometimes more than once.

To define how price updates affect existing Recurring Orders, you define the PriceSelectionMode through the recurrenceInfo field on each recurring item. The price selection mode determines whether Recurring Orders should retain the original item price or adopt the new price going forward.

You can choose one of the following price selection modes:

  • Fixed: the price set at the time the Recurring Order was created remains the same. With this configuration, any changes made to the Product's price will not affect existing Recurring Orders.
  • Dynamic: each time a new order is generated from a Recurring Order, the platform retrieves and applies the current Product price. With this configuration, any updates to a Product's price will affect all existing Recurring Orders going forward.

Prices

Prices (both Embedded and Standalone) carry information about possible recurrence. Each price that is defined on a recurring item must be connected to a Recurrence Policy.

When selecting a price for a Recurring Order, the platform will use the standard price selection rules, along with the specified Recurrence Policy, to determine the correct price for the given SKU and recurrence. If no such price is found, the platform defaults to using the standard one-time purchase price.

For example, for a Recurring Order using an SKU with a monthly recurrence, the platform will attempt to locate a price explicitly tied to that monthly policy.

You only need to set recurrence information on prices if you intend to offer special pricing for recurring items; otherwise, no changes to your existing pricing configuration are needed.

For example, to sell yogurt in 3 different intervals, you set a price for each interval:

If you are using Standalone Prices, create a new price via the Create StandalonePrice endpoint, and set the desired Recurrence Policy in the StandalonePriceDraft object.
If you are using Embedded Prices, add a new price via the Add Price update action, and set the desired Recurrence Policy in the PriceDraft object.

If you are using external pricing, you can set the price for the individual Line Item or Custom Line Item on the Cart, when creating or updating the Cart.

Recurring Carts

A Cart with the CartOrigin RecurringOrder is known as a recurring Cart and is used as the source to create all subsequent orders generated by a specific Recurring Order. A recurring Cart contains only Line Items and Custom Line Items that are linked to a Recurrence Policy.
Recurring Carts are not deleted by the automatic cleanup, even if no changes occur within a 90-day period.
To learn how recurring Carts are created, see Initial creation.

Recurring Orders

Initial creation

To create a Recurring Order, you can use the following methods:

MethodDescriptionUse case
Create Order from Cart (Orders API)Automatically checks Line Items and Custom Line Items for recurrence information, and if found, creates a Recurring Order for each recurrence schedule that is found.Use when the Cart contains a mix of one-time and recurring purchases, or recurring items with different schedules.
Create RecurringOrder (RecurringOrders API)Requires a Cart where all Line Items and Custom Line Items are recurring and share the same recurrence schedule. You can also set the startsAt, expiresAt, and custom fields.Use when all items in the Cart are linked to the same recurrence schedule and you need additional flexibility to set when the Recurring Order starts or stops, or to store custom information.

Method A: Create Order from Cart

The following steps describe the process when using the Create Order from Cart endpoint on the Orders API:
  1. On the OrderFromCartDraft, you specify the cart that contains items.
  2. An Order is created from the specified Cart.
  3. The platform evaluates the Line Items and Custom Line Items:
    1. If no recurrence information is found, no further action is taken.
    2. If one or more items contain recurrence information:
      • Recurring items are grouped by their recurrence schedule (specified in the Recurrence Policies).
      • For each group, a new Recurring Order and a new recurring Cart are created.
      • Each recurring Cart inherits the base configuration of the original Cart (for example, tax mode, customer group, inventory mode, store, business unit) but contains only the items that belong to that group.
      • If multiple shipping methods are used, only the shipping methods and addresses associated with the items in the group are copied to the new Cart.

Example

A customer wants to buy four different products (SKUs). Their Cart has the following items:

ItemPurchase intervalShip to
SKU1One-time purchaseHome
SKU2WeeklyHome
SKU3MonthlyOffice
SKU4MonthlyOffice

The customer completes the checkout process and receives an email with the confirmation.

Internally, the following steps happen:

  • A new Order is created with all four items.
  • The platform determines that three of the four items are recurring and groups them by their recurrence interval:
    • Group A: SKU2 (weekly)
    • Group B: SKU3 and SKU4 (monthly)
  • For each group, a new Recurring Order and a new recurring Cart are created.
  • The new recurring Carts inherit the base configuration of the original Cart.

This results in the following:

  • Recurring Order A: SKU2 is shipped weekly to the home address.
  • Recurring Order B: SKU3 and SKU4 are shipped monthly to the office address.
Each Recurring Order holds a link to the recurring Cart that contains the items which share the same schedule.

Method B: Create RecurringOrder

The following steps describe the process when using the Create RecurringOrder endpoint on the Recurring Orders API:
  1. On the RecurringOrderDraft, you specify the cart that contains the recurring items.
  2. A new Recurring Order is created.
  3. The origin field on the specified Cart changes to RecurringOrder.

Subsequent Orders

Once a Recurring Order is created, the platform automatically creates new Orders based on the defined schedule. Each Recurring Order contains the following information:

  • cart: the recurring Cart for this Recurring Order. It serves as a blueprint for generating future orders.
  • nextOrderAt: the date and time when the next order will be created.
  • originOrder: the original Order from which this Recurring Order was initiated. This field is only populated when the Recurring Order is created via the Create Order from Cart endpoint.
  • startsAt: date and time when this Recurring Order becomes active and eligible to generate new Orders.
  • schedule: The defined interval that determines how often new orders are generated for this Recurring Order.

Delays can occur due to application or server-side processing.

The following example shows when the next orders are created for a Recurring Order configured with a weekly interval.

DateStatusOrder creatednextOrderAt
1 Jul 2025Active✓8 Jul 2025
8 Jul 2025Active✓15 Jul 2025
15 Jul 2025Active✓22 Jul 2025
22 Jul 2025Active✓29 Jul 2025
29 Jul 2025.........
For every new Order, commercetools executes all related API Extensions and generates the OrderCreatedFromRecurringOrder Message. Orders generated by a Recurring Order schedule do not emit the standard OrderCreated Message; the OrderCreated Message is emitted only for the initial Order created directly from a Cart.

Paused Recurring Orders

You can pause a Recurring Order at any time. When paused, subsequent Orders will not be created until the Recurring Order is reactivated.

The following example shows when the next orders are created for a Recurring Order configured with a weekly interval that has been paused and then reactivated.

DateStatusOrder CreatednextOrderAt
1 Jul 2025Active✓8 Jul 2025
6 Jul 2025Paused by the user✗empty
19 Jul 2025Reactivated by the user✗22 Jul 2025
22 Jul 2025Active✓29 Jul 2025
29 Jul 2025Active......

Failed Recurring Orders

Errors prevent subsequent Orders from being created and cause the Recurring Order's state to change to Failed. The RecurringOrderFailed Message always reports the cause in its failureReason field and can include additional details in its optional errors field.
Recurring Orders do not retry automatically. A Recurring Order stays in the Failed state, and generates no Orders, until you resolve the issue and set it back to Active using the Set RecurringOrder State update action.

Order now

You can create the next Order of a Recurring Order immediately instead of waiting for nextOrderAt. To do so, send the Request Order Now update action on the Recurring Order. The request is rejected if the Recurring Order is not eligible, for example, if it is paused or the minimum gap between Orders has not passed. For all conditions, see RecurringOrderRequestOrderNowAction.

The early Order consumes the upcoming occurrence. It is not an additional Order, and it does not move the schedule to the date of the request. The customer receives the same number of Orders over time, and only the timing of one Order changes.

The following example shows a Recurring Order configured with a monthly interval on the first day of the month. An early Order is requested on 20 October 2025, while nextOrderAt is 1 November 2025.
DateEventOrder creatednextOrderAt
1 Oct 2025Scheduled Order✓1 Nov 2025
20 Oct 2025Early Order (the November Order)✓1 Dec 2025
1 Dec 2025Scheduled Order✓1 Jan 2026

How it works

  1. You send the requestOrderNow update action. The API responds with 200 and the updated Recurring Order. The response still shows the original nextOrderAt because the request is recorded, but the Order does not exist yet.
  2. The RecurringOrderNowRequested Message is generated.
  3. The Order is created asynchronously through the regular Recurring Order process. The platform selects prices again for Dynamic Line Items, handles inventory according to the inventory mode, and runs API Extensions. If payment runs through Checkout, the platform requests the payment first and creates the Order after the payment succeeds. The OrderCreatedFromRecurringOrder Message is generated.
  4. Only then does the Recurring Order update. lastOrderAt is set to the actual creation date, and nextOrderAt advances by one interval from the consumed occurrence.
After an early Order, lastOrderAt is the earlier, actual creation date, while nextOrderAt is derived from the consumed occurrence and not from lastOrderAt.

The request is always asynchronous, with no synchronous variant.

  • Pricing: depends on the priceSelectionMode of each Line Item. With Dynamic pricing, prices are selected again at creation time, so an early Order uses the price valid on the day it is created. Fixed prices are not affected.
  • Inventory: depends on the InventoryMode of the Line Item or, if not set, of the Cart. With ReserveOnOrder, insufficient stock causes the Order to fail unless restockableInDays is set on the Inventory Entry. With TrackOnly, the Order is created even if the available quantity is zero or negative, but fails if no matching Inventory Entry exists. With None, no inventory checks are made.
  • Payment: the platform requests a payment only if payment runs through Checkout. Otherwise, it creates the Order without initiating a payment, and any financial transaction is handled by your external PSP integration.
  • Failure: the occurrence is not consumed and nextOrderAt remains unchanged. The Recurring Order changes to the Failed state. To recover, first resolve the underlying cause, such as missing inventory or a configuration problem, then set the state to Active.

Limit early orders

To space out early Orders, set minDaysBetweenOrders on the Recurrence Policy using the RecurrencePolicyDraft or the Set Min Days Between Orders update action. A request is rejected if fewer than this number of days have passed since lastOrderAt of the Recurring Order. The time is measured in multiples of 24 hours, not calendar days, and counts Orders created on schedule or early.
minDaysBetweenOrders does not affect the schedule. A weekly Recurrence Policy with minDaysBetweenOrders set to 30 still creates an Order every week. It also is not a quota: it sets a minimum gap, not a maximum number of early Orders per period.

Recurrence Policies are shared. The limit applies to every Recurring Order that uses the Recurrence Policy, and changes take effect immediately. If you do not set the field, there is no limit. Existing Recurrence Policies and Recurring Orders are not affected.

No customer-facing /me endpoint or Merchant Center UI exists for this feature. A storefront can offer early Orders only by calling the API through your own backend.

Payments BETA

By default, a subsequent Order is created as soon as it is due, and collecting payment for it is your responsibility afterwards. Alternatively, you can have payment collected by commercetools Checkout before the Order is created, so that a subsequent Order only exists if its payment succeeded.
You configure this on the recurring Cart, in the RecurringPaymentConfiguration field. The configuration is only evaluated on Carts with the RecurringOrder CartOrigin.
The recurring payment configuration on Carts and the integration of Recurring Orders with Checkout are in public beta.

Payment strategies

The PaymentStrategy determines when and by whom payment is collected.
BehaviorNo RecurringPaymentConfigurationCheckout PaymentStrategy
When the Order is createdImmediately when dueOnly after the payment succeeds
Who collects paymentYou, after the Order existscommercetools Checkout, before the Order exists
If the payment failsThe Order already existsNo Order is created, and the Recurring Order transitions to Failed
InventoryHandled according to the Cart's InventoryMode when the Order is createdReserved before payment for the TrackOnly and ReserveOnOrder InventoryModes, and released if the payment fails

Payment allocations

Each RecurringPaymentAllocation assigns a share of the Order total to one PaymentMethod. The share is either a RelativeAllocation, expressed as a percentage, or an AbsoluteAllocation, expressed as an amount. All allocations in a configuration must be of the same type.
Checkout doesn't support split payments for Recurring Orders. With the Checkout PaymentStrategy, configure a single allocation that covers 100% of the Order total with one Payment Method, so the same Payment Method can be charged for future Orders. For Payment Connector requirements and other constraints, see the Checkout documentation.

Use the following update actions on the recurring Cart to manage the configuration:

Update actionUse to
Set RecurringPaymentStrategySet the paymentStrategy without changing the existing allocations. If no configuration exists, one is created without allocations.
Set RecurringPaymentConfigurationSet the paymentStrategy and the allocations together, replacing any existing configuration.
Add RecurringPaymentAllocationAdd a single allocation to an existing configuration.
Remove RecurringPaymentAllocationRemove a single allocation by its id.

Checkout payment flow

When a subsequent Order is due on a Recurring Order whose recurring Cart uses the Checkout PaymentStrategy, the following steps happen:
  1. A snapshot of the recurring Cart is created and frozen with the HardFreeze FreezeStrategy, so that its total cannot change while the payment is in progress.
  2. Inventory is reserved for Line Items that use the TrackOnly or ReserveOnOrder InventoryMode. Other inventory modes aren't reserved in this step.
  3. commercetools asks Checkout to charge the Payment Methods in paymentAllocations.
  4. Checkout processes the payment and reports the result. This step is asynchronous and does not complete within a single API call.
  5. If the payment succeeds, the Order is created and the inventory reservation is committed. If the payment fails, the reservation is released and the Recurring Order transitions to the Failed RecurringOrderState.
Because step 4 is asynchronous, there is a delay between the time an Order is due and the time it exists. Do not build integrations that assume an Order exists immediately after nextOrderAt; subscribe to the OrderCreatedFromRecurringOrder Message instead.
The Cart snapshot created in step 1 is a regular Cart in your Project with the RecurringOrder CartOrigin. It is deleted after the Order is created, or after the payment fails. If the payment succeeds but the Order cannot be created, the Cart copy is kept so that the refund remains traceable. Do not modify these Carts.

Payment failures

With the Checkout PaymentStrategy, a Recurring Order transitions to Failed in the following cases:
  • The payment fails. Resolve the cause, which is usually a Payment Method that must be updated, before setting the Recurring Order back to Active.
  • The payment succeeds but the Order cannot be created. This most often happens when an API Extension rejects the Order creation. commercetools releases the inventory reservation and asks Checkout to refund the payment.

Because a rejection after payment triggers a refund, run validations that can be performed on the Cart as API Extensions on the Cart rather than on Order creation.

Further resources

For a complete walkthrough on how to setup and create a Recurring Order, see our Create a Recurring Order tutorial.