Recurring Orders

Elevate, May 20-22-2025, Miami Beach, Florida

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.

MinLength2MaxLength256Pattern^[A-Za-z0-9_-]+$
cart
Reference to the Cart for a RecurringOrder. The referenced Cart will have the RecurringOrder CartOrigin.
originOrder
Reference to the Order that generated this RecurringOrder.
startsAt
DateTime

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

resumesAt
DateTime

Date and time (UTC) the RecurringOrder resumes subsequent order creation after it is unpaused.

expiresAt
DateTime

Date and time (UTC) 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 of this RecurringOrder.

businessUnit
Reference to a Business Unit 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

Custom Fields of the RecurringOrder.

createdAt
DateTime

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

createdByBETA

IDs and references that created the RecurringOrder.

lastModifiedAt
DateTime

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

lastModifiedByBETA

IDs and references that last modified the RecurringOrder.

RecurringOrderDraft

key
String

User-defined unique identifier of the RecurringOrder.

MinLength2MaxLength256Pattern^[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) 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
Default20Minimum0Maximum500
offset
Int
Number of elements skipped.
Default0Minimum0Maximum10000
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.

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.

SkipConfiguration

Defines how the next orders are going to be skipped.

Counter

Configuration that uses a counter to track the amount of orders that will be skipped.

type
String
"counter"
totalToSkip
Int

Amount 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 amount of orders that will be skipped.

type
String
"counter"
totalToSkip
Int

Amount of orders that are going to be skipped.

PriceSelectionMode

Indicates how the price of a line item will be selected during order creation.

Fixed

The price set when the Recurring Order was created will be used for each subsequent order.

Dynamic

The price will be 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"
  }
}

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 exist with the provided id. Returns a 200 OK status if the Recurring Order exists, or a ResourceNotFound 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 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 ResourceNotFound 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. Before you create a Recurring Order, the Cart is validated to ensure that it is convertible to an Order. If validation fails, an error is returned.

If a server-side problem occurs, indicated by a 500 Internal Server Error HTTP response, the RecurringOrder creation may still successfully complete after the error is returned. If you receive this error, you should verify the status of the RecurringOrder 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 actions

Set Key

action
String
"setKey"
key
String

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

MinLength2MaxLength256Pattern^[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.
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": "Paused"
}

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

TODO.

updatedExpiresAt
DateTime

Date and time (UTC) the RecurringOrder TODO.

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