> 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/customer-management.md).

# Customer Management Guide

Use the Customers API to create customer records and manage their saved payment instruments.

## Overview

The public customer surface supports:

* Create, list, retrieve, update, and delete customers
* List a customer's saved payment instruments
* Delete a saved payment instrument
* Associate customers with payment and session flows

New payment instruments are created indirectly through tokenization or payment flows. The public API does not document a direct "create payment instrument" endpoint or a "set default payment instrument" operation.

Use this guide for customer CRUD and saved-instrument retrieval or removal. For collecting a new instrument, use [Tokenization Guide](/rest-api/customers-and-saved-methods/tokenization-guide.md). For charging saved instruments on a schedule, use [Recurring Payments](/rest-api/customers-and-saved-methods/recurring-payments.md).

## Create a Customer

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

{
  "referenceId": "customer-1001",
  "email": "customer@example.com",
  "firstName": "Test",
  "lastName": "User",
  "phone": "+59899123456",
  "metadata": {
    "segment": "premium",
    "crmId": "CRM-1001"
  }
}
```

Notes:

* `referenceId` should be unique within your client scope when you send it
* At least one identifying field should be provided
* The response returns the Plexo `id` you will use in later calls

## Read and Update Customers

Use these endpoints for day-to-day customer management:

* `GET /v1/customers`
* `GET /v1/customers/{customerId}`
* `PUT /v1/customers/{customerId}`
* `DELETE /v1/customers/{customerId}`

Example update:

```http
PUT /v1/customers/3fa85f64-5717-4562-b3fc-2c963f66afa6
Authorization: Basic {credentials}
Content-Type: application/json

{
  "email": "updated@example.com",
  "phone": "+59899123457",
  "metadata": {
    "segment": "gold"
  }
}
```

## Manage Saved Payment Instruments

### List instruments

```http
GET /v1/customers/3fa85f64-5717-4562-b3fc-2c963f66afa6/payment-instruments
Authorization: Basic {credentials}
```

Example response:

```json
[
  {
    "token": "9b7f1c2e-4a3d-4e8b-9c1f-2d3e4f5a6b7c",
    "name": "4242",
    "type": "credit",
    "issuer": {
      "id": 1,
      "name": "VISA"
    },
    "expMonth": 12,
    "expYear": 2028,
    "status": "Ok",
    "tokenizationType": "persistent"
  }
]
```

### Delete an instrument

```http
DELETE /v1/customers/3fa85f64-5717-4562-b3fc-2c963f66afa6/payment-instruments/9b7f1c2e-4a3d-4e8b-9c1f-2d3e4f5a6b7c
Authorization: Basic {credentials}
```

Use tokenization sessions or payment flows with tokenization enabled when you need to add a new instrument.

## Use Customers in Payments and Sessions

### Payments

Attach `customerId` to a payment when the charge belongs to an existing customer.

```json
{
  "merchantId": 12345,
  "referenceId": "order-1001",
  "invoiceNumber": "INV-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"
  }
}
```

### Sessions

Attach `customerId` to a checkout or tokenization session so saved instruments remain associated with the same customer record.

```json
{
  "merchantId": 12345,
  "referenceId": "session-1001",
  "type": "tokenization",
  "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "settings": {
    "tokenization": {
      "type": "store"
    }
  }
}
```

## Best Practices

* Use your own `referenceId` to map Plexo customers to your internal records
* Keep customer records lightweight and avoid unnecessary PII in `metadata`
* Reuse the same `customerId` across tokenization and recurring payment flows
* Read the current instrument list before charging a stored token
* Let customers re-enter card details through tokenization when they need to replace a saved card

## Related Resources

* [Tokenization Guide](/rest-api/customers-and-saved-methods/tokenization-guide.md)
* [Recurring Payments](/rest-api/customers-and-saved-methods/recurring-payments.md)
* [CustomerDto](/rest-api/api-reference/models.md#customerdto)


---

# 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/customer-management.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.