Recurring Orders

Automate the reordering process for frequently purchased products.

Recurring Orders automate 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

RecurringOrderDraft

RecurringOrderPagedQueryResponse

RecurringOrderReference

RecurringOrderResourceIdentifier

RecurringOrderState

RecurringOrderStateDraft -RecurringOrderActive -RecurringOrderPaused -RecurringOrderExpired -RecurringOrderCanceled

SkipConfiguration -Counter -SkipConfigurationDraft -CounterDraft

PriceSelectionMode

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` CartReference	Reference to the Cart for a RecurringOrder. The referenced Cart will have the `RecurringOrder` CartOrigin.
`originOrder` OrderReference	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` SkipConfiguration	Information about current and future skips for this RecurringOrder.
`store` StoreKeyReference	Reference to a Store.
`businessUnit` BusinessUnitKeyReference	Reference to the Business Unit that the RecurringOrder belongs to.
`state` StateReference	State of the RecurringOrder in a custom workflow.
`recurringOrderState` RecurringOrderState	Current state of the RecurringOrder.
`schedule` RecurrencePolicySchedule	Schedule of the RecurringOrder.
`customer` CustomerReference	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 LastModifiedBy	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` CartResourceIdentifier	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. When specified, the date and time must be in the future. If not specified, the recurring order will start immediately.
`expiresAt` DateTime	Date and time (UTC) when the RecurringOrder will expire.
`state` StateResourceIdentifier	State for the RecurringOrder in a custom workflow.
`custom` CustomFieldsDraft	Custom Fields for the RecurringOrder.

RecurringOrderPagedQueryResponse

PagedQueryResult with results containing an array of RecurringOrder.

`limit` Int	Number of results requested. 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

Reference to a RecurringOrder.

`id` String	Unique identifier of the referenced RecurringOrder.
`typeId` ReferenceTypeId	`recurring-order` Type of referenced resource.
`obj` RecurringOrder	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` ReferenceTypeId	`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 has expired.
Canceled: Indicates that the RecurringOrder is canceled.
Failed: Indicates that the process of creating new orders has failed. The field failure stores the error encountered (inventory unavailable, etc). New orders will not be created until the issue is fixed.

RecurringOrderStateDraft

Defines the new state for the Recurring Order—for possible values, see RecurringOrderActive, RecurringOrderPaused, RecurringOrderExpired, and RecurringOrderCanceled.

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

Generic type that shows how future orders will be skipped.

Supported data types:

Counter

Counter

Configuration to track skips for a RecurringOrder.

`type` String	`"Counter"`
`totalToSkip` Int	Number of Orders that will be skipped.
`skipped` Int	Number of Orders that were already skipped.
`lastSkippedAt` DateTime	Date and time (UTC) when the last Order creation was skipped.

SkipConfigurationDraft

Generic type used to define how future orders will be skipped. Use with CounterDraft.

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

Expansion

The parameter can be passed multiple times.

Response:

200

RecurringOrder

application/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

Expansion

The parameter can be passed multiple times.

Response:

200

RecurringOrder

application/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` QueryPredicate	The parameter can be passed multiple times.
`sort` Sort	The parameter can be passed multiple times.
`expand` Expansion	The parameter can be passed multiple times.
`limit` Int	Number of results requested. 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	Predicate parameter values. The parameter can be passed multiple times.

Response:

200

RecurringOrderPagedQueryResponse

application/json

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

QueryPredicate

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. Produces the RecurringOrderCreated message.

The Cart is validated to ensure that it is convertible to an Order. If the validation fails, an error is returned. If the expiration date has been reached when the Recurring Order is processed, its RecurringOrderState will be updated to Expired, and no Order will be created.

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

Expansion

The parameter can be passed multiple times.

Request Body:RecurringOrderDraftasapplication/json

Response:

201

RecurringOrder

application/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.

A Recurring Order can only be updated when it is not processing an Order. Otherwise, an InvalidOperation error is returned.

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

Expansion

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` Array of RecurringOrderUpdateAction	Update actions to be performed on the RecurringOrder.

Response:

200

RecurringOrder

application/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.

A Recurring Order can only be updated when it is not processing an Order. Otherwise, an InvalidOperation error is returned.

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

Expansion

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` Array of RecurringOrderUpdateAction	Update actions to be performed on the RecurringOrder.

Response:

200

RecurringOrder

application/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

Transition State

Set RecurringOrderState

Set Order Skip Configuration

Set Key

This update action generates the RecurringOrderKeySet Message.

`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.

This update action produces the Recurring Order State Transition Message.

`action` String	`"transitionState"`
`state` StateResourceIdentifier	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 RecurringOrderStateChanged Message.

`action` String	`"setRecurringOrderState"`
`recurringOrderState` RecurringOrderStateDraft	New state of the RecurringOrder.

Example: json

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

Set Order Skip Configuration

`action` String	`"setOrderSkipConfiguration"`
`skipConfigurationInputDraft` SkipConfigurationDraft	Configuration for skipping future orders of the Recurring Order.
`updatedExpiresAt` DateTime	Date and time (UTC) the Recurring Order will expire and stop generating new orders.

Example: json

{
  "action": "setOrderSkipConfiguration",
  "skipConfigurationInputDraft": {
    "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 Expires At

Setting the expiration date and time generates the RecurringOrderExpiresAtSet Message.

`action` String	`"setExpiresAt"`
`expiresAt` DateTime	Date and time (UTC) the Recurring Order should expire. If empty, any existing value will be removed. If the date or time is extended or removed when the RecurringOrderState is `Expired`, the state will be updated to `Active`.

Example: json

{
  "action": "setExpiresAt",
  "expiresAt": "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` RecurrencePolicyResourceIdentifier	Value to set.

