Documentation

Recurring Orders overview

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.

General concepts

Recurrence Policies

A Recurrence Policy carries information about a specific schedule (for example, weekly, monthly, or on a specific date each month). You define Recurrence Policies on individual Line Items and Custom Line Items as well as individual prices (both Standalone and Embedded). You can reuse a Recurrence Policy across multiple prices.

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 pricing

For each recurring item, you define the pricing mode to use:

  • Fixed price: the price set at the time the Recurring Order was created remains the same. If an SKU's price changes, the Recurring Order continues to use the original price.
  • Dynamic price: each time a new order is generated, the latest price for the item is used.
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. 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.
Recurring Orders do not support a fallback mechanism for price selection. If a matching price cannot be found for the specified SKU and Recurrence Policy, the corresponding Line Item will not be added to the Cart.

Price configuration

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.

For example, to sell yogurt in 3 different intervals, a price must exist 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.

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 use the same 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 CartAutomatically 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 RecurringOrderRequires a Cart where all Line Items and Custom Line Items are recurring and share the same recurrence schedule.Use when all items in the Cart share the same recurrence schedule.

Platform behavior

The following steps describe the process when using the Create Order from Cart endpoint:
  1. An Order is created from the provided Cart.
  2. 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 Order (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.

Subsequent Orders

Once a Recurring Order is created, the platform automatically creates new Orders based on the defined schedule. Each Recurring Order contains a nextOrderAt field that specifies the date and time when the next order will be created.
In most cases, Orders are created around the same time as the nextOrderAt date and time. In some cases, it may take up to 48 hours.

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.........

Paused 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......

Example

A customer wants to buy 4 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, Composable Commerce performs the following steps:

  • 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 Order.

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.
Every new Order will execute all related API Extensions, and generate Messages.