A Recurrence Policy is a reusable configuration that defines a schedule for selling recurring products at specific prices.
Representations
RecurrencePolicy
idString | Unique identifier of the RecurrencePolicy. |
versionInt | Current version of the RecurrencePolicy. |
keyString | User-defined unique identifier of the RecurrencePolicy. |
name | Name of the RecurrencePolicy. |
description | Description of the RecurrencePolicy. |
schedule | Schedule of the RecurrencePolicy. |
createdAt | Date and time (UTC) the RecurrencePolicy was initially created. |
createdByBETA | IDs and references that created the RecurrencePolicy. |
lastModifiedAt | Date and time (UTC) the RecurrencePolicy was last updated. |
lastModifiedByBETA | IDs and references that last modified the RecurrencePolicy. |
RecurrencePolicyDraft
keyString | 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
limitInt | Number of results requested. Default: 20Minimum: 0Maximum: 500 |
offsetInt | Number of elements skipped. Default: 0Minimum: 0Maximum: 10000 |
countInt | Actual number of results returned. |
totalInt | 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. |
resultsArray of RecurrencePolicy | RecurrencePolicies matching the query. |
RecurrencePolicyReference
idString | Unique identifier of the referenced RecurrencePolicy. |
typeId | recurrence-policyType of referenced resource. |
obj | Contains the representation of the expanded RecurrencePolicy.
Only present in responses to requests with Reference Expansion for RecurrencePolicies. |
RecurrencePolicyResourceIdentifier
id or key is required. If both are set, an InvalidJsonInput error is returned.idString | Unique identifier of the referenced RecurrencePolicy. Required if key is absent. |
keyString | User-defined unique identifier of the referenced RecurrencePolicy. Required if id is absent. |
typeId | recurrence-policyType of referenced resource. If given, it must match the expected ReferenceTypeId of the referenced resource. |
RecurrencePolicySchedule
StandardSchedule
typeString | "standard" |
valueInt | Number of intervals between orders. |
intervalUnit | Interval of this schedule. |
DayOfMonthSchedule
typeString | "dayOfMonth" |
dayInt | 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: 1Maximum: 31 |
RecurrencePolicyScheduleDraft
StandardScheduleDraft
typeString | "standard" |
valueInt | Number of intervals between orders. |
intervalUnit | Interval for this schedule. |
DayOfMonthScheduleDraft
- 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.
typeString | "dayOfMonth" |
dayInt | 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: 1Maximum: 31 |
IntervalUnit
DaysUse to set a daily schedule.
WeeksUse to set a weekly schedule.
MonthsUse to set a monthly schedule.
Get RecurrencePolicy
Get RecurrencePolicy by ID
id.view_recurring_orders:{projectKey}regionString | Region in which the Project is hosted. |
projectKeyString | key of the Project. |
idString | id of the RecurrencePolicy. |
expand | The parameter can be passed multiple times. |
application/jsoncurl --get https://api.{region}.commercetools.com/{projectKey}/recurrence-policies/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" {
"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
key.view_recurring_orders:{projectKey}regionString | Region in which the Project is hosted. |
projectKeyString | key of the Project. |
keyString | key of the RecurrencePolicy. |
expand | The parameter can be passed multiple times. |
application/jsoncurl --get https://api.{region}.commercetools.com/{projectKey}/recurrence-policies/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" {
"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
Retrieves Recurrence Policies in the Project.
view_recurring_orders:{projectKey}regionString | Region in which the Project is hosted. |
projectKeyString | key of the Project. |
where | The parameter can be passed multiple times. |
sort | The parameter can be passed multiple times. |
expand | The parameter can be passed multiple times. |
limitInt | Number of results requested. Default: 20Minimum: 0Maximum: 500 |
offsetInt | Number of elements skipped. Default: 0Maximum: 10000 |
withTotalBoolean | 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. |
RecurrencePolicyPagedQueryResponse
asapplication/jsoncurl --get https://api.{region}.commercetools.com/{projectKey}/recurrence-policies -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" {
"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
id. Returns a 200 status if the Recurrence Policy exists, or a NotFound error otherwise.view_recurring_orders:{projectKey}regionString | Region in which the Project is hosted. |
projectKeyString | key of the Project. |
idString | id of the RecurrencePolicy. |
curl --head https://api.{region}.commercetools.com/{projectKey}/recurrence-policies/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" Check if RecurrencePolicy exists by Key
key. Returns a 200 status if the Recurrence Policy exists, or a NotFound error otherwise.view_recurring_orders:{projectKey}regionString | Region in which the Project is hosted. |
projectKeyString | key of the Project. |
keyString | key of the RecurrencePolicy. |
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
200 status if any Recurrence Policies match the query predicate, or a NotFound error otherwise.view_recurring_orders:{projectKey}regionString | Region in which the Project is hosted. |
projectKeyString | key of the Project. |
where | The parameter can be passed multiple times. |
curl --head https://api.{region}.commercetools.com/{projectKey}/recurrence-policies -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" Create RecurrencePolicy
Creates a Recurrence Policy in the Project.
manage_recurring_orders:{projectKey}regionString | Region in which the Project is hosted. |
projectKeyString | key of the Project. |
expand | The parameter can be passed multiple times. |
application/jsonapplication/jsoncurl 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{
"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
manage_recurring_orders:{projectKey}regionString | Region in which the Project is hosted. |
projectKeyString | key of the Project. |
idString | id of the RecurrencePolicy. |
expand | The parameter can be passed multiple times. |
application/jsonversionInt | 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. |
actionsArray of RecurrencePolicyUpdateAction | Update actions to be performed on the RecurrencePolicy. |
application/jsoncurl 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{
"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
manage_recurring_orders:{projectKey}regionString | Region in which the Project is hosted. |
projectKeyString | key of the Project. |
keyString | key of the RecurrencePolicy. |
expand | The parameter can be passed multiple times. |
application/jsonversionInt | 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. |
actionsArray of RecurrencePolicyUpdateAction | Update actions to be performed on the RecurrencePolicy. |
application/jsoncurl 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{
"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
actionString | "setKey" |
keyString | Value to set. If empty, any existing value will be removed. MinLength:2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$ |
{
"action": "setKey",
"key": "new-key"
}Set Name
actionString | "setName" |
name | Value to set. If empty, any existing value will be removed. |
{
"action": "setName",
"name": {
"en": "New name",
"de": "Neuer Name"
}
}Set Description
actionString | "setDescription" |
description | Value to set. If empty, any existing value will be removed. |
{
"action": "setDescription",
"description": {
"en": "New description"
}
}Set Schedule
actionString | "setSchedule" |
schedule | Schedule where the recurrence is defined. |
{
"action": "setSchedule",
"schedule": {
"type": "standard",
"value": 1,
"intervalUnit": "Days"
}
}Delete RecurrencePolicy
Delete RecurrencePolicy by ID
Deletes a Recurrence Policy in the Project.
manage_recurring_orders:{projectKey}regionString | Region in which the Project is hosted. |
projectKeyString | key of the Project. |
idString | id of the RecurrencePolicy. |
versionInt | Last seen version of the resource. |
expand | The parameter can be passed multiple times. |
application/jsoncurl -X DELETE https://api.{region}.commercetools.com/{projectKey}/recurrence-policies/{id}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"{
"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"
}
}Delete RecurrencePolicy by Key
Deletes a Recurrence Policy in the Project.
manage_recurring_orders:{projectKey}regionString | Region in which the Project is hosted. |
projectKeyString | key of the Project. |
keyString | key of the RecurrencePolicy. |
versionInt | Last seen version of the resource. |
expand | The parameter can be passed multiple times. |
application/jsoncurl -X DELETE https://api.{region}.commercetools.com/{projectKey}/recurrence-policies/key={key}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"{
"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"
}
}