Recurring Orders

Automate the reordering process for frequently purchased products.

Recurring Orders automates the reordering process for a Customer. You can define the Cart containing the products to be ordered, the reorder frequency, and the start and end dates. Once configured, orders are placed automatically for the Customer at the scheduled interval. Recurring Orders can be modified, paused, or canceled to accommodate changes in demand.

Representations

RecurringOrder

id​
String​

Unique identifier of the RecurringOrder.

version​
Int​

Current version of the RecurringOrder.

key​
String​

User-defined unique identifier of the RecurringOrder.

MinLength: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
cart​
Reference to the Cart for a RecurringOrder. The referenced Cart will have the RecurringOrder CartOrigin.
originOrder​
Reference to the original Order that generated this RecurringOrder.
startsAt​
DateTime​

Date and time (UTC) when the RecurringOrder starts creating new Orders.

resumesAt​
DateTime​

Date and time (UTC) when the RecurringOrder resumes creating Orders after being unpaused.

expiresAt​
DateTime​

Date and time (UTC) when the RecurringOrder expires.

lastOrderAt​
DateTime​

Date and time (UTC) when the last Order was created from this RecurringOrder.

nextOrderAt​
DateTime​

Date and time (UTC) when the next Order will be created from this RecurringOrder.

skipConfiguration​

Information about current and future skips for this RecurringOrder.

store​
Reference to a Store.
businessUnit​
Reference to the Business Unit that the RecurringOrder belongs to.
state​
State of the RecurringOrder. This reference can point to a State in a custom workflow.
recurringOrderState​

Current state of the RecurringOrder.

schedule​

Schedule of the RecurringOrder.

customer​
The Customer that the RecurringOrder belongs to.
customerEmail​
String​

Email address of the Customer that the RecurringOrder belongs to.

custom​
CustomFields​

Custom Fields of the RecurringOrder.

createdAt​
DateTime​

Date and time (UTC) when the RecurringOrder was created.

createdBy​BETA
CreatedBy​

IDs and references that created the RecurringOrder.

lastModifiedAt​
DateTime​

Date and time (UTC) when the RecurringOrder was last updated.

lastModifiedBy​BETA

IDs and references that last modified the RecurringOrder.

RecurringOrderDraft

Recurring Orders are automatically assigned the Store and/or Business Unit from the associated Cart.

key​
String​
User-defined unique identifier of the RecurringOrder.
MinLength: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
cart​
ResourceIdentifier to the Cart from which the RecurringOrder is created.
cartVersion​
Int​
Current version of the referenced Cart.
startsAt​
DateTime​

Date and time (UTC) when the RecurringOrder will start.

state​

State for the RecurringOrder in a custom workflow.

custom​

Custom Fields to be added to the RecurringOrder.

RecurringOrderPagedQueryResponse

PagedQueryResult with results containing an array of RecurringOrder.
limit​
Int​
Default: 20​Minimum: 0​Maximum: 500​
offset​
Int​
Number of elements skipped.
Default: 0​Minimum: 0​Maximum: 10000​
count​
Int​

Actual number of results returned.

total​
Int​
Total number of results matching the query. This number is an estimation that is not strongly consistent. This field is returned by default. For improved performance, calculating this field can be deactivated by using the query parameter withTotal=false. When the results are filtered with a Query Predicate, total is subject to a limit.
results​
Array of RecurringOrder​
RecurringOrders matching the query.

RecurringOrderReference

id​
String​
Unique identifier of the referenced RecurringOrder.
typeId​
recurring-order

Type of referenced resource.

obj​
Contains the representation of the expanded RecurringOrder. Only present in responses to requests with Reference Expansion for RecurringOrders.

RecurringOrderResourceIdentifier

ResourceIdentifier to a RecurringOrder. Either id or key is required. If both are set, an InvalidJsonInput error is returned.
id​
String​
Unique identifier of the referenced RecurringOrder. Required if key is absent.
key​
String​
User-defined unique identifier of the referenced RecurringOrder. Required if id is absent.
typeId​
recurring-order
Type of referenced resource. If given, it must match the expected ReferenceTypeId of the referenced resource.

RecurringOrderState

Indicates the state of the RecurringOrder.
Active