Example: json

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

Set Custom Type

Adding or updating a Custom Type on a Recurring Order generates the RecurringOrderCustomTypeSet Message, removing one generates the RecurringOrderCustomTypeRemoved Message.

`action` String	`"setCustomType"`
`type` TypeResourceIdentifier	Defines the Type that extends the RecurringOrder with Custom Fields. If absent, any existing Type and Custom Fields are removed from the RecurringOrder.
`fields` FieldContainer	Sets the Custom Fields fields for the RecurringOrder.

Example: json

{
  "action": "setCustomType",
  "type": {
    "id": "{{type-id}}",
    "typeId": "type"
  },
  "fields": {
    "exampleStringField": "TextString"
  }
}

Set CustomField

Adding a Custom Field to a Recurring Order generates the RecurringOrderCustomFieldAdded Message, removing one generates the RecurringOrderCustomFieldRemoved Message, and updating an existing one generates the RecurringOrderCustomFieldChanged Message.

`action` String	`"setCustomField"`
`name` String	Name of the Custom Field.
`value` CustomFieldValue	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"
}

Delete RecurringOrder

Only Recurring Orders with recurringOrderState of Expired or Canceled can be deleted.

Delete RecurringOrder by ID

DELETE

https://api.{region}.commercetools.com/{projectKey}/recurring-orders/{id}

Deletes a Recurring Order in the Project.

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:

`version` Int	Last seen version of the resource.
`expand` Expansion	The parameter can be passed multiple times.
`dataErasure` Boolean	To erase all related personal data in compliance with GDPR, set to `true`. Default: `false`

Response:

200

RecurringOrder

application/json

Request Example:cURL

curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/recurring-orders/{id}?version={version} -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"
  }
}

Delete RecurringOrder by Key

DELETE

https://api.{region}.commercetools.com/{projectKey}/recurring-orders/key={key}

Deletes a Recurring Order in the Project.

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:

`version` Int	Last seen version of the resource.
`expand` Expansion	The parameter can be passed multiple times.
`dataErasure` Boolean	To erase all related personal data in compliance with GDPR, set to `true`. Default: `false`

Response:

200

RecurringOrder

application/json

Request Example:cURL

curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/recurring-orders/key={key}?version={version} -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"
  }
}

Recurring Orders

Representations.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

RecurringOrder.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

RecurringOrderDraft.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

RecurringOrderPagedQueryResponse.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

RecurringOrderReference.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

RecurringOrderResourceIdentifier.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

RecurringOrderState.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

RecurringOrderStateDraft.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

RecurringOrderActive.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

RecurringOrderPaused.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

RecurringOrderExpired.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

RecurringOrderCanceled.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

SkipConfiguration.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Counter.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

SkipConfigurationDraft.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

CounterDraft.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

PriceSelectionMode.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Get RecurringOrder.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Get RecurringOrder by ID.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Get RecurringOrder by Key.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Query RecurringOrders.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Check if RecurringOrder exists.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Check if RecurringOrder exists by ID.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Check if RecurringOrder exists by Key.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Check if RecurringOrder exists by Query Predicate.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Create RecurringOrder.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Update RecurringOrder.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Update RecurringOrder by ID.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Update RecurringOrder by Key.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Update actions.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Set Key.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Transition State.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Set RecurringOrderState.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Set Order Skip Configuration.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Set Starts At.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Set Expires At.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Set Schedule.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Set Custom Type.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Set CustomField.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Delete RecurringOrder.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Delete RecurringOrder by ID.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Delete RecurringOrder by Key.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Representations

RecurringOrder

RecurringOrderDraft

RecurringOrderPagedQueryResponse

RecurringOrderReference

RecurringOrderResourceIdentifier

RecurringOrderState

RecurringOrderStateDraft

RecurringOrderActive

RecurringOrderPaused

RecurringOrderExpired

RecurringOrderCanceled

SkipConfiguration

Counter

SkipConfigurationDraft

CounterDraft

PriceSelectionMode

Get RecurringOrder

Get RecurringOrder by ID

Get RecurringOrder by Key

Query RecurringOrders

Check if RecurringOrder exists

Check if RecurringOrder exists by ID

Check if RecurringOrder exists by Key

Check if RecurringOrder exists by Query Predicate

Create RecurringOrder

Update RecurringOrder

Update RecurringOrder by ID

Update RecurringOrder by Key

Update actions

Set Key

Transition State

Set RecurringOrderState

Set Order Skip Configuration

Set Starts At

Set Expires At

Set Schedule

Set Custom Type

Set CustomField

Delete RecurringOrder

Delete RecurringOrder by ID

Delete RecurringOrder by Key