How to work with the APIs for Recurring Orders.
APIs in this topic
| Resource | Purpose | Reference |
|---|---|---|
| Recurrence Policies | Define a reusable schedule for selling recurring products at specific prices. | Recurrence Policies |
| Recurring Orders | Automate the reordering process for frequently purchased products. | Recurring Orders |
Data model
Recurrence Policies
Standard schedules
intervalUnit, for example Days, Weeks, or Months, and also the value field, which represents the number of intervals between orders.| Order frequency | Value | Interval unit |
|---|---|---|
| Daily | 1 | Days |
| Weekly | 1 | Weeks |
| Monthly | 1 | Months |
| Every 10 days | 10 | Days |
| Every 2 weeks | 2 | Weeks |
| Every 3 months | 3 | Months |
Day of month schedules
Recurring items
Define a schedule or interval
To set the schedule or interval:
-
Create (or add) a Line Item or Custom Line Item with the
RecurrenceInfofield set:- For Line Items
- For Custom Line Items
-
Update a Line Item or Custom Line Item with the
RecurrenceInfofield set:- For Line Items
- For Custom Line Items
Define a price selection mode
Fixed or Dynamic) through the recurrenceInfo field on each recurring item.Prices
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
Working with the APIs
Initial creation
To create a Recurring Order, you can use the following methods:
| Method | Description | Use 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. |
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
How it works
- You send the
requestOrderNowupdate action. The response still shows the originalnextOrderAtbecause the request is recorded, but the Order does not exist yet. For the REST response, see Request Order Now. - The RecurringOrderNowRequested Message is generated.
- The Order is created asynchronously through the regular Recurring Order process. The platform selects prices again for
DynamicLine 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. - Only then does the Recurring Order update.
lastOrderAtis set to the actual creation date, andnextOrderAtadvances by one interval from the consumed occurrence.
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
priceSelectionModeof each Line Item. WithDynamicpricing, prices are selected again at creation time, so an early Order uses the price valid on the day it is created.Fixedprices 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 unlessrestockableInDaysis set on the Inventory Entry. WithTrackOnly, the Order is created even if the available quantity is zero or negative, but fails if no matching Inventory Entry exists. WithNone, 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
nextOrderAtremains unchanged. The Recurring Order changes to theFailedstate. To recover, first resolve the underlying cause, such as missing inventory or a configuration problem, then set the state toActive.
Limit early orders
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.
/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
RecurringOrder CartOrigin.Payment strategies
| Behavior | No RecurringPaymentConfiguration | Checkout PaymentStrategy |
|---|---|---|
| When the Order is created | Immediately when due | Only after the payment succeeds |
| Who collects payment | You, after the Order exists | commercetools Checkout, before the Order exists |
| If the payment fails | The Order already exists | No Order is created, and the Recurring Order transitions to Failed |
| Inventory | Handled according to the Cart's InventoryMode when the Order is created | Reserved before payment for the TrackOnly and ReserveOnOrder InventoryModes, and released if the payment fails |
Payment allocations
percentage, or an AbsoluteAllocation, expressed as an amount. All allocations in a configuration must be of the same type.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 action | Use to |
|---|---|
| Set RecurringPaymentStrategy | Set the paymentStrategy without changing the existing allocations. If no configuration exists, one is created without allocations. |
| Set RecurringPaymentConfiguration | Set the paymentStrategy and the allocations together, replacing any existing configuration. |
| Add RecurringPaymentAllocation | Add a single allocation to an existing configuration. |
| Remove RecurringPaymentAllocation | Remove a single allocation by its id. |
Checkout payment flow
Checkout PaymentStrategy, the following steps happen:- A snapshot of the recurring Cart is created and frozen with the
HardFreezeFreezeStrategy, so that its total cannot change while the payment is in progress. - Inventory is reserved for Line Items that use the
TrackOnlyorReserveOnOrderInventoryMode. Other inventory modes aren't reserved in this step. - commercetools asks Checkout to charge the Payment Methods in
paymentAllocations. - Checkout processes the payment and reports the result. This step is asynchronous and does not complete within a single API call.
- 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
FailedRecurringOrderState.
nextOrderAt; subscribe to the OrderCreatedFromRecurringOrder Message instead.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
- 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
OrderCreated Message is emitted only for the initial Order created directly from a Cart.failureReason field and can include additional details in its optional errors field.