Recurring Orders APIs overview

Ask about this Page
Copy for AI
View as Markdown

How to work with the APIs for Recurring Orders.

This page describes rules that apply across the Recurring Orders APIs. For what Recurring Orders and Recurrence Policies are and how they behave, see the Recurring Orders overview.

APIs in this topic

ResourcePurposeReference
Recurrence PoliciesDefine a reusable schedule for selling recurring products at specific prices.Recurrence Policies
Recurring OrdersAutomate the reordering process for frequently purchased products.Recurring Orders

Data model

Recurrence Policies

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

Define a schedule or interval

To set the schedule or interval:

Define a price selection mode

To define how price updates affect existing Recurring Orders, you define the PriceSelectionMode (Fixed or Dynamic) through the recurrenceInfo field on each recurring item.

Prices

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.
Recurring Carts are not deleted by the automatic cleanup, even if no changes occur within a 90-day period.

Working with the APIs

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.
For the steps that each method performs, see Create Order from Cart and Create RecurringOrder.
For a complete walkthrough on how to setup and create a Recurring Order, see our Create a Recurring Order tutorial.

Subsequent Orders

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.

Order now

To create the next Order of a Recurring Order immediately, send the Request Order Now update action on the Recurring Order. For all eligibility conditions, see RecurringOrderRequestOrderNowAction.

How it works

  1. You send the requestOrderNow update action. The response still shows the original nextOrderAt because the request is recorded, but the Order does not exist yet. For the REST response, see Request Order Now.
  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

You configure how payment is collected on the recurring Cart, in the RecurringPaymentConfiguration field. The configuration is only evaluated on Carts with the RecurringOrder CartOrigin.

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.

Messages and events

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.
The RecurringOrderFailed Message always reports the cause in its failureReason field and can include additional details in its optional errors field.