# Recurring Orders APIs overview

**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](/api/recurring-orders-overview.md).

## APIs in this topic

| Resource | Purpose | Reference |
| --- | --- | --- |
| Recurrence Policies | Define a reusable schedule for selling recurring products at specific prices. | [Recurrence Policies](/api/projects/recurrence-policies.md) |
| Recurring Orders | Automate the reordering process for frequently purchased products. | [Recurring Orders](/api/projects/recurring-orders.md) |

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

To schedule a Recurring Order on a specific day of the month, you can use the [DayOfMonthSchedule](/search.md?urn=ctp:api:type:DayOfMonthSchedule).

### 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 `RecurrenceInfo` field set:
  - For [Line Items](/api/projects/carts.md#lineitemrecurrenceinfodraft)
  - For [Custom Line Items](/api/projects/carts.md#customlineitemrecurrenceinfodraft)

- Update a Line Item or Custom Line Item with the `RecurrenceInfo` field set:
  - For [Line Items](/api/projects/carts.md#set-lineitemrecurrenceinfo)
  - For [Custom Line Items](/api/projects/carts.md#set-customlineitemrecurrenceinfo)

#### Define a price selection mode

To define how price updates affect existing Recurring Orders, you define the [PriceSelectionMode](/search.md?urn=ctp:api:type: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](/search.md?urn=ctp:api:endpoint:/{projectKey}/standalone-prices:POST) endpoint, and set the desired [Recurrence Policy](/api/projects/recurrence-policies.md#recurrencepolicy) in the [StandalonePriceDraft](/search.md?urn=ctp:api:type:StandalonePriceDraft) object.

If you are using Embedded Prices, add a new price via the [Add Price](/api/projects/products.md#add-price) update action, and set the desired [Recurrence Policy](/api/projects/recurrence-policies.md#recurrencepolicy) in the [PriceDraft](/api/types.md#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](/search.md?urn=ctp:api:type:Cart) with the [CartOrigin](/search.md?urn=ctp:api:type:CartOrigin) `RecurringOrder` is known as a recurring Cart.

> Recurring Carts are not deleted by the [automatic cleanup](/api/general-concepts.md#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:

| Method | Description | Use case |
| --- | --- | --- |
| [Create Order from Cart](/search.md?urn=ctp:api:endpoint:/{projectKey}/orders:POST) (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](/search.md?urn=ctp:api:endpoint:/{projectKey}/recurring-orders:POST) (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](/api/projects/orders.md#create-order-from-cart) and [Create RecurringOrder](/api/projects/recurring-orders.md#create-recurringorder).

For a complete walkthrough on how to setup and create a Recurring Order, see our [Create a Recurring Order](/guides/create-a-recurring-order.md) 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](/search.md?urn=ctp:api:endpoint:/{projectKey}/orders:POST) 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](/api/projects/recurring-orders.md#request-order-now) update action on the Recurring Order. For all eligibility conditions, see [RecurringOrderRequestOrderNowAction](/search.md?urn=ctp:api:type: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](/api/projects/recurring-orders.md#request-order-now).
2. The [RecurringOrderNowRequested](/api/projects/messages/cart-order-messages.md#recurring-order-now-requested) 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](/api/projects/api-extensions.md). If payment runs through [Checkout](/checkout/overview.md), the platform requests the payment first and creates the Order after the payment succeeds. The [OrderCreatedFromRecurringOrder](/api/projects/messages/cart-order-messages.md#order-created-from-recurring-order) 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](/search.md?urn=ctp:api:type: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](/checkout/overview.md). Otherwise, it creates the Order without initiating a payment, and any financial transaction is handled by your [external PSP integration](/api/projects/payments.md).
- **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`](/search.md?urn=ctp:api:type:RecurringOrderSetStateAction).

#### Limit early orders

To space out early Orders, set `minDaysBetweenOrders` on the Recurrence Policy using the [RecurrencePolicyDraft](/search.md?urn=ctp:api:type:RecurrencePolicyDraft) or the [Set Min Days Between Orders](/api/projects/recurrence-policies.md#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&#x20;

You configure how payment is collected on the recurring Cart, in the [RecurringPaymentConfiguration](/search.md?urn=ctp:api:type:RecurringPaymentConfiguration) field. The configuration is only evaluated on Carts with the `RecurringOrder` [CartOrigin](/search.md?urn=ctp:api:type:CartOrigin).

#### Payment strategies

The [PaymentStrategy](/search.md?urn=ctp:api:type:PaymentStrategy) determines when and by whom payment is collected.

| Behavior | No [RecurringPaymentConfiguration](/search.md?urn=ctp:api:type:RecurringPaymentConfiguration) | `Checkout` [PaymentStrategy](/search.md?urn=ctp:api:type: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`](/api/recurring-orders-overview.md#failed-recurring-orders) |
| Inventory | Handled according to the Cart's [InventoryMode](/search.md?urn=ctp:api:type:InventoryMode) when the Order is created | Reserved before payment for the `TrackOnly` and `ReserveOnOrder` [InventoryModes](/search.md?urn=ctp:api:type:InventoryMode), and released if the payment fails |

#### Payment allocations

Each [RecurringPaymentAllocation](/search.md?urn=ctp:api:type:RecurringPaymentAllocation) assigns a share of the Order total to one [PaymentMethod](/search.md?urn=ctp:api:type:PaymentMethod). The share is either a [RelativeAllocation](/search.md?urn=ctp:api:type:RelativeAllocation), expressed as a `percentage`, or an [AbsoluteAllocation](/search.md?urn=ctp:api:type: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](/search.md?urn=ctp:api:type: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](/checkout/) documentation.

Use the following update actions on the recurring Cart to manage the configuration:

| Update action | Use to |
| --- | --- |
| [Set RecurringPaymentStrategy](/search.md?urn=ctp:api:type:CartSetRecurringPaymentStrategyAction) | Set the `paymentStrategy` without changing the existing allocations. If no configuration exists, one is created without allocations. |
| [Set RecurringPaymentConfiguration](/search.md?urn=ctp:api:type:CartSetRecurringPaymentConfigurationAction) | Set the `paymentStrategy` and the allocations together, replacing any existing configuration. |
| [Add RecurringPaymentAllocation](/search.md?urn=ctp:api:type:CartAddRecurringPaymentAllocationAction) | Add a single allocation to an existing configuration. |
| [Remove RecurringPaymentAllocation](/search.md?urn=ctp:api:type:CartRemoveRecurringPaymentAllocationAction) | Remove 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](/search.md?urn=ctp:api:type: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](/search.md?urn=ctp:api:type: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`](/api/recurring-orders-overview.md#failed-recurring-orders) [RecurringOrderState](/search.md?urn=ctp:api:type: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](/search.md?urn=ctp:api:type:OrderCreatedFromRecurringOrderMessage) Message instead.

> The Cart snapshot created in step 1 is a regular Cart in your Project with the `RecurringOrder` [CartOrigin](/search.md?urn=ctp:api:type: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](/search.md?urn=ctp:api:type:PaymentStrategy), a Recurring Order transitions to [`Failed`](/api/recurring-orders-overview.md#failed-recurring-orders) 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](/api/projects/api-extensions.md) 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](/api/projects/api-extensions.md) and generates the [OrderCreatedFromRecurringOrder](/search.md?urn=ctp:api:type:OrderCreatedFromRecurringOrderMessage) Message. Orders generated by a Recurring Order schedule do not emit the standard [OrderCreated](/search.md?urn=ctp:api:type:OrderCreatedMessage) Message; the `OrderCreated` Message is emitted only for the initial Order created directly from a Cart.

The [RecurringOrderFailed](/search.md?urn=ctp:api:type:RecurringOrderFailedMessage) Message always reports the cause in its `failureReason` field and can include additional details in its optional `errors` field.

## Related pages

- [Area overview page with navigation](/api.md)
- [Previous page: Overview](/api/recurring-orders-overview.md)
- [Next page: Recurrence Policies](/api/projects/recurrence-policies.md)
- [Search documentation and API specs](/search.md)