Recurrence Policies

B2CB2BB2XB2C CORE COMMERCEB2B CORE COMMERCEB2X CORE COMMERCE

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

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
obj​
RecurrencePolicy​
Contains the representation of the expanded RecurrencePolicy. Only present in responses to requests with Reference Expansion for RecurrencePolicies.

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

RecurrencePolicySchedule

The schedule of a RecurrencePolicy.

StandardSchedule

Schedule of 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​
IntervalUnit​

Interval of this schedule.

DayOfMonthSchedule

Schedule of 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 when the Recurring Order is created. If the value is greater than the number of days in a given month, the order is created on the last day of the month.
Minimum: 1​Maximum: 31​

RecurrencePolicyScheduleDraft

The schedule for a RecurrencePolicy.

StandardScheduleDraft

Determines 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​
IntervalUnit​

Interval for this schedule.

DayOfMonthScheduleDraft

Determines 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), create separate Recurring Orders—each with its own schedule.
type​
String​
"dayOfMonth"
day​
Int​
The day of the month when the Recurring Order should be created. If the value is greater than the number of days in a given month, the order will be created on the last day of the month.
Minimum: 1​Maximum: 31​

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_recurrence_policies:{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

as
application/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
"{\n  \"id\" : \"4be2bea9-bf21-4987-9114-d1339bcebf3d\",\n  \"version\" : 1,\n  \"createdAt\" : \"2024-12-11T15:13:42.183Z\",\n  \"lastModifiedAt\" : \"2024-12-11T15:13:42.183Z\",\n  \"key\" : \"daily\",\n  \"name\" : {\n    \"en\" : \"daily\"\n  },\n  \"schedule\" : {\n    \"type\" : \"standard\",\n    \"value\" : 1,\n    \"intervalUnit\" : \"Days\"\n  }\n}\n"

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_recurrence_policies:{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
​
Expansion
​
The parameter can be passed multiple times.
Response:
200

RecurrencePolicy

as
application/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
"{\n  \"id\" : \"4be2bea9-bf21-4987-9114-d1339bcebf3d\",\n  \"version\" : 1,\n  \"createdAt\" : \"2024-12-11T15:13:42.183Z\",\n  \"lastModifiedAt\" : \"2024-12-11T15:13:42.183Z\",\n  \"key\" : \"daily\",\n  \"name\" : {\n    \"en\" : \"daily\"\n  },\n  \"schedule\" : {\n    \"type\" : \"standard\",\n    \"value\" : 1,\n    \"intervalUnit\" : \"Days\"\n  }\n}\n"

Query RecurrencePolicies

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

Retrieves Recurrence Policies in the Project.

OAuth 2.0 Scopes:
view_recurrence_policies:{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

as
application/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/recurrence-policies -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: RecurrencePolicyPagedQueryResponsejson
"{\n  \"limit\" : 20,\n  \"offset\" : 0,\n  \"count\" : 1,\n  \"total\" : 1,\n  \"results\" : [ {\n    \"id\" : \"4be2bea9-bf21-4987-9114-d1339bcebf3d\",\n    \"version\" : 1,\n    \"versionModifiedAt\" : \"2024-12-11T15:13:42.183Z\",\n    \"createdAt\" : \"2024-12-11T15:13:42.183Z\",\n    \"lastModifiedAt\" : \"2024-12-11T15:13:42.183Z\",\n    \"key\" : \"daily\",\n    \"name\" : {\n      \"en\" : \"daily\"\n    },\n    \"schedule\" : {\n      \"type\" : \"standard\",\n      \"value\" : 1,\n      \"intervalUnit\" : \"Days\"\n    }\n  } ]\n}\n"

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 status if the Recurrence Policy exists, or a NotFound error otherwise.
OAuth 2.0 Scopes:
view_recurrence_policies:{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 status if the Recurrence Policy exists, or a NotFound error otherwise.
OAuth 2.0 Scopes:
view_recurrence_policies:{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 status if any Recurrence Policies match the query predicate, or a NotFound error otherwise.
OAuth 2.0 Scopes:
view_recurrence_policies:{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_recurrence_policies:{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

as
application/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
"{\n  \"id\" : \"4be2bea9-bf21-4987-9114-d1339bcebf3d\",\n  \"version\" : 1,\n  \"createdAt\" : \"2024-12-11T15:13:42.183Z\",\n  \"lastModifiedAt\" : \"2024-12-11T15:13:42.183Z\",\n  \"key\" : \"daily\",\n  \"name\" : {\n    \"en\" : \"daily\"\n  },\n  \"schedule\" : {\n    \"type\" : \"standard\",\n    \"value\" : 1,\n    \"intervalUnit\" : \"Days\"\n  }\n}\n"

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_recurrence_policies:{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

as
application/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
"{\n  \"id\" : \"4be2bea9-bf21-4987-9114-d1339bcebf3d\",\n  \"version\" : 1,\n  \"createdAt\" : \"2024-12-11T15:13:42.183Z\",\n  \"lastModifiedAt\" : \"2024-12-11T15:13:42.183Z\",\n  \"key\" : \"daily\",\n  \"name\" : {\n    \"en\" : \"daily\"\n  },\n  \"schedule\" : {\n    \"type\" : \"standard\",\n    \"value\" : 1,\n    \"intervalUnit\" : \"Days\"\n  }\n}\n"

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_recurrence_policies:{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
​
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

as
application/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
"{\n  \"id\" : \"4be2bea9-bf21-4987-9114-d1339bcebf3d\",\n  \"version\" : 1,\n  \"createdAt\" : \"2024-12-11T15:13:42.183Z\",\n  \"lastModifiedAt\" : \"2024-12-11T15:13:42.183Z\",\n  \"key\" : \"daily\",\n  \"name\" : {\n    \"en\" : \"daily\"\n  },\n  \"schedule\" : {\n    \"type\" : \"standard\",\n    \"value\" : 1,\n    \"intervalUnit\" : \"Days\"\n  }\n}\n"

Update actions

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

Set Schedule

action​
String​
"setSchedule"
schedule​
RecurrencePolicyScheduleDraft​

Schedule where the recurrence is defined.

Example: json
{
  "action": "setSchedule",
  "schedule": {
    "type": "standard",
    "value": 1,
    "intervalUnit": "Days"
  }
}

Delete RecurrencePolicy

A Recurrence Policy can only be deleted if it is not referenced by any CartDiscount.

Delete RecurrencePolicy by ID

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

Deletes a Recurrence Policy in the Project.

A Recurrence Policy can be deleted only if it is not referenced by any Embedded Price, Standalone Price, or (Custom) Line Item, otherwise a ReferenceExists error is returned.
OAuth 2.0 Scopes:
manage_recurrence_policies:{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:
version
​
Int
​

Last seen version of the resource.

expand
​
Expansion
​
The parameter can be passed multiple times.
Response:
200

RecurrencePolicy

as
application/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/recurrence-policies/{id}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: RecurrencePolicyjson
"{\n  \"id\" : \"4be2bea9-bf21-4987-9114-d1339bcebf3d\",\n  \"version\" : 1,\n  \"createdAt\" : \"2024-12-11T15:13:42.183Z\",\n  \"lastModifiedAt\" : \"2024-12-11T15:13:42.183Z\",\n  \"key\" : \"daily\",\n  \"name\" : {\n    \"en\" : \"daily\"\n  },\n  \"schedule\" : {\n    \"type\" : \"standard\",\n    \"value\" : 1,\n    \"intervalUnit\" : \"Days\"\n  }\n}\n"

Delete RecurrencePolicy by Key

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

Deletes a Recurrence Policy in the Project.

A Recurrence Policy can be deleted only if it is not referenced by any Embedded Price, Standalone Price, or (Custom) Line Item, otherwise a ReferenceExists error is returned.
OAuth 2.0 Scopes:
manage_recurrence_policies:{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:
version
​
Int
​

Last seen version of the resource.

expand
​
Expansion
​
The parameter can be passed multiple times.
Response:
200

RecurrencePolicy

as
application/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/recurrence-policies/key={key}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: RecurrencePolicyjson
"{\n  \"id\" : \"4be2bea9-bf21-4987-9114-d1339bcebf3d\",\n  \"version\" : 1,\n  \"createdAt\" : \"2024-12-11T15:13:42.183Z\",\n  \"lastModifiedAt\" : \"2024-12-11T15:13:42.183Z\",\n  \"key\" : \"daily\",\n  \"name\" : {\n    \"en\" : \"daily\"\n  },\n  \"schedule\" : {\n    \"type\" : \"standard\",\n    \"value\" : 1,\n    \"intervalUnit\" : \"Days\"\n  }\n}\n"