The default state of a new RecurringOrder.

Paused

Indicates that the RecurringOrder is paused.

Expired

Indicates that the RecurringOrder is expired.

Canceled

Indicates that the RecurringOrder is canceled.

RecurringOrderStateDraft

Defines the new state for the Recurring Order. For possible values, see RecurringOrderActive, RecurringOrderPaused, RecurringOrderExpired, and RecurringOrderCanceled.
type​
String​

RecurringOrderActive

Changes the Recurring Order state to active.

type​
String​
"active"
resumesAt​
DateTime​

If set, the Recurring Order will automatically resume at the date and time (UTC) specified.

RecurringOrderPaused

Changes the Recurring Order state to paused.

type​
String​
"paused"

RecurringOrderExpired

Changes the Recurring Order state to expired.

type​
String​
"expired"

RecurringOrderCanceled

Changes the Recurring Order state to canceled.

type​
String​
"canceled"
reason​
String​

The reason for the cancelation.

SkipConfiguration

Defines how the next orders are going to be skipped.

Counter

Configuration to track skips for a RecurringOrder.
type​
String​
"counter"
totalToSkip​
Int​

Number of Orders that are going to be skipped.

skipped​
Int​

Amount of Orders that were already skipped.

lastSkippedAt​
DateTime​

Date and time (UTC) when the last Order creation was skipped.

CounterDraft

Configuration that uses a counter to track the number of Orders that will be skipped.

type​
String​
"counter"
totalToSkip​
Int​

Number of Orders that are going to be skipped.

PriceSelectionMode

Indicates how the price of a Line Item or Custom Line Item is selected during Order creation.
Fixed
The price set when the Recurring Order was created is used for each subsequent order.
Dynamic

The price is updated each time a new Order is created.

Get RecurringOrder

Get RecurringOrder by ID

GET
https://api.{region}.commercetools.com/{projectKey}/recurring-orders/{id}
Retrieves a Recurring Order with the provided id.
OAuth 2.0 Scopes:
view_recurring_orders:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
id
​
String
​
id of the RecurringOrder.
Query parameters:
expand
​​
The parameter can be passed multiple times.
Response:
200

RecurringOrder

asapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/recurring-orders/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 
200 Response Example: RecurringOrderjson
{
  "id": "42c72ffb-d1e6-4eb2-b05f-17d227f8422d",
  "version": 1,
  "createdAt": "2025-01-06T20:09:33.751Z",
  "lastModifiedAt": "2025-01-06T20:09:33.751Z",
  "cart": {
    "typeId": "cart",
    "id": "d688de05-dc0a-43de-91dc-94ab30f21c1e"
  },
  "originOrder": {
    "typeId": "order",
    "id": "68c20103-fc7b-430f-8f00-094c312b19e6"
  },
  "businessUnit": {
    "typeId": "business-unit",
    "key": "bu-key"
  },
  "startsAt": "2025-01-02T20:09:33.644Z",
  "lastOrderAt": "2025-01-06T16:00:25.657Z",
  "nextOrderAt": "2025-01-07T20:09:33.644Z",
  "recurringOrderState": "Active",
  "schedule": {
    "type": "standard",
    "value": 1,
    "intervalUnit": "Days"
  }
}

Get RecurringOrder by Key

GET
https://api.{region}.commercetools.com/{projectKey}/recurring-orders/key={key}
Retrieves a Recurring Order with the provided key.
OAuth 2.0 Scopes:
view_recurring_orders:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
key
​
String
​
key of the RecurringOrder.
Query parameters:
expand
​​
The parameter can be passed multiple times.
Response:
200

RecurringOrder

asapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/recurring-orders/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 
200 Response Example: RecurringOrderjson
{
  "id": "42c72ffb-d1e6-4eb2-b05f-17d227f8422d",
  "version": 1,
  "createdAt": "2025-01-06T20:09:33.751Z",
  "lastModifiedAt": "2025-01-06T20:09:33.751Z",
  "cart": {
    "typeId": "cart",
    "id": "d688de05-dc0a-43de-91dc-94ab30f21c1e"
  },
  "originOrder": {
    "typeId": "order",
    "id": "68c20103-fc7b-430f-8f00-094c312b19e6"
  },
  "businessUnit": {
    "typeId": "business-unit",
    "key": "bu-key"
  },
  "startsAt": "2025-01-02T20:09:33.644Z",
  "lastOrderAt": "2025-01-06T16:00:25.657Z",
  "nextOrderAt": "2025-01-07T20:09:33.644Z",
  "recurringOrderState": "Active",
  "schedule": {
    "type": "standard",
    "value": 1,
    "intervalUnit": "Days"
  }
}

