Checkout Recurring Payments API

Define where the future payments of a Recurring Order are processed.

A RecurringPayment maps a Recurring Order to the PaymentMethod and Payment Connector that process its future payments. Checkout creates a RecurringPayment automatically when a Recurring Payment Job runs. The Checkout Recurring Payments API is also available for you to inspect or adjust the payment setup of a Recurring Order.
To understand how Recurring Orders work with Checkout and their constraints, see Recurring Orders in Checkout.

Checkout only supports processing a RecurringPayment with one PaymentMethodConfiguration.

Scope

ScopePermission granted
view_recurring_payments:{projectKey}View Recurring Payments
manage_recurring_payments:{projectKey}Manage Recurring Payments

Get Recurring Payment

Get Recurring Payment by ID

GET
https://checkout.{region}.commercetools.com/{projectKey}/recurring-payments/{id}
Retrieves a Recurring Payment with a given id. Specific Error Codes:
OAuth 2.0 Scopes:
view_recurring_payments:{projectKey}manage_recurring_payments:{projectKey}manage_projects:{projectKey}
Path parameters:
projectKey
​
String
​
Identifier of your Checkout entity and key of your Project.
id
​
String
​
id of the RecurringPayment.
region
​
String
​
Region in which the Checkout application is hosted.
Response:
200

RecurringPayment

