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.

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.

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.