> 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
* `firstName`, `lastName`, and `email` are optional on create and update; a supplied `email` must be syntactically valid
* `identification.value` and the legacy `document.value` field use the [document normalization rules](/rest-api/api-reference/models.md#documentdto): send a string; Plexo removes symbols and whitespace while preserving letters, digits, casing, and leading zeros. A value that becomes empty returns HTTP `400`.
* Updates replace the submitted profile; omitted optional fields are cleared
* 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",
  "firstName": "Updated",
  "lastName": "User",
  "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)