Checkout Recurring Payment Jobs API

Automate the configuration of future payments for a Recurring Order.

The Recurring Payment Jobs API lets Checkout automate the configuration of the Recurring Cart associated with a Recurring Order, so that its future Orders can be paid using Checkout. To understand how Recurring Orders work with Checkout and their constraints, see Recurring Orders in Checkout.

Use the Checkout Recurring Payment Jobs API only for Payments managed by Checkout.

When you create a Recurring Order, Checkout uses the Order's Recurring Payment Job to:

Set the payment allocation of the Recurring Cart's recurringPaymentConfiguration to 100% of the PaymentMethod.
Create the Recurring Payment that links the Recurring Order to the PaymentMethod and to the Payment Connector responsible for processing its future payments.

A Recurring Payment Job is used only once to set up the future payments of a Recurring Order. After it has been processed, its status reflects the outcome, but Checkout no longer uses it.

If a Recurring Payment Job has not been processed yet by the time it is needed, Checkout automatically retries it until it succeeds or reaches the maximum number of 3 attempts.

Scope

Scope	Permission granted
`view_recurring_payment_jobs:{projectKey}`	View Recurring Payment Jobs
`manage_recurring_payment_jobs:{projectKey}`	Manage Recurring Payment Jobs

Get Recurring Payment Job

Get Recurring Payment Job by ID

GET

https://checkout.{region}.commercetools.com/{projectKey}/recurring-payment-jobs/{id}

Retrieves a Recurring Payment Job with a given id. Specific Error Codes:

OAuth 2.0 Scopes:

view_recurring_payment_jobs:{projectKey}manage_recurring_payment_jobs:{projectKey}manage_projects:{projectKey}

Path parameters:

`projectKey` String	Identifier of your Checkout entity and `key` of your Project.
`id` String	`id` of the RecurringPaymentJob.
`region` String	Region in which the Checkout application is hosted.

Response:

200

RecurringPaymentJob

application/json

curl --get https://checkout.{region}.commercetools.com/{projectKey}/recurring-payment-jobs/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 

{
  "id": "6d95b6c6-5ef0-4091-8478-b26077ca2b2f",
  "version": 1,
  "key": "recurring-payment-job-key",
  "originPayment": {
    "typeId": "payment",
    "id": "d1fec278-22c2-4a1d-8190-8f1e8af5ccfb"
  },
  "paymentMethod": {
    "typeId": "payment-method",
    "id": "9c5e8f2a-3b7d-4e6a-9c1f-2a5b8d7e4f3c"
  },
  "recurringPayments": [
    {
      "typeId": "recurring-payment",
      "id": "39ccda28-47f9-41bf-8dde-e1d720c19000"
    }
  ],
  "status": {
    "state": "Completed",
    "attempts": 1
  },
  "createdAt": "2026-07-14T08:15:22.310Z",
  "lastModifiedAt": "2026-07-19T08:15:29.840Z"
}

Get Recurring Payment Job by Key

GET

https://checkout.{region}.commercetools.com/{projectKey}/recurring-payment-jobs/key={key}

Retrieves a Recurring Payment Job with a given key. Specific Error Codes:

OAuth 2.0 Scopes:

view_recurring_payment_jobs:{projectKey}manage_recurring_payment_jobs:{projectKey}manage_projects:{projectKey}

Path parameters:

`projectKey` String	Identifier of your Checkout entity and `key` of your Project.
`key` String	`key` of the RecurringPaymentJob.
`region` String	Region in which the Checkout application is hosted.

Response:

200

RecurringPaymentJob

application/json

curl --get https://checkout.{region}.commercetools.com/{projectKey}/recurring-payment-jobs/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 

