# Managing Customers

A customer record in ODUS represents a person or organization you charge. Each record holds contact information — name, email, phone number, and addresses. Payments, subscriptions, and saved payment methods reference the customer by its `id` (prefixed `cus_`).

## Prerequisites

* A valid ODUS secret key with the `customer:update` permission to update customers, and `customer:read` to find them.

## How customers are created

v2 has no endpoint for creating a customer. A customer record is created when a shopper pays through the [Checkout SDK](https://docs.odus.com/docs/guides/checkout/.md), from the details collected at checkout.

To charge a returning customer, pass their `id` as `customer` when you [create a payment](https://docs.odus.com/docs/guides/payments/making-payments.md). To find that `id`, [look the customer up](#find-and-filter-customers) by email.

## Update a customer

Send a [`POST /v2/customers/{id}`](https://docs.odus.com/docs/api/core/v2/customer-controller-update) request with the fields you want to change. All fields are optional — only the fields you include will be updated.

```
{

  "name": "Jane Doe",

  "phoneNumber": "+15559876543"

}
```

### Updating metadata

The `metadata` field is merged with any existing metadata on every update. Only the keys you include are changed — existing keys that you do not mention are preserved. To remove a specific key, set its value to an empty string. To clear all metadata at once, send `null`.

```
{

  "metadata": {

    "internalAccountId": "acct_9870",

    "tier": "premium"

  }

}
```

note

Metadata is for your own use only. ODUS does not use metadata values in any processing logic.

## View a customer in the Dashboard

1. In the Dashboard, go to **Customers**.
2. Click a customer row to open the customer detail page.

The detail page shows:

* **Subscriptions** — all subscriptions linked to this customer.
* **Payments** — all payment attempts associated with this customer.
* **Payment methods** — saved cards and other payment methods stored for this customer.
* **Customer details** — contact information and editable metadata, displayed in the right sidebar.

To edit the customer's name, email, phone number, or address, click **Edit** on the customer card at the top of the page. To remove a stored phone number, clear the field and save.

To edit metadata directly in the Dashboard, use the metadata editor in the **Customer details** sidebar and save your changes.

## Find and filter customers

### Dashboard

On the **Customers** list page, use the filter bar to narrow results:

| Filter       | Description                             |
| ------------ | --------------------------------------- |
| Email        | Exact or partial match on email address |
| Name         | Exact or partial match on display name  |
| Created Date | Filter by creation date range           |

Click any row to open that customer's detail page.

### API

Use [`GET /v2/customers`](https://docs.odus.com/docs/api/core/v2/customer-controller-find-all-paginated) with query parameters to filter results. Text filters such as `email` and `name` support `eq`, `ne`, `like`, `ilike`, `in` and `nin`. `id` is matched whole and accepts `eq`, `ne`, `in` and `nin`.

Look a customer up by email with `eq`. ODUS stores email addresses in lowercase and lowercases the value you send, so the case does not matter:

```
GET /v2/customers?email[eq]=jane@example.com
```

Every other string filter is case-sensitive, and `like` matches the start of a value. To match any part of a value in any case, use `ilike` and wrap the value in `%` wildcards, encoded as `%25`:

```
GET /v2/customers?name[ilike]=%25smith%25&sortDirection=desc&limit=20
```

warning

A filter whose case does not match the stored value returns an empty page, not an error. Use `ilike` for names and other values people type.

The response is paged by cursor. To fetch the next page, send the returned `pagination.nextCursor` as `cursor`.

See [Pagination, Filtering, and Sorting](https://docs.odus.com/docs/guides/api-features/pagination-filtering-sorting.md#customers) for the full list of supported filter fields and operators.

## Read a customer's payment methods and subscriptions

A v2 customer object does not include the customer's payment methods or subscriptions. Read each from its own list endpoint, filtered by the customer's `id`:

```
GET /v2/payment-methods?customer[eq]=cus_2R0uWz4tu9wxTMBXxj9CJfSE9vV

GET /v2/subscriptions?customer[eq]=cus_2R0uWz4tu9wxTMBXxj9CJfSE9vV
```

Your key needs `payment_method:read` and `subscription:read` for these requests.