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

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. You can also set the startsAt, expiresAt, custom fields.Use when all items in the Cart share the same recurrence schedule and/or you need flexibility to define when the Recurring Order starts, stops, and to store custom information.

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 the following information:

  • cart: the Cart created specifically 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.
  • 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.
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.

Further resources

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