{
  "id": "6d95b6c6-5ef0-4091-8478-b26077ca2b2f",
  "version": 1,
  "key": "recurring-payment-job-key",
  "originPayment": {
    "typeId": "payment",
    "id": "d1fec278-22c2-4a1d-8190-8f1e8af5ccfb"
  },
  "paymentMethod": {
    "typeId": "payment-method",
    "id": "9c5e8f2a-3b7d-4e6a-9c1f-2a5b8d7e4f3c"
  },
  "recurringPayments": [
    {
      "typeId": "recurring-payment",
      "id": "39ccda28-47f9-41bf-8dde-e1d720c19000"
    }
  ],
  "status": {
    "state": "Completed",
    "attempts": 1
  },
  "createdAt": "2026-07-14T08:15:22.310Z",
  "lastModifiedAt": "2026-07-19T08:15:29.840Z"
}

Query Recurring Payment Jobs

GET

https://checkout.{region}.commercetools.com/{projectKey}/recurring-payment-jobs

Retrieves Recurring Payment Jobs in a Project.

The results are paginated.

OAuth 2.0 Scopes:

view_recurring_payment_jobs:{projectKey}manage_recurring_payment_jobs:{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`
`status.state` String	Filters the results by `status.state` using the format `status.state=eq:{value}`.

Response:

200

application/json

curl --get https://checkout.{region}.commercetools.com/{projectKey}/recurring-payment-jobs -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 

{
  "limit": 20,
  "offset": 0,
  "count": 1,
  "total": 1,
  "results": [
    {
      "id": "6d95b6c6-5ef0-4091-8478-b26077ca2b2f",
      "version": 1,
      "key": "recurring-payment-job-key",
      "originPayment": {
        "typeId": "payment",
        "id": "d1fec278-22c2-4a1d-8190-8f1e8af5ccfb"
      },
      "paymentMethod": {
        "typeId": "payment-method",
        "id": "9c5e8f2a-3b7d-4e6a-9c1f-2a5b8d7e4f3c"
      },
      "recurringPayments": [
        {
          "typeId": "recurring-payment",
          "id": "39ccda28-47f9-41bf-8dde-e1d720c19000"
        }
      ],
      "status": {
        "state": "Completed",
        "attempts": 1
      },
      "createdAt": "2026-07-14T08:15:22.310Z",
      "lastModifiedAt": "2026-07-14T08:15:29.840Z"
    }
  ]
}

Create Recurring Payment Job

POST

https://checkout.{region}.commercetools.com/{projectKey}/recurring-payment-jobs

Creates a new RecurringPaymentJob. Specific Error Codes:

OAuth 2.0 Scopes:

manage_recurring_payment_jobs:{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:RecurringPaymentJobDraftasapplication/json

Response:

201

RecurringPaymentJob

application/json

curl https://checkout.{region}.commercetools.com/{projectKey}/recurring-payment-jobs -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "key" : "recurring-payment-job-key",
  "originPayment" : {
    "typeId" : "payment",
    "id" : "d1fec278-22c2-4a1d-8190-8f1e8af5ccfb"
  },
  "paymentMethod" : {
    "typeId" : "payment-method",
    "id" : "9c5e8f2a-3b7d-4e6a-9c1f-2a5b8d7e4f3c"
  }
}
DATA

{
  "id": "6d95b6c6-5ef0-4091-8478-b26077ca2b2f",
  "version": 1,
  "key": "recurring-payment-job-key",
  "originPayment": {
    "typeId": "payment",
    "id": "d1fec278-22c2-4a1d-8190-8f1e8af5ccfb"
  },
  "paymentMethod": {
    "typeId": "payment-method",
    "id": "9c5e8f2a-3b7d-4e6a-9c1f-2a5b8d7e4f3c"
  },
  "recurringPayments": [
    {
      "typeId": "recurring-payment",
      "id": "39ccda28-47f9-41bf-8dde-e1d720c19000"
    }
  ],
  "status": {
    "state": "Completed",
    "attempts": 1
  },
  "createdAt": "2026-07-14T08:15:22.310Z",
  "lastModifiedAt": "2026-07-19T08:15:29.840Z"
}

Delete Recurring Payment Job

Delete Recurring Payment Job by ID

DELETE

https://checkout.{region}.commercetools.com/{projectKey}/recurring-payment-jobs/{id}

Deletes a Recurring Payment Job with a given id. Specific Error Codes:

OAuth 2.0 Scopes:

manage_recurring_payment_jobs:{projectKey}manage_projects:{projectKey}

Path parameters:

`projectKey` String	Identifier of your Checkout entity and `key` of your Project.
`id` String	`id` of the RecurringPaymentJob.
`region` String	Region in which the Checkout application is hosted.

Query parameters:

version

Int64

Last seen version of the resource.

Response:

200

RecurringPaymentJob

application/json

curl -X DELETE https://checkout.{region}.commercetools.com/{projectKey}/recurring-payment-jobs/{id}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

{
  "id": "6d95b6c6-5ef0-4091-8478-b26077ca2b2f",
  "version": 1,
  "key": "recurring-payment-job-key",
  "originPayment": {
    "typeId": "payment",
    "id": "d1fec278-22c2-4a1d-8190-8f1e8af5ccfb"
  },
  "paymentMethod": {
    "typeId": "payment-method",
    "id": "9c5e8f2a-3b7d-4e6a-9c1f-2a5b8d7e4f3c"
  },
  "recurringPayments": [
    {
      "typeId": "recurring-payment",
      "id": "39ccda28-47f9-41bf-8dde-e1d720c19000"
    }
  ],
  "status": {
    "state": "Completed",
    "attempts": 1
  },
  "createdAt": "2026-07-14T08:15:22.310Z",
  "lastModifiedAt": "2026-07-19T08:15:29.840Z"
}

Delete Recurring Payment Job by Key

DELETE

https://checkout.{region}.commercetools.com/{projectKey}/recurring-payment-jobs/key={key}

Deletes a Recurring Payment Job with a given key. Specific Error Codes:

OAuth 2.0 Scopes:

manage_recurring_payment_jobs:{projectKey}manage_projects:{projectKey}

Path parameters:

`projectKey` String	Identifier of your Checkout entity and `key` of your Project.
`key` String	`key` of the RecurringPaymentJob.
`region` String	Region in which the Checkout application is hosted.

Query parameters:

version

Int64

Last seen version of the resource.

Response:

200

RecurringPaymentJob

application/json

curl -X DELETE https://checkout.{region}.commercetools.com/{projectKey}/recurring-payment-jobs/key={key}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

{
  "id": "6d95b6c6-5ef0-4091-8478-b26077ca2b2f",
  "version": 1,
  "key": "recurring-payment-job-key",
  "originPayment": {
    "typeId": "payment",
    "id": "d1fec278-22c2-4a1d-8190-8f1e8af5ccfb"
  },
  "paymentMethod": {
    "typeId": "payment-method",
    "id": "9c5e8f2a-3b7d-4e6a-9c1f-2a5b8d7e4f3c"
  },
  "recurringPayments": [
    {
      "typeId": "recurring-payment",
      "id": "39ccda28-47f9-41bf-8dde-e1d720c19000"
    }
  ],
  "status": {
    "state": "Completed",
    "attempts": 1
  },
  "createdAt": "2026-07-14T08:15:22.310Z",
  "lastModifiedAt": "2026-07-19T08:15:29.840Z"
}

Sort results

When querying Recurring Payment Jobs, you can sort the results using the sort query parameter. The following fields are available for sorting:

Field	Description	Example
`id`	Sort by Recurring Payment Job ID	`id asc`
`key`	Sort by Recurring Payment Job key	`key asc`
`createdAt`	Sort by creation timestamp	`createdAt desc`
`lastModifiedAt`	Sort by the last modified timestamp	`lastModifiedAt asc`

Sorting examples

Basic sorting:

GET /{projectKey}/recurring-payment-jobs?sort=createdAt%20desc
GET /{projectKey}/recurring-payment-jobs?sort=id%20asc

Sorting with pagination:

GET /{projectKey}/recurring-payment-jobs?sort=lastModifiedAt%20desc&limit=10&offset=0

Representations

RecurringPaymentJob

RecurringPaymentJobDraft

RecurringPaymentJobStatus

RecurringPaymentJobState

RecurringPaymentJobError

PaymentMethodReference

RecurringPaymentJob

Links a Payment made through Checkout to the PaymentMethod that must be used to pay the Orders generated by the resulting Recurring Order.

`id` String	Unique identifier of the Recurring Payment Job.
`version` Int	Current version of the Recurring Payment Job.
`key` String	User-defined unique identifier of the Recurring Payment Job. MinLength: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`
`originPayment` PaymentReference	Payment made for the Cart that generated the Recurring Order.
`paymentMethod` PaymentMethodReference	PaymentMethod that must be used to pay the Orders generated by the Recurring Order.
`recurringPayments` Array of RecurringPaymentReference	Recurring Payments created from the Recurring Payment Job.
`status` RecurringPaymentJobStatus	Status of the Recurring Payment Job.
`createdAt` DateTime	Date and time (UTC) the Recurring Payment Job was initially created.
`lastModifiedAt` DateTime	Date and time (UTC) the Recurring Payment Job was last updated.

RecurringPaymentJobDraft

Draft type to create a RecurringPaymentJob.

`key` String	User-defined unique identifier of the Recurring Payment Job. MinLength: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`
`originPayment` PaymentReference	Payment made for the Cart that generates the Recurring Order.
`paymentMethod` PaymentMethodReference	PaymentMethod that must be used to pay the Orders generated by the Recurring Order.

RecurringPaymentJobStatus

The state of the RecurringPaymentJob, the number of processing attempts, and the related errors in case of a failed Recurring Payment Job.

`state` RecurringPaymentJobState	State of the Recurring Payment Job.
`attempts` Int	Number of times Checkout has attempted to process the Recurring Payment Job.
`errors` Array of RecurringPaymentJobError	Errors returned if the Recurring Payment Job is in the `Failed` state.

RecurringPaymentJobState

The state of the RecurringPaymentJob.

Initial: The Recurring Payment Job has been created and is waiting to be processed.
Pending: Checkout is setting up the future payment method and Connector for the Orders generated by the Recurring Order.
Completed: The Recurring Payment Job completed successfully. Checkout created the Recurring Payment needed to process the future payments of the Recurring Order.
Failed: The Recurring Payment Job failed.

RecurringPaymentJobError

A single error on the RecurringPaymentJob. Multiple errors may be included in the RecurringPaymentJobStatus.

`code` String	Error identifier.
`message` String	Plain text description of the cause of the error.

PaymentMethodReference

Reference to a PaymentMethod.

`id` String	Unique identifier of the referenced PaymentMethod.
`typeId` ReferenceTypeId	`payment-method`

Checkout Recurring Payment Jobs API

Scope.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Get Recurring Payment Job.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Get Recurring Payment Job by ID.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Get Recurring Payment Job by Key.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Query Recurring Payment Jobs.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Create Recurring Payment Job.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Delete Recurring Payment Job.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Delete Recurring Payment Job by ID.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Delete Recurring Payment Job by Key.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Sort results.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Sorting examples.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Representations.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

RecurringPaymentJob.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

RecurringPaymentJobDraft.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

RecurringPaymentJobStatus.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

RecurringPaymentJobState.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

RecurringPaymentJobError.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

PaymentMethodReference.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Scope

Get Recurring Payment Job

Get Recurring Payment Job by ID

Get Recurring Payment Job by Key

Query Recurring Payment Jobs

Create Recurring Payment Job

Delete Recurring Payment Job

Delete Recurring Payment Job by ID

Delete Recurring Payment Job by Key

Sort results

Sorting examples

Representations

RecurringPaymentJob

RecurringPaymentJobDraft

RecurringPaymentJobStatus

RecurringPaymentJobState

RecurringPaymentJobError

PaymentMethodReference