> For the complete documentation index, see [llms.txt](https://plexo.gitbook.io/rest-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://plexo.gitbook.io/rest-api/customers-and-saved-methods/recurring-payments.md).

# Recurring Payments Guide

Build recurring billing on top of customers, tokenization, and regular payment creation.

## Overview

The public API does not document a dedicated subscriptions scheduler. Instead, recurring billing is assembled from these primitives:

* Customers: `POST /v1/customers`
* Tokenization sessions: `POST /v1/sessions` with `"type": "tokenization"`
* Saved instrument management: `GET` and `DELETE /v1/customers/{customerId}/payment-instruments`
* Charges against saved instruments: `POST /v1/payments`

The public contract also does not document a "set default payment instrument" endpoint. If you need a preferred card, choose it in your own application logic.

Use this guide for charging saved instruments on your own billing schedule. For the reusable-card collection flow itself, use [Tokenization Guide](/rest-api/customers-and-saved-methods/tokenization-guide.md).

## Recommended Recurring Flow

### 1. Create the customer

```http
POST /v1/customers
Authorization: Basic {credentials}
Content-Type: application/json

{
  "referenceId": "subscriber-1001",
  "email": "subscriber@example.com",
  "firstName": "Test",
  "lastName": "Subscriber"
}
```

### 2. Collect a reusable payment instrument

Create a tokenization session and associate it with the customer.

```http
POST /v1/sessions
Authorization: Basic {credentials}
Content-Type: application/json

{
  "merchantId": 12345,
  "referenceId": "subscription-setup-1001",
  "type": "tokenization",
  "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "settings": {
    "tokenization": {
      "type": "store",
      "allowedCardTypes": ["credit", "debit"],
      "features": ["create", "list", "select", "delete"]
    },
    "callbacks": {
      "tokenizationCallbackUrl": "https://merchant.example.com/callbacks/tokenization"
    }
  }
}
```

After the hosted flow completes, read the customer's instruments and persist the token reference in your subscription system.

### 3. Charge the saved instrument

```http
POST /v1/payments
Authorization: Basic {credentials}
Content-Type: application/json

{
  "merchantId": 12345,
  "referenceId": "subscription-charge-2026-03",
  "invoiceNumber": "SUB-2026-03-1001",
  "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "amount": {
    "total": 10000,
    "currency": "UYU"
  },
  "paymentMethod": {
    "source": "token",
    "paymentInstrument": {
      "token": "9b7f1c2e-4a3d-4e8b-9c1f-2d3e4f5a6b7c"
    }
  },
  "capture": {
    "method": "automatic"
  },
  "metadata": {
    "subscriptionId": "sub-1001",
    "billingCycle": "2026-03"
  }
}
```

## Alternative: Save the Card During the First Charge

If the first order should charge the card and store it for future renewals, create the payment with `paymentMethod.card.tokenizationSettings` and a `customerId`. After the payment succeeds, read the customer's instruments to get the reusable token.

## Failure Handling

Recurring billing logic lives in your system, so plan for asynchronous failures and retries.

* Use unique `referenceId` and `invoiceNumber` values for every billing attempt
* Store the payment `id` and final `status` from each cycle
* Retry according to your own billing rules, not by reusing the same payment record
* If a token stops working, send the customer back through a tokenization session to replace it

## Updating the Payment Method

The supported public replacement flow is:

1. Create a new tokenization session for the customer
2. Read the new token from `GET /v1/customers/{customerId}/payment-instruments`
3. Update your subscription record to use the new token
4. Optionally delete the old token with `DELETE /v1/customers/{customerId}/payment-instruments/{tokenId}`

## Best Practices

* Store the Plexo `customerId` and instrument token alongside your subscription record
* Keep recurring retries idempotent in your own scheduler
* Prefer hosted tokenization over collecting card data on your server
* Use `metadata` to store subscription identifiers for reconciliation
* Re-query the customer instruments list before assuming a token is still active

## Related Resources

* [Tokenization Guide](/rest-api/customers-and-saved-methods/tokenization-guide.md)
* [Customer Management](/rest-api/customers-and-saved-methods/customer-management.md)
* [Payment Processing](/rest-api/payments/payment-processing.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://plexo.gitbook.io/rest-api/customers-and-saved-methods/recurring-payments.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.