# Customers

> Create and manage customers shared across products.

Customers store a buyer's identity and default payment details. A single customer record is shared
across payments, subscriptions, invoices, and loyalty — attach a payment method once and reference
the customer everywhere.

> **Illustrative content.** Hand-authored to demonstrate the Standard/Advanced pattern; the production
> page will be generated from the VINR OpenAPI spec (roadmap item #1). Field names are representative.

## The customer object

- **id** `string` — Unique identifier for the customer, e.g. `cust_8aZ2`.
- **email** `string` — The customer's email address.
- **name** `string` — The customer's full name.
- **phone** `string` — The customer's phone number in E.164 format, e.g. `+14155552671`.
- **default\_payment\_method** `object` (expandable) — The default payment method for this customer. Expand to retrieve the full object.
  - **id** `string` — Payment method identifier, e.g. `pm_9bR3`.
  - **type** `string` — Instrument type, e.g. `card`.
  - **card** `object` — Card details snapshot (brand, last4, exp\_month, exp\_year).
- **created** `integer` — Unix timestamp when the customer was created.

## Create a customer

Pass an email and optional name and phone. VINR returns a customer object you can attach payment
methods to and reference on future payments and subscriptions.

`POST /v1/customers`

```bash
curl -X POST https://api.vinr.com/v1/customers \
-H "X-Api-Key: $VINR_SECRET_KEY" \
-d email=jenny@example.com \
-d name="Jenny Rosen" \
-d phone=+14155552671
```

```js
import { Vinr } from '@vinr/sdk';

const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

const customer = await vinr.customers.create({
email: 'jenny@example.com',
name: 'Jenny Rosen',
phone: '+14155552671',
});
```

```python
import vinr

customer = vinr.Customer.create(
  email="jenny@example.com",
  name="Jenny Rosen",
  phone="+14155552671",
)
```

```ruby
customer = Vinr::Customer.create(
email: 'jenny@example.com',
name: 'Jenny Rosen',
phone: '+14155552671',
)
```

```json
{
"id": "cust_8aZ2",
"email": "jenny@example.com",
"name": "Jenny Rosen",
"phone": "+14155552671",
"default_payment_method": null,
"created": 1716300000
}
```

## Retrieve a customer

`GET /v1/customers/{id}`

```bash
curl https://api.vinr.com/v1/customers/cust_8aZ2 \
-H "X-Api-Key: $VINR_SECRET_KEY"
```

```js
const customer = await vinr.customers.retrieve('cust_8aZ2');
```

```python
customer = vinr.Customer.retrieve("cust_8aZ2")
```

```ruby
customer = Vinr::Customer.retrieve("cust_8aZ2")
```

```json
{
"id": "cust_8aZ2",
"email": "jenny@example.com",
"name": "Jenny Rosen",
"phone": "+14155552671",
"default_payment_method": "pm_9bR3",
"created": 1716300000
}
```

## Update a customer

Send any subset of fields — only the fields you pass are changed.

`POST /v1/customers/{id}`

```bash
curl -X POST https://api.vinr.com/v1/customers/cust_8aZ2 \
-H "X-Api-Key: $VINR_SECRET_KEY" \
-d email=jenny.rosen@example.com
```

```js
const customer = await vinr.customers.update('cust_8aZ2', {
email: 'jenny.rosen@example.com',
});
```

```python
customer = vinr.Customer.modify(
  "cust_8aZ2",
  email="jenny.rosen@example.com",
)
```

```ruby
customer = Vinr::Customer.update(
"cust_8aZ2",
email: 'jenny.rosen@example.com',
)
```

```json
{
"id": "cust_8aZ2",
"email": "jenny.rosen@example.com",
"name": "Jenny Rosen",
"phone": "+14155552671",
"default_payment_method": "pm_9bR3",
"created": 1716300000
}
```

## Delete a customer

Deletes the customer and unlinks them from future charges. Active subscriptions must be canceled
first.

`DELETE /v1/customers/{id}`

```bash
curl -X DELETE https://api.vinr.com/v1/customers/cust_8aZ2 \
-H "X-Api-Key: $VINR_SECRET_KEY"
```

```js
const deleted = await vinr.customers.delete('cust_8aZ2');
```

```python
deleted = vinr.Customer.delete("cust_8aZ2")
```

```ruby
deleted = Vinr::Customer.delete("cust_8aZ2")
```

```json
{
"id": "cust_8aZ2",
"deleted": true
}
```

## List customers

Returns a paginated list of customers. Filter by `email` to look up a specific buyer.

`GET /v1/customers`

```bash
curl "https://api.vinr.com/v1/customers?email=jenny%40example.com&limit=10" \
-H "X-Api-Key: $VINR_SECRET_KEY"
```

```js
const customers = await vinr.customers.list({
email: 'jenny@example.com',
limit: 10,
});
```

```python
customers = vinr.Customer.list(
  email="jenny@example.com",
  limit=10,
)
```

```ruby
customers = Vinr::Customer.list(
email: 'jenny@example.com',
limit: 10,
)
```

```json
{
"object": "list",
"data": [
  {
    "id": "cust_8aZ2",
    "email": "jenny@example.com",
    "name": "Jenny Rosen",
    "phone": "+14155552671",
    "default_payment_method": "pm_9bR3",
    "created": 1716300000
  }
],
"has_more": false
}
```

## Related events

`customer.created`, `customer.updated`, `customer.deleted`. See [Events](/docs/api-reference/events).