# Checkout Recurring Payments API

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

A RecurringPayment maps a [Recurring Order](/api/projects/recurring-orders.md) to the [PaymentMethod](/search.md?urn=ctp:api:type:PaymentMethod) and [Payment Connector](/checkout/connectors-and-applications.md#payment-connectors) that process its future payments. Checkout creates a RecurringPayment automatically when a [Recurring Payment Job](/checkout/recurring-orders-in-checkout.md#recurring-payment-jobs) 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/recurring-orders-in-checkout.md).

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

[endpoint definition](/search.md?urn=ctp:checkout:endpoint:/{projectKey}/recurring-payments/{id}:GET).

### Get Recurring Payment by Key

[endpoint definition](/search.md?urn=ctp:checkout:endpoint:/{projectKey}/recurring-payments/key={key}:GET).

## Query Recurring Payments

[endpoint definition](/search.md?urn=ctp:checkout:endpoint:/{projectKey}/recurring-payments:GET).

## Create Recurring Payment

[endpoint definition](/search.md?urn=ctp:checkout:endpoint:/{projectKey}/recurring-payments:POST).

## Update Recurring Payment

### Update Recurring Payment by ID

[endpoint definition](/search.md?urn=ctp:checkout:endpoint:/{projectKey}/recurring-payments/{id}:POST).

### Update Recurring Payment by Key

[endpoint definition](/search.md?urn=ctp:checkout:endpoint:/{projectKey}/recurring-payments/key={key}:POST).

## 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

[type definition](/search.md?urn=ctp:checkout:type:RecurringPaymentSetKeyUpdateAction).

#### Set Recurring Order

[type definition](/search.md?urn=ctp:checkout:type:RecurringPaymentSetRecurringOrderUpdateAction).

#### Set Payment Method Configuration

[type definition](/search.md?urn=ctp:checkout:type:RecurringPaymentSetPaymentMethodConfigurationUpdateAction).

#### Add Payment Method Configuration

[type definition](/search.md?urn=ctp:checkout:type:RecurringPaymentAddPaymentMethodConfigurationUpdateAction).

## Delete Recurring Payment

### Delete Recurring Payment by ID

[endpoint definition](/search.md?urn=ctp:checkout:endpoint:/{projectKey}/recurring-payments/{id}:DELETE).

### Delete Recurring Payment by Key

[endpoint definition](/search.md?urn=ctp:checkout:endpoint:/{projectKey}/recurring-payments/key={key}:DELETE).

## Sort results

When querying Recurring Payments, 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 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

**Basic sorting:**

```http title="Basic sorting"
GET /{projectKey}/recurring-payments?sort=createdAt%20desc
GET /{projectKey}/recurring-payments?sort=id%20asc
```

**Sorting with pagination:**

```http title="Sorting with pagination"
GET /{projectKey}/recurring-payments?sort=lastModifiedAt%20desc&limit=10&offset=0
```

## Representations

#### RecurringPayment

[type definition](/search.md?urn=ctp:checkout:type:RecurringPayment).

#### RecurringPaymentDraft

[type definition](/search.md?urn=ctp:checkout:type:RecurringPaymentDraft).

#### PaymentMethodConfiguration

[type definition](/search.md?urn=ctp:checkout:type:PaymentMethodConfiguration).

#### PaymentMethodReference

[type definition](/search.md?urn=ctp:checkout:type:PaymentMethodReference).

#### ConnectorDeploymentReference

[type definition](/search.md?urn=ctp:checkout:type:ConnectorDeploymentReference).

## Related pages

- [Area overview page with navigation](/checkout.md)
- [Previous page: Recurring Payment Jobs](/checkout/recurring-payment-jobs-api.md)
- [Next page: Transactions](/checkout/transactions-api.md)
- [Search documentation and API specs](/search.md)