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. |
createdBy BETA | IDs and references that created the RecurrencePolicy. |
lastModifiedAt DateTime | Date and time (UTC) the RecurrencePolicy was last updated. |
lastModifiedBy BETA | 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
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
id String | Unique identifier of the referenced RecurrencePolicy. |
typeId | recurrence-policy Type of referenced resource. |
obj | Contains the representation of the expanded RecurrencePolicy.
Only present in responses to requests with Reference Expansion for RecurrencePolicy. |
RecurrencePolicyResourceIdentifier
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
StandardSchedule
type String | "standard" |
value Int | Number of intervals between orders. |
intervalUnit | The interval used for this schedule. |
StandardScheduleDraft
type String | "standard" |
value Int | Number of intervals between orders. |
intervalUnit | Interval used for this schedule. |
DayOfMonthSchedule
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. Minimum: 1 Maximum: 31 |
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), 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. Minimum: 1 Maximum: 31 |
IntervalUnit
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
id
.view_recurring_orders:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String | key of the Project. |
id String | id of the RecurrencePolicy. |
expand | The parameter can be passed multiple times. |
application/json
curl --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}
region String | Region in which the Project is hosted. |
projectKey String | key of the Project. |
key String | key of the RecurrencePolicy. |
expand | The parameter can be passed multiple times. |
application/json
curl --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
view_recurring_orders:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String | 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. |
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. |
RecurrencePolicyPagedQueryResponse
asapplication/json
curl --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 OK
status if the Recurrence Policy exists, or a NotFound error otherwise.view_recurring_orders:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String | key of the Project. |
id String | 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 OK
status if the Recurrence Policy exists, or a NotFound error otherwise.view_recurring_orders:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String | key of the Project. |
key String | 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 OK
status if any Recurrence Policies match the query predicate, or a NotFound error otherwise.view_recurring_orders:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String | 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
manage_recurring_orders:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String | key of the Project. |
expand | The parameter can be passed multiple times. |
application/json
application/json
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
{
"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}
region String | Region in which the Project is hosted. |
projectKey String | key of the Project. |
id String | id of the RecurrencePolicy. |
expand | The parameter can be passed multiple times. |
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. |
application/json
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
{
"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}
region String | Region in which the Project is hosted. |
projectKey String | key of the Project. |
key String | key of the RecurrencePolicy. |
expand | The parameter can be passed multiple times. |
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. |
application/json
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
{
"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. MinLength:2 MaxLength: 256 Pattern: ^[A-Za-z0-9_-]+$ |
{
"action": "setKey",
"key": "new-key"
}
Set Name
action String | "setName" |
name | Value to set. If empty, any existing value will be removed. |
{
"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. |
{
"action": "setDescription",
"description": {
"en": "New description"
}
}