This is the documentation preview for Recurring Orders, a feature that is currently in early access. This documentation might not be in sync with our official documentation.

Recurrence Policies

A Recurrence Policy is a configuration of a schedule used to sell a product at a specific price. It can be reused across multiple prices.

Representations

RecurrencePolicy

RecurrencePolicyDraft

RecurrencePolicyPagedQueryResponse

RecurrencePolicyReference

RecurrencePolicyResourceIdentifier

RecurrencePolicySchedule -StandardSchedule -StandardScheduleDraft

IntervalUnit

RecurrencePolicy

`id` String	Unique identifier of the RecurrencePolicy.
`version` Int	Current version of the RecurrencePolicy.
`key` String	User-defined unique identifier of the RecurrencePolicy.
`name` LocalizedString	Name of the RecurrencePolicy.
`description` LocalizedString	Description of the RecurrencePolicy.
`schedule` RecurrencePolicySchedule	Schedule of the RecurrencePolicy.
`createdAt` DateTime	Date and time (UTC) the RecurrencePolicy was initially created.
`createdBy`BETA CreatedBy	IDs and references that created the RecurrencePolicy.
`lastModifiedAt` DateTime	Date and time (UTC) the RecurrencePolicy was last updated.
`lastModifiedBy`BETA LastModifiedBy	IDs and references that last modified the RecurrencePolicy.

RecurrencePolicyDraft

`key` String	User-defined unique identifier for the RecurrencePolicy.
`name` LocalizedString	Name of the RecurrencePolicy.
`description` LocalizedString	Description of the RecurrencePolicy.
`schedule` RecurrencePolicySchedule	Schedule where the recurrence is defined.

RecurrencePolicyPagedQueryResponse

PagedQueryResult with results containing an array of RecurrencePolicy.

`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 RecurrencePolicy	RecurrencePolicies matching the query.

RecurrencePolicyReference

Reference to a RecurrencePolicy.

`id` String	Unique identifier of the referenced RecurrencePolicy.
`typeId` ReferenceTypeId	`recurrence-policy` Type of referenced resource.
`obj` RecurrencePolicy	Contains the representation of the expanded RecurrencePolicy. Only present in responses to requests with Reference Expansion for RecurrencePolicy.

RecurrencePolicyResourceIdentifier

ResourceIdentifier to a RecurrencePolicy. Either id or key is required. If both are set, an InvalidJsonInput error is returned.

`id` String	Unique identifier of the referenced RecurrencePolicy. Required if `key` is absent.
`key` String	User-defined unique identifier of the referenced RecurrencePolicy. Required if `id` is absent.
`typeId` ReferenceTypeId	`recurrence-policy` Type of referenced resource. If given, it must match the expected ReferenceTypeId of the referenced resource.

RecurrencePolicySchedule

The schedule used for a recurrence policy.

StandardSchedule

Schedule where the recurring order is defined. For example: 1 month, 2 weeks.

`type` String	`"standard"`
`value` Int	Number of schedule types between orders.
`intervalUnit` IntervalUnit	The interval used for this schedule.

StandardScheduleDraft

Sets the schedule for a recurrence policy.

`type` String	`"standard"`
`value` Int	Number of schedule types between orders.
`intervalUnit` IntervalUnit	Interval used for this schedule.

IntervalUnit

The intervals supported for schedules.

Days: Use to set daily schedule.
Weeks: Use to set weekly schedule.
Months: Use to set monthly schedule.

Get RecurrencePolicy

Get RecurrencePolicy by ID

GET

https://api.{region}.commercetools.com/{projectKey}/recurrence-policies/{id}

Retrieves a Recurrence Policy 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 RecurrencePolicy.

Query parameters:

expand

Expansion

The parameter can be passed multiple times.

Response:

200

RecurrencePolicy

asapplication/json

Request Example:cURL

curl --get https://api.{region}.commercetools.com/{projectKey}/recurrence-policies/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

200 Response Example: RecurrencePolicyjson

{
  "id": "4be2bea9-bf21-4987-9114-d1339bcebf3d",
  "version": 1,
  "createdAt": "2024-12-11T15:13:42.183Z",
  "lastModifiedAt": "2024-12-11T15:13:42.183Z",
  "key": "daily",
  "name": {
    "en": "daily"
  },
  "schedule": {
    "type": "standard",
    "value": 1,
    "intervalUnit": "Days"
  }
}

Query RecurrencePolicies

GET

https://api.{region}.commercetools.com/{projectKey}/recurrence-policies

Retrieves Recurrence Policies 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

RecurrencePolicyPagedQueryResponse

asapplication/json

Request Example:cURL

curl --get https://api.{region}.commercetools.com/{projectKey}/recurrence-policies -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

200 Response Example: RecurrencePolicyPagedQueryResponsejson

{
  "limit": 20,
  "offset": 0,
  "count": 1,
  "total": 1,
  "results": [
    {
      "id": "4be2bea9-bf21-4987-9114-d1339bcebf3d",
      "version": 1,
      "versionModifiedAt": "2024-12-11T15:13:42.183Z",
      "createdAt": "2024-12-11T15:13:42.183Z",
      "lastModifiedAt": "2024-12-11T15:13:42.183Z",
      "key": "daily",
      "name": {
        "en": "daily"
      },
      "schedule": {
        "type": "standard",
        "value": 1,
        "intervalUnit": "Days"
      }
    }
  ]
}

Check if RecurrencePolicy exists

Check if RecurrencePolicy exists by ID

HEAD

https://api.{region}.commercetools.com/{projectKey}/recurrence-policies/{id}

Checks if a Recurrence Policy exists with the provided id. Returns a 200 OK status if the Recurrence Policy 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 RecurrencePolicy.

Response:

200

Request Example:cURL

curl --head https://api.{region}.commercetools.com/{projectKey}/recurrence-policies/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Check if RecurrencePolicy exists by Query Predicate

HEAD

https://api.{region}.commercetools.com/{projectKey}/recurrence-policies

Checks if one or more Recurrence Policies exist for the provided query predicate. Returns a 200 OK status if any Recurrence Policies 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

QueryPredicate

The parameter can be passed multiple times.

Response:

200

Request Example:cURL

curl --head https://api.{region}.commercetools.com/{projectKey}/recurrence-policies -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Create RecurrencePolicy

POST

https://api.{region}.commercetools.com/{projectKey}/recurrence-policies

Creates a Recurrence Policy 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.

Query parameters:

expand

Expansion

The parameter can be passed multiple times.

Request Body:RecurrencePolicyDraftasapplication/json

Response:

201

RecurrencePolicy

asapplication/json

Request Example:cURL

curl https://api.{region}.commercetools.com/{projectKey}/recurrence-policies -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "key" : "daily",
  "name" : {
    "en" : "daily"
  },
  "schedule" : {
    "type" : "standard",
    "value" : 1,
    "intervalUnit" : "Days"
  }
}
DATA

201 Response Example: RecurrencePolicyjson

{
  "id": "4be2bea9-bf21-4987-9114-d1339bcebf3d",
  "version": 1,
  "createdAt": "2024-12-11T15:13:42.183Z",
  "lastModifiedAt": "2024-12-11T15:13:42.183Z",
  "key": "daily",
  "name": {
    "en": "daily"
  },
  "schedule": {
    "type": "standard",
    "value": 1,
    "intervalUnit": "Days"
  }
}

Update RecurrencePolicy

Update RecurrencePolicy by ID

POST

https://api.{region}.commercetools.com/{projectKey}/recurrence-policies/{id}

Updates a Recurrence Policy 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 RecurrencePolicy.

Query parameters:

expand

Expansion

The parameter can be passed multiple times.

Request Body:

application/json

`version` Int	Expected version of the RecurrencePolicy 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 RecurrencePolicyUpdateAction	Update actions to be performed on the RecurrencePolicy.

Response:

200

RecurrencePolicy

asapplication/json

Request Example:cURL

curl https://api.{region}.commercetools.com/{projectKey}/recurrence-policies/{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: RecurrencePolicyjson

{
  "id": "4be2bea9-bf21-4987-9114-d1339bcebf3d",
  "version": 1,
  "createdAt": "2024-12-11T15:13:42.183Z",
  "lastModifiedAt": "2024-12-11T15:13:42.183Z",
  "key": "daily",
  "name": {
    "en": "daily"
  },
  "schedule": {
    "type": "standard",
    "value": 1,
    "intervalUnit": "Days"
  }
}

Update actions

Set Key

Set Name

Set Description

Set Key

`action` String	`"setKey"`
`key` String	Value to set. If empty, any existing value will be removed. MinLength: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`