Query RecurringOrders

GET
https://api.{region}.commercetools.com/{projectKey}/recurring-orders
Retrieves Recurring Orders in the Project.
OAuth 2.0 Scopes:
view_recurring_orders:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
Query parameters:
where
​​
The parameter can be passed multiple times.
sort
​​
The parameter can be passed multiple times.
expand
​​
The parameter can be passed multiple times.
limit
​
Int
​
Default: 20​
Minimum: 0​
Maximum: 500​
offset
​
Int
​
Number of elements skipped.
Default: 0​
Maximum: 10000​
withTotal
​
Boolean
​
Controls the calculation of the total number of query results. Set to false to improve query performance when the total is not needed.
Default: true​
var.<varName>
​
String
​
The parameter can be passed multiple times.
Response:
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/recurring-orders -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 
200 Response Example: RecurringOrderPagedQueryResponsejson
{
  "limit": 20,
  "offset": 0,
  "count": 1,
  "total": 1,
  "results": [
    {
      "id": "42c72ffb-d1e6-4eb2-b05f-17d227f8422d",
      "version": 1,
      "createdAt": "2025-01-06T20:09:33.751Z",
      "lastModifiedAt": "2025-01-06T20:09:33.751Z",
      "cart": {
        "typeId": "cart",
        "id": "d688de05-dc0a-43de-91dc-94ab30f21c1e"
      },
      "originOrder": {
        "typeId": "order",
        "id": "68c20103-fc7b-430f-8f00-094c312b19e6"
      },
      "businessUnit": {
        "typeId": "business-unit",
        "key": "bu-key"
      },
      "startsAt": "2025-01-02T20:09:33.644Z",
      "lastOrderAt": "2025-01-06T16:00:25.657Z",
      "nextOrderAt": "2025-01-07T20:09:33.644Z",
      "recurringOrderState": "Active",
      "schedule": {
        "type": "standard",
        "value": 1,
        "intervalUnit": "Days"
      }
    }
  ]
}

Check if RecurringOrder exists

Check if RecurringOrder exists by ID

HEAD
https://api.{region}.commercetools.com/{projectKey}/recurring-orders/{id}
Checks if a Recurring Order exists with the provided id. Returns a 200 OK status if the Recurring Order exists, or a NotFound error otherwise.
OAuth 2.0 Scopes:
view_recurring_orders:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
id
​
String
​
id of the RecurringOrder.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/recurring-orders/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 

Check if RecurringOrder exists by Key

HEAD
https://api.{region}.commercetools.com/{projectKey}/recurring-orders/key={key}
Checks if a Recurring Order exists with the provided key. Returns a 200 OK status if the Recurring Order exists, or a NotFound error otherwise.
OAuth 2.0 Scopes:
view_recurring_orders:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
key
​
String
​
key of the RecurringOrder.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/recurring-orders/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 

Check if RecurringOrder exists by Query Predicate

HEAD
https://api.{region}.commercetools.com/{projectKey}/recurring-orders
Checks if one or more Recurring Orders exist for the provided query predicate. Returns a 200 OK status if any Recurring Orders match the query predicate, or a NotFound error otherwise.
OAuth 2.0 Scopes:
view_recurring_orders:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
Query parameters:
where
​​
The parameter can be passed multiple times.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/recurring-orders -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 

Create RecurringOrder

POST
https://api.{region}.commercetools.com/{projectKey}/recurring-orders
Creates a Recurring Order in the Project. The Cart is validated to ensure that it is convertible to an Order. If validation fails, an error is returned.
Produces the RecurringOrderCreated message.

If a server-side problem occurs, indicated by a 500 Internal Server Error HTTP response, the Recurring Order creation may still successfully complete after the error is returned. If you receive this error, you should verify the status of the Recurring Order by querying a unique identifier supplied during the creation request, such as the key.

