Define where the future payments of a Recurring Order are processed.
Checkout only supports processing a RecurringPayment with one PaymentMethodConfiguration.
Scope
| Scope | Permission granted |
|---|---|
view_recurring_payments:{projectKey} | View Recurring Payments |
manage_recurring_payments:{projectKey} | Manage Recurring Payments |
Get Recurring Payment
Get Recurring Payment by ID
id. Specific Error Codes:view_recurring_payments:{projectKey}manage_recurring_payments:{projectKey}manage_projects:{projectKey}projectKeyString | Identifier of your Checkout entity and key of your Project. |
idString | id of the RecurringPayment. |
regionString |
application/jsoncurl --get https://checkout.{region}.commercetools.com/{projectKey}/recurring-payments/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" {
"id": "6f2b7c1a-9e3d-4a5b-8c6f-1d2e3f4a5b6c",
"version": 1,
"key": "recurring-payment-key",
"recurringOrder": {
"typeId": "recurring-order",
"id": "39ccda28-47f9-41bf-8dde-e1d720c19000"
},
"paymentMethodConfigurations": [
{
"paymentMethod": {
"typeId": "payment-method",
"id": "9c5e8f2a-3b7d-4e6a-9c1f-2a5b8d7e4f3c"
},
"connectorDeployment": {
"typeId": "deployment",
"id": "4c24762b-87df-4bd3-898a-bafed913a9ca"
}
}
],
"createdAt": "2026-06-02T11:34:07.520Z",
"lastModifiedAt": "2026-07-14T08:15:29.840Z"
}Get Recurring Payment by Key
key. Specific Error Codes:view_recurring_payments:{projectKey}manage_recurring_payments:{projectKey}manage_projects:{projectKey}projectKeyString | Identifier of your Checkout entity and key of your Project. |
keyString | key of the RecurringPayment. |
regionString |
application/jsoncurl --get https://checkout.{region}.commercetools.com/{projectKey}/recurring-payments/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" {
"id": "6f2b7c1a-9e3d-4a5b-8c6f-1d2e3f4a5b6c",
"version": 1,
"key": "recurring-payment-key",
"recurringOrder": {
"typeId": "recurring-order",
"id": "39ccda28-47f9-41bf-8dde-e1d720c19000"
},
"paymentMethodConfigurations": [
{
"paymentMethod": {
"typeId": "payment-method",
"id": "9c5e8f2a-3b7d-4e6a-9c1f-2a5b8d7e4f3c"
},
"connectorDeployment": {
"typeId": "deployment",
"id": "4c24762b-87df-4bd3-898a-bafed913a9ca"
}
}
],
"createdAt": "2026-06-02T11:34:07.520Z",
"lastModifiedAt": "2026-07-14T08:15:29.840Z"
}Query Recurring Payments
view_recurring_payments:{projectKey}manage_recurring_payments:{projectKey}manage_projects:{projectKey}projectKeyString | Identifier of your Checkout entity and key of your Project. |
regionString |
sortString | Controls Sorting of query results. The following fields are available for sorting: id, key, createdAt, lastModifiedAt.The parameter can be passed multiple times. |
limitInt32 | Number of results requested. Default: 20Minimum: 0Maximum: 500 |
offsetInt32 | Number of elements skipped. Default: 0Maximum: 10000 |
withTotalBoolean | Controls the calculation of the total number of query results. Default: false |
recurringOrderIdString |
application/jsoncurl --get https://checkout.{region}.commercetools.com/{projectKey}/recurring-payments -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" {
"limit": 20,
"offset": 0,
"count": 1,
"total": 1,
"results": [
{
"id": "6f2b7c1a-9e3d-4a5b-8c6f-1d2e3f4a5b6c",
"version": 1,
"key": "recurring-payment-key",
"recurringOrder": {
"typeId": "recurring-order",
"id": "39ccda28-47f9-41bf-8dde-e1d720c19000"
},
"paymentMethodConfigurations": [
{
"paymentMethod": {
"typeId": "payment-method",
"id": "9c5e8f2a-3b7d-4e6a-9c1f-2a5b8d7e4f3c"
},
"connectorDeployment": {
"typeId": "deployment",
"id": "4c24762b-87df-4bd3-898a-bafed913a9ca"
}
}
],
"createdAt": "2026-06-02T11:34:07.520Z",
"lastModifiedAt": "2026-07-14T08:15:29.840Z"
}
]
}Create Recurring Payment
manage_recurring_payments:{projectKey}manage_projects:{projectKey}projectKeyString | Identifier of your Checkout entity and key of your Project. |
regionString |
application/jsonapplication/jsoncurl https://checkout.{region}.commercetools.com/{projectKey}/recurring-payments -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"key" : "recurring-payment-key",
"recurringOrder" : {
"typeId" : "recurring-order",
"id" : "39ccda28-47f9-41bf-8dde-e1d720c19000"
},
"paymentMethodConfigurations" : [ {
"paymentMethod" : {
"typeId" : "payment-method",
"id" : "9c5e8f2a-3b7d-4e6a-9c1f-2a5b8d7e4f3c"
},
"connectorDeployment" : {
"typeId" : "deployment",
"id" : "4c24762b-87df-4bd3-898a-bafed913a9ca"
}
} ]
}
DATA{
"id": "6f2b7c1a-9e3d-4a5b-8c6f-1d2e3f4a5b6c",
"version": 1,
"key": "recurring-payment-key",
"recurringOrder": {
"typeId": "recurring-order",
"id": "39ccda28-47f9-41bf-8dde-e1d720c19000"
},
"paymentMethodConfigurations": [
{
"paymentMethod": {
"typeId": "payment-method",
"id": "9c5e8f2a-3b7d-4e6a-9c1f-2a5b8d7e4f3c"
},
"connectorDeployment": {
"typeId": "deployment",
"id": "4c24762b-87df-4bd3-898a-bafed913a9ca"
}
}
],
"createdAt": "2026-06-02T11:34:07.520Z",
"lastModifiedAt": "2026-07-14T08:15:29.840Z"
}Update Recurring Payment
Update Recurring Payment by ID
id. Specific Error Codes:manage_recurring_payments:{projectKey}manage_projects:{projectKey}projectKeyString | Identifier of your Checkout entity and key of your Project. |
idString | id of the RecurringPayment. |
regionString |
application/jsonversionInt | Expected version of the RecurringPayment 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 RecurringPaymentUpdateAction | Update actions to be performed on the RecurringPayment. |
application/jsoncurl https://checkout.{region}.commercetools.com/{projectKey}/recurring-payments/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"version" : 1,
"actions" : [ {
"action" : "setKey",
"key" : "new-recurring-payment-key"
} ]
}
DATA{
"id": "6f2b7c1a-9e3d-4a5b-8c6f-1d2e3f4a5b6c",
"version": 1,
"key": "recurring-payment-key",
"recurringOrder": {
"typeId": "recurring-order",
"id": "39ccda28-47f9-41bf-8dde-e1d720c19000"
},
"paymentMethodConfigurations": [
{
"paymentMethod": {
"typeId": "payment-method",
"id": "9c5e8f2a-3b7d-4e6a-9c1f-2a5b8d7e4f3c"
},
"connectorDeployment": {
"typeId": "deployment",
"id": "4c24762b-87df-4bd3-898a-bafed913a9ca"
}
}
],
"createdAt": "2026-06-02T11:34:07.520Z",
"lastModifiedAt": "2026-07-14T08:15:29.840Z"
}Update Recurring Payment by Key
key. Specific Error Codes:manage_recurring_payments:{projectKey}manage_projects:{projectKey}projectKeyString | Identifier of your Checkout entity and key of your Project. |
keyString | key of the RecurringPayment. |
regionString |
application/jsonversionInt | Expected version of the RecurringPayment 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 RecurringPaymentUpdateAction | Update actions to be performed on the RecurringPayment. |
application/jsoncurl https://checkout.{region}.commercetools.com/{projectKey}/recurring-payments/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"version" : 1,
"actions" : [ {
"action" : "setKey",
"key" : "new-recurring-payment-key"
} ]
}
DATA{
"id": "6f2b7c1a-9e3d-4a5b-8c6f-1d2e3f4a5b6c",
"version": 1,
"key": "recurring-payment-key",
"recurringOrder": {
"typeId": "recurring-order",
"id": "39ccda28-47f9-41bf-8dde-e1d720c19000"
},
"paymentMethodConfigurations": [
{
"paymentMethod": {
"typeId": "payment-method",
"id": "9c5e8f2a-3b7d-4e6a-9c1f-2a5b8d7e4f3c"
},
"connectorDeployment": {
"typeId": "deployment",
"id": "4c24762b-87df-4bd3-898a-bafed913a9ca"
}
}
],
"createdAt": "2026-06-02T11:34:07.520Z",
"lastModifiedAt": "2026-07-14T08:15:29.840Z"
}Update actions
The following update actions allow you to modify specific properties of a RecurringPayment. Use them with the update endpoints as described above.
Set Key
Sets or unsets the key of a RecurringPayment.
actionString | "setKey"Type of update action to be performed on the RecurringPayment. |
keyString | Key to set. If omitted, any existing value is removed. |
Set Recurring Order
actionString | "setRecurringOrder"Type of update action to be performed on the RecurringPayment. |
recurringOrderRecurringOrderReference | RecurringOrder to set. |
Set Payment Method Configuration
Sets the PaymentMethodConfigurations of a RecurringPayment, replacing any existing ones. Checkout only supports processing this array with one PaymentMethodConfiguration.
actionString | "setPaymentMethodConfiguration"Type of update action to be performed on the RecurringPayment. |
paymentMethodConfigurationsArray of PaymentMethodConfiguration | PaymentMethod and Connector to set. MinItems:1 |
Add Payment Method Configuration
Adds a PaymentMethodConfiguration to a RecurringPayment. Checkout only supports processing a RecurringPayment with one PaymentMethodConfiguration.
actionString | "addPaymentMethodConfiguration"Type of update action to be performed on the RecurringPayment. |
paymentMethodConfiguration | PaymentMethod and Connector to add. |
Delete Recurring Payment
Delete Recurring Payment by ID
id. Specific Error Codes:manage_recurring_payments:{projectKey}manage_projects:{projectKey}projectKeyString | Identifier of your Checkout entity and key of your Project. |
idString | id of the RecurringPayment. |
regionString |
versionInt64 | Last seen version of the resource. |
application/jsoncurl -X DELETE https://checkout.{region}.commercetools.com/{projectKey}/recurring-payments/{id}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"{
"id": "6f2b7c1a-9e3d-4a5b-8c6f-1d2e3f4a5b6c",
"version": 1,
"key": "recurring-payment-key",
"recurringOrder": {
"typeId": "recurring-order",
"id": "39ccda28-47f9-41bf-8dde-e1d720c19000"
},
"paymentMethodConfigurations": [
{
"paymentMethod": {
"typeId": "payment-method",
"id": "9c5e8f2a-3b7d-4e6a-9c1f-2a5b8d7e4f3c"
},
"connectorDeployment": {
"typeId": "deployment",
"id": "4c24762b-87df-4bd3-898a-bafed913a9ca"
}
}
],
"createdAt": "2026-06-02T11:34:07.520Z",
"lastModifiedAt": "2026-07-14T08:15:29.840Z"
}Delete Recurring Payment by Key
key. Specific Error Codes:manage_recurring_payments:{projectKey}manage_projects:{projectKey}projectKeyString | Identifier of your Checkout entity and key of your Project. |
keyString | key of the RecurringPayment. |
regionString |
versionInt64 | Last seen version of the resource. |
application/jsoncurl -X DELETE https://checkout.{region}.commercetools.com/{projectKey}/recurring-payments/key={key}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"{
"id": "6f2b7c1a-9e3d-4a5b-8c6f-1d2e3f4a5b6c",
"version": 1,
"key": "recurring-payment-key",
"recurringOrder": {
"typeId": "recurring-order",
"id": "39ccda28-47f9-41bf-8dde-e1d720c19000"
},
"paymentMethodConfigurations": [
{
"paymentMethod": {
"typeId": "payment-method",
"id": "9c5e8f2a-3b7d-4e6a-9c1f-2a5b8d7e4f3c"
},
"connectorDeployment": {
"typeId": "deployment",
"id": "4c24762b-87df-4bd3-898a-bafed913a9ca"
}
}
],
"createdAt": "2026-06-02T11:34:07.520Z",
"lastModifiedAt": "2026-07-14T08:15:29.840Z"
}Sort results
sort query parameter. The following fields are available for sorting:| Field | Description | Example |
|---|---|---|
id | Sort by Recurring Payment ID | id asc |
key | Sort by Recurring Payment key | key asc |
createdAt | Sort by creation timestamp | createdAt desc |
lastModifiedAt | Sort by the last modified timestamp | lastModifiedAt asc |
Sorting examples
GET /{projectKey}/recurring-payments?sort=createdAt%20desc
GET /{projectKey}/recurring-payments?sort=id%20asc
GET /{projectKey}/recurring-payments?sort=lastModifiedAt%20desc&limit=10&offset=0
Representations
RecurringPayment
idString | Unique identifier of the RecurringPayment. |
versionInt | Current version of the RecurringPayment. |
keyString | User-defined unique identifier of the RecurringPayment. MinLength:2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$ |
recurringOrderRecurringOrderReference | RecurringOrder whose future payments are processed using Checkout. |
paymentMethodConfigurationsArray of PaymentMethodConfiguration | PaymentMethod and Connector used to pay the RecurringOrder. Checkout only supports processing this array with one PaymentMethodConfiguration. |
createdAtDateTime | Date and time (UTC) the RecurringPayment was initially created. |
lastModifiedAtDateTime | Date and time (UTC) the RecurringPayment was last updated. |
RecurringPaymentDraft
keyString | User-defined unique identifier of the RecurringPayment. MinLength:2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$ |
recurringOrderRecurringOrderReference | RecurringOrder whose future payments must be processed using Checkout. |
paymentMethodConfigurationsArray of PaymentMethodConfiguration | PaymentMethod and Connector to use to pay the RecurringOrder. Checkout only supports processing this array with one PaymentMethodConfiguration. MinItems: 1 |
PaymentMethodConfiguration
paymentMethod | PaymentMethod used to pay the RecurringOrder. |
connectorDeployment | Connector Deployment that processes the future payments of the RecurringOrder. |
PaymentMethodReference
idString | Unique identifier of the referenced PaymentMethod. |
typeId | payment-method |
ConnectorDeploymentReference
Reference to a ConnectorDeployment for the payment integration.
idString | Unique identifier of the referenced ConnectorDeployment. |
typeIdString | Type identifier, always deployment for ConnectorDeployment references. |