Example: json

{
  "action": "setKey",
  "key": "new-key"
}

Set Name

`action` String	`"setName"`
`name` LocalizedString	Value to set. If empty, any existing value will be removed.

Example: json

{
  "action": "setName",
  "name": {
    "en": "New name",
    "de": "Neuer Name"
  }
}

Set Description

`action` String	`"setDescription"`
`description` LocalizedString	Value to set. If empty, any existing value will be removed.

Example: json

{
  "action": "setDescription",
  "description": {
    "en": "New description"
  }
}

Recurrence Policies

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

RecurrencePolicy.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;}

RecurrencePolicyDraft.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;}

RecurrencePolicyPagedQueryResponse.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;}

RecurrencePolicyReference.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;}

RecurrencePolicyResourceIdentifier.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;}

RecurrencePolicySchedule.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;}

StandardSchedule.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;}

StandardScheduleDraft.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;}

IntervalUnit.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 RecurrencePolicy.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 RecurrencePolicy 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;}

Query RecurrencePolicies.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 RecurrencePolicy 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 RecurrencePolicy 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 RecurrencePolicy 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 RecurrencePolicy.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 RecurrencePolicy.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 RecurrencePolicy 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 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;}

Set Name.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 Description.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

RecurrencePolicy

RecurrencePolicyDraft

RecurrencePolicyPagedQueryResponse

RecurrencePolicyReference

RecurrencePolicyResourceIdentifier

RecurrencePolicySchedule

StandardSchedule

StandardScheduleDraft

IntervalUnit

Get RecurrencePolicy

Get RecurrencePolicy by ID

Query RecurrencePolicies

Check if RecurrencePolicy exists

Check if RecurrencePolicy exists by ID

Check if RecurrencePolicy exists by Query Predicate

Create RecurrencePolicy

Update RecurrencePolicy

Update RecurrencePolicy by ID

Update actions

Set Key

Set Name

Set Description