OAuth 2.0 Scopes:
manage_recurring_orders:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
Query parameters:
expand
​​
The parameter can be passed multiple times.
Request Body:RecurringOrderDraftasapplication/json
Response:
201

RecurringOrder

asapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/recurring-orders -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "cart" : {
    "id" : "7c2e2694-aefe-43d7-888e-6a99514caaca",
    "typeId" : "cart"
  },
  "cartVersion" : 10,
  "startsAt" : "2017-01-04T19:54:49.797Z"
}
DATA
201 Response Example: RecurringOrderjson
{
  "id": "42c72ffb-d1e6-4eb2-b05f-17d227f8422d",
  "version": 1,
  "createdAt": "2025-01-06T20:09:33.751Z",
  "lastModifiedAt": "2025-01-06T20:09:33.751Z",
  "cart": {
    "typeId": "cart",
    "id": "d688de05-dc0a-43de-91dc-94ab30f21c1e"
  },
  "originOrder": {
    "typeId": "order",
    "id": "68c20103-fc7b-430f-8f00-094c312b19e6"
  },
  "businessUnit": {
    "typeId": "business-unit",
    "key": "bu-key"
  },
  "startsAt": "2025-01-02T20:09:33.644Z",
  "lastOrderAt": "2025-01-06T16:00:25.657Z",
  "nextOrderAt": "2025-01-07T20:09:33.644Z",
  "recurringOrderState": "Active",
  "schedule": {
    "type": "standard",
    "value": 1,
    "intervalUnit": "Days"
  }
}

Update RecurringOrder

Update RecurringOrder by ID

POST
https://api.{region}.commercetools.com/{projectKey}/recurring-orders/{id}
Updates a Recurring Order using one or more update actions.
OAuth 2.0 Scopes:
manage_recurring_orders:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
id
​
String
​
id of the RecurringOrder.
Query parameters:
expand
​​
The parameter can be passed multiple times.
Request Body:
application/json
version​
Int​
Expected version of the RecurringOrder on which the changes should be applied. If the expected version does not match the actual version, a ConcurrentModification error will be returned.
actions​

Update actions to be performed on the RecurringOrder.

Response:
200

RecurringOrder

asapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/recurring-orders/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "version" : 1,
  "actions" : [ {
    "action" : "setKey",
    "key" : "new-key"
  } ]
}
DATA
200 Response Example: RecurringOrderjson
{
  "id": "42c72ffb-d1e6-4eb2-b05f-17d227f8422d",
  "version": 1,
  "createdAt": "2025-01-06T20:09:33.751Z",
  "lastModifiedAt": "2025-01-06T20:09:33.751Z",
  "cart": {
    "typeId": "cart",
    "id": "d688de05-dc0a-43de-91dc-94ab30f21c1e"
  },
  "originOrder": {
    "typeId": "order",
    "id": "68c20103-fc7b-430f-8f00-094c312b19e6"
  },
  "businessUnit": {
    "typeId": "business-unit",
    "key": "bu-key"
  },
  "startsAt": "2025-01-02T20:09:33.644Z",
  "lastOrderAt": "2025-01-06T16:00:25.657Z",
  "nextOrderAt": "2025-01-07T20:09:33.644Z",
  "recurringOrderState": "Active",
  "schedule": {
    "type": "standard",
    "value": 1,
    "intervalUnit": "Days"
  }
}

Update RecurringOrder by Key

POST
https://api.{region}.commercetools.com/{projectKey}/recurring-orders/key={key}
Updates a Recurring Order using one or more update actions.
OAuth 2.0 Scopes:
manage_recurring_orders:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
key
​
String
​
key of the RecurringOrder.
Query parameters:
expand
​​
The parameter can be passed multiple times.
Request Body:
application/json
version​
Int​
Expected version of the RecurringOrder on which the changes should be applied. If the expected version does not match the actual version, a ConcurrentModification error will be returned.
actions​

Update actions to be performed on the RecurringOrder.

Response:
200

RecurringOrder

asapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/recurring-orders/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "version" : 1,
  "actions" : [ {
    "action" : "setKey",
    "key" : "new-key"
  } ]
}
DATA
200 Response Example: RecurringOrderjson
{
  "id": "42c72ffb-d1e6-4eb2-b05f-17d227f8422d",
  "version": 1,
  "createdAt": "2025-01-06T20:09:33.751Z",
  "lastModifiedAt": "2025-01-06T20:09:33.751Z",
  "cart": {
    "typeId": "cart",
    "id": "d688de05-dc0a-43de-91dc-94ab30f21c1e"
  },
  "originOrder": {
    "typeId": "order",
    "id": "68c20103-fc7b-430f-8f00-094c312b19e6"
  },
  "businessUnit": {
    "typeId": "business-unit",
    "key": "bu-key"
  },
  "startsAt": "2025-01-02T20:09:33.644Z",
  "lastOrderAt": "2025-01-06T16:00:25.657Z",
  "nextOrderAt": "2025-01-07T20:09:33.644Z",
  "recurringOrderState": "Active",
  "schedule": {
    "type": "standard",
    "value": 1,
    "intervalUnit": "Days"
  }
}

Update actions

Set Key

action​
String​
"setKey"
key​
String​

Value to set. If empty, any existing key will be removed.

MinLength: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
Example: json
{
  "action": "setKey",
  "key": "new-key"
}

Transition State

If the existing State has set transitions, there must be a direct transition to the new State. If transitions is not set, no validation is performed.
action​
String​
"transitionState"
state​

Value to set. If there is no State yet, the new State must be an initial State.

force​
Boolean​
Set to true to turn off validation.
Default: false​
Example: json
{
  "action": "transitionState",
  "state": {
    "typeId": "state",
    "id": "{{state-id}}"
  }
}

Set RecurringOrderState

Setting the RecurringOrderState generates the RecurringOrderStateSet Message.
action​
String​
"setRecurringOrderState"
recurringOrderState​

New state of the RecurringOrder.

Example: json
{
  "action": "setRecurringOrderState",
  "recurringOrderState": {
    "type": "active"
  }
}

Set CustomField

action​
String​
"setCustomField"
name​
String​
Name of the Custom Field.
value​
If value is absent or null, this field will be removed if it exists. Removing a field that does not exist returns an InvalidOperation error. If value is provided, it is set for the field defined by name.
Example: json
{
  "action": "setCustomField",
  "name": "ExampleStringTypeField",
  "value": "TextString"
}

Set Custom Type

action​
String​
"setCustomType"
type​
Defines the Type that extends the RecurringOrder with Custom Fields. If absent, any existing Type and Custom Fields are removed from the RecurringOrder.
fields​
Sets the Custom Fields fields for the RecurringOrder.
Example: json
{
  "action": "setCustomType",
  "type": {
    "id": "{{type-id}}",
    "typeId": "type"
  },
  "fields": {
    "exampleStringField": "TextString"
  }
}

Set Skip Configuration

action​
String​
"setOrderSkipConfiguration"
skipConfiguration​
SkipConfigurationDraft​
Configuration for skipping the next orders of the Recurring Order.
updatedExpiresAt​
DateTime​

Date and time (UTC) the Recurring Order will resume and start to generate new orders.

Example: json
{
  "action": "setOrderSkipConfiguration",
  "skipConfiguration": {
    "type": "counter",
    "totalToSkip": 3
  },
  "updatedExpiresAt": "2025-10-15T15:00:00.000Z"
}

Set Starts At

To set the start date and time, the Recurring Order must not have been started yet. Setting the start date and time generates the RecurringOrderStartsAtSet Message.
action​
String​
"setStartsAt"
startsAt​
DateTime​
Date and time (UTC) the Recurring Order should be started. The date and time must be in the future.
Example: json
{
  "action": "setStartsAt",
  "startsAt": "2025-10-15T15:00:00.000Z"
}

Set Schedule

To set the schedule, the Recurring Order must be active, with no active Skip Configuration and with available prices for all Cart items for the new schedule. Setting the schedule generates the RecurringOrderScheduleSet Message.
action​
String​
"setSchedule"
recurrencePolicy​

Value to set.

Example: json
{
  "action": "setSchedule",
  "recurrencePolicy": {
    "typeId": "recurrence-policy",
    "id": "{{recurrence-policy-id}}"
  }
}