Recurrence Policies

A Recurrence Policy is a reusable configuration that defines a schedule for selling recurring products at specific prices.

Representations

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

Name of the RecurrencePolicy.

description

Description of the RecurrencePolicy.

schedule

Schedule of the RecurrencePolicy.

createdAt
DateTime

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

createdByBETA

IDs and references that created the RecurrencePolicy.

lastModifiedAt
DateTime

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

lastModifiedByBETA

IDs and references that last modified the RecurrencePolicy.

RecurrencePolicyDraft

key
String
User-defined unique identifier for the RecurrencePolicy.
name

Name of the RecurrencePolicy.

description

Description of the RecurrencePolicy.

schedule

Schedule where the recurrence is defined.

RecurrencePolicyPagedQueryResponse

PagedQueryResult with results containing an array of RecurrencePolicy.
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 RecurrencePolicy
RecurrencePolicies matching the query.

RecurrencePolicyReference

id
String
Unique identifier of the referenced RecurrencePolicy.
typeId
recurrence-policy

Type of referenced resource.

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
recurrence-policy
Type of referenced resource. If given, it must match the expected ReferenceTypeId of the referenced resource.

RecurrencePolicySchedule

The schedule for a Recurrence Policy.

StandardSchedule

Schedule for a RecurringOrder that occurs at a fixed interval. For example: every two weeks or every month.
type
String
"standard"
value
Int

Number of intervals between orders.

intervalUnit

The interval used for this schedule.

StandardScheduleDraft

Sets the schedule for a Recurring Order to occur at a fixed interval. For example: every two weeks or every month.
type
String
"standard"
value
Int

Number of intervals between orders.

intervalUnit

Interval used for this schedule.

DayOfMonthSchedule

Schedule for a Recurring Order that occurs on a specific day of each month. This type is returned in the RecurrencePolicy for an active Recurring Order.
type
String
"dayOfMonth"
day
Int
The day of the month on which the Recurring Order is created. If this value is greater than the number of days in a given month, the order is created on the last day of the month.
Minimum1Maximum31

DayOfMonthScheduleDraft

Sets the schedule for a Recurring Order to occur on a specific day of each month.
  • Orders will be created even if the specified day is a weekend or holiday.
  • To place orders on different dates within the same month (for example, the 1st and 15th), you must create separate Recurring Orders, each with its own schedule.
type
String
"dayOfMonth"
day
Int
Specify the day of the month (1-31) when the Recurring Order should be created. If this value is greater than the number of days in a given month, the order will be created on the last day of the month.
Minimum1Maximum31

IntervalUnit

Supported interval units for Recurrence Policies which are used in Recurring Orders.
Days

Use to set a daily schedule.

Weeks

Use to set a weekly schedule.

Months

Use to set a 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
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"
  }
}

Get RecurrencePolicy by Key

GET
https://api.{region}.commercetools.com/{projectKey}/recurrence-policies/key={key}
Retrieves a Recurrence Policy 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 RecurrencePolicy.
Query parameters:
expand
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/key={key} -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
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}/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 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 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 Key

HEAD
https://api.{region}.commercetools.com/{projectKey}/recurrence-policies/key={key}
Checks if a Recurrence Policy exists with the provided key. Returns a 200 OK status if the Recurrence Policy 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 RecurrencePolicy.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/recurrence-policies/key={key} -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 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}/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
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
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

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 RecurrencePolicy by Key

POST
https://api.{region}.commercetools.com/{projectKey}/recurrence-policies/key={key}
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.
key
String
key of the RecurrencePolicy.
Query parameters:
expand
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

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

action
String
"setKey"
key
String

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

MinLength2MaxLength256Pattern^[A-Za-z0-9_-]+$
Example: json
{
  "action": "setKey",
  "key": "new-key"
}

Set Name

action
String
"setName"
name

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

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

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