as
application/json
Request Example:cURL
curl --get https://checkout.{region}.commercetools.com/{projectKey}/recurring-payments/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 
200 Response Example: RecurringPaymentjson
{
  "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

GET
https://checkout.{region}.commercetools.com/{projectKey}/recurring-payments/key={key}
Retrieves a Recurring Payment with a given key. Specific Error Codes:
OAuth 2.0 Scopes:
view_recurring_payments:{projectKey}manage_recurring_payments:{projectKey}manage_projects:{projectKey}
Path parameters:
projectKey
​
String
​
Identifier of your Checkout entity and key of your Project.
key
​
String
​
key of the RecurringPayment.
region
​
String
​
Region in which the Checkout application is hosted.
Response:
200

RecurringPayment

as
application/json
Request Example:cURL
curl --get https://checkout.{region}.commercetools.com/{projectKey}/recurring-payments/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 
200 Response Example: RecurringPaymentjson
{
  "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

GET
https://checkout.{region}.commercetools.com/{projectKey}/recurring-payments
Retrieves Recurring Payments in a Project.
The results are paginated.
OAuth 2.0 Scopes:
view_recurring_payments:{projectKey}manage_recurring_payments:{projectKey}manage_projects:{projectKey}
Path parameters:
projectKey
​
String
​
Identifier of your Checkout entity and key of your Project.
region
​
String
​
Region in which the Checkout application is hosted.
Query parameters:
sort
​
String
​
Controls Sorting of query results. The following fields are available for sorting: id, key, createdAt, lastModifiedAt.
The parameter can be passed multiple times.
limit
​
Int32
​

Number of results requested.

Default: 20​
Minimum: 0​
Maximum: 500​
offset
​
Int32
​

Number of elements skipped.

Default: 0​
Maximum: 10000​
withTotal
​
Boolean
​

Controls the calculation of the total number of query results.

Default: false​
recurringOrderId
​
String
​
Filters the results by the id of the RecurringOrder using the format recurringOrderId=eq:{value}.
Response:
200

as
application/json
Request Example:cURL
curl --get https://checkout.{region}.commercetools.com/{projectKey}/recurring-payments -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 
200 Response Example: PaginatedRecurringPaymentjson
{
  "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

POST
https://checkout.{region}.commercetools.com/{projectKey}/recurring-payments
OAuth 2.0 Scopes:
manage_recurring_payments:{projectKey}manage_projects:{projectKey}
Path parameters:
projectKey
​
String
​
Identifier of your Checkout entity and key of your Project.
region
​
String
​
Region in which the Checkout application is hosted.
Request Body:RecurringPaymentDraftasapplication/json
Response:
201

RecurringPayment

as
application/json
Request Example:cURL
curl 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
201 Response Example: RecurringPaymentjson
{
  "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

POST
https://checkout.{region}.commercetools.com/{projectKey}/recurring-payments/{id}
Updates a Recurring Payment with a given id. Specific Error Codes:
OAuth 2.0 Scopes:
manage_recurring_payments:{projectKey}manage_projects:{projectKey}
Path parameters:
projectKey
​
String
​
Identifier of your Checkout entity and key of your Project.
id
​
String
​
id of the RecurringPayment.
region
​
String
​
Region in which the Checkout application is hosted.
Request Body:
application/json
Request body to update a RecurringPayment.
version​
Int​
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.
actions​
Array of RecurringPaymentUpdateAction​

Update actions to be performed on the RecurringPayment.

Response:
200

RecurringPayment

as
application/json
Request Example:cURL
curl 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
200 Response Example: RecurringPaymentjson
{
  "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

POST
https://checkout.{region}.commercetools.com/{projectKey}/recurring-payments/key={key}
Updates a Recurring Payment with a given key. Specific Error Codes:
OAuth 2.0 Scopes:
manage_recurring_payments:{projectKey}manage_projects:{projectKey}
Path parameters:
projectKey
​
String
​
Identifier of your Checkout entity and key of your Project.
key
​
String
​
key of the RecurringPayment.
region
​
String
​
Region in which the Checkout application is hosted.
Request Body:
application/json
Request body to update a RecurringPayment.
version​
Int​
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.
actions​
Array of RecurringPaymentUpdateAction​

Update actions to be performed on the RecurringPayment.

Response:
200

RecurringPayment

as
application/json
Request Example:cURL
curl 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
200 Response Example: RecurringPaymentjson
{
  "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.

action​
String​
"setKey"

Type of update action to be performed on the RecurringPayment.

key​
String​

Key to set. If omitted, any existing value is removed.

Set Recurring Order

Sets the RecurringOrder of a RecurringPayment.
action​
String​
"setRecurringOrder"

Type of update action to be performed on the RecurringPayment.

recurringOrder​
RecurringOrderReference​

Set Payment Method Configuration

Sets the PaymentMethodConfigurations of a RecurringPayment, replacing any existing ones. Checkout only supports processing this array with one PaymentMethodConfiguration.

action​
String​
"setPaymentMethodConfiguration"

Type of update action to be performed on the RecurringPayment.

paymentMethodConfigurations​

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.

action​
String​
"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

DELETE
https://checkout.{region}.commercetools.com/{projectKey}/recurring-payments/{id}
Deletes a Recurring Payment with a given id. Specific Error Codes:
OAuth 2.0 Scopes:
manage_recurring_payments:{projectKey}manage_projects:{projectKey}
Path parameters:
projectKey
​
String
​
Identifier of your Checkout entity and key of your Project.
id
​
String
​
id of the RecurringPayment.
region
​
String
​
Region in which the Checkout application is hosted.
Query parameters:
version
​
Int64
​

Last seen version of the resource.

Response:
200

RecurringPayment

as
application/json
Request Example:cURL
curl -X DELETE https://checkout.{region}.commercetools.com/{projectKey}/recurring-payments/{id}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: RecurringPaymentjson
{
  "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

DELETE
https://checkout.{region}.commercetools.com/{projectKey}/recurring-payments/key={key}
Deletes a Recurring Payment with a given key. Specific Error Codes:
OAuth 2.0 Scopes:
manage_recurring_payments:{projectKey}manage_projects:{projectKey}
Path parameters:
projectKey
​
String
​
Identifier of your Checkout entity and key of your Project.
key
​
String
​
key of the RecurringPayment.
region
​
String
​
Region in which the Checkout application is hosted.
Query parameters:
version
​
Int64
​

Last seen version of the resource.

Response:
200

RecurringPayment

as
application/json
Request Example:cURL
curl -X DELETE https://checkout.{region}.commercetools.com/{projectKey}/recurring-payments/key={key}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: RecurringPaymentjson
{
  "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

When querying Recurring Payments, you can sort the results using the sort query parameter. The following fields are available for sorting:
FieldDescriptionExample
idSort by Recurring Payment IDid asc
keySort by Recurring Payment keykey asc
createdAtSort by creation timestampcreatedAt desc
lastModifiedAtSort by the last modified timestamplastModifiedAt asc

Sorting examples

Basic sorting:
Basic sortinghttp
GET /{projectKey}/recurring-payments?sort=createdAt%20desc
GET /{projectKey}/recurring-payments?sort=id%20asc
Sorting with pagination:
Sorting with paginationhttp
GET /{projectKey}/recurring-payments?sort=lastModifiedAt%20desc&limit=10&offset=0

Representations

RecurringPayment

Maps a RecurringOrder to the PaymentMethod and Connector that process its future payments.
id​
String​

Unique identifier of the RecurringPayment.

version​
Int​

Current version of the RecurringPayment.

key​
String​

User-defined unique identifier of the RecurringPayment.

MinLength: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
recurringOrder​
RecurringOrderReference​
RecurringOrder whose future payments are processed using Checkout.
paymentMethodConfigurations​
PaymentMethod and Connector used to pay the RecurringOrder. Checkout only supports processing this array with one PaymentMethodConfiguration.
createdAt​
DateTime​

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

lastModifiedAt​
DateTime​

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

RecurringPaymentDraft

Draft type to create a RecurringPayment.
key​
String​

User-defined unique identifier of the RecurringPayment.

MinLength: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
recurringOrder​
RecurringOrderReference​
RecurringOrder whose future payments must be processed using Checkout.
paymentMethodConfigurations​
PaymentMethod and Connector to use to pay the RecurringOrder. Checkout only supports processing this array with one PaymentMethodConfiguration.
MinItems: 1​

PaymentMethodConfiguration

The PaymentMethod used to pay a RecurringOrder and the Connector that processes it.
Checkout only supports processing a RecurringPayment with one PaymentMethodConfiguration.
paymentMethod​
PaymentMethod used to pay the RecurringOrder.
connectorDeployment​
Connector Deployment that processes the future payments of the RecurringOrder.

PaymentMethodReference

Reference to a PaymentMethod.
id​
String​
Unique identifier of the referenced PaymentMethod.
typeId​
payment-method

ConnectorDeploymentReference

Reference to a ConnectorDeployment for the payment integration.

id​
String​

Unique identifier of the referenced ConnectorDeployment.

typeId​
String​
Type identifier, always deployment for ConnectorDeployment references.