> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stellartools.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Customers

> Create and manage customers

A customer represents a person or entity that pays through StellarTools. Customers hold wallets, subscriptions, and payment history.

## The customer object

<ResponseField name="id" type="string">
  Unique identifier. Prefixed with `cus_`.
</ResponseField>

<ResponseField name="object" type="string">
  Always `"customer"`.
</ResponseField>

<ResponseField name="email" type="string">
  Email address of the customer.
</ResponseField>

<ResponseField name="name" type="string">
  Full name of the customer.
</ResponseField>

<ResponseField name="phone" type="string">
  Phone number of the customer.
</ResponseField>

<ResponseField name="image" type="string">
  URL to the customer's profile image.
</ResponseField>

<ResponseField name="wallets" type="array">
  Stellar wallets linked to this customer.

  <Expandable title="wallet fields">
    <ResponseField name="id" type="string">
      Unique identifier for the wallet. Prefixed with `cwl_`.
    </ResponseField>

    <ResponseField name="address" type="string">
      The Stellar public key.
    </ResponseField>

    <ResponseField name="metadata" type="object">
      Arbitrary key-value metadata.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="metadata" type="object">
  Arbitrary key-value data you can attach to the customer.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp.
</ResponseField>

<ResponseField name="updated_at" type="string">
  ISO 8601 timestamp.
</ResponseField>

***

## Create a customer

`POST /customers`

Creates one customer. You can also pass an array to create multiple at once.

```bash theme={null}
curl https://api.stellartools.dev/customers \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "jane@example.com", "name": "Jane Smith" }'
```

### Body

<ParamField body="email" type="string" required>
  Customer's email address.
</ParamField>

<ParamField body="name" type="string" required>
  Customer's full name.
</ParamField>

<ParamField body="phone" type="string">
  Customer's phone number.
</ParamField>

<ParamField body="image" type="string">
  URL to a profile image.
</ParamField>

<ParamField body="metadata" type="object">
  Arbitrary key-value string pairs to attach to the customer.
</ParamField>

***

## List customers

`GET /customers`

Returns all customers for your account.

```bash theme={null}
curl https://api.stellartools.dev/customers \
  -H "x-api-key: YOUR_API_KEY"
```

Returns a [list object](/api-reference/introduction#pagination) containing customer objects.

***

## Retrieve a customer

`GET /customers/{customer_id}`

```bash theme={null}
curl https://api.stellartools.dev/customers/cus_01jx... \
  -H "x-api-key: YOUR_API_KEY"
```

***

## Update a customer

`PUT /customers/{customer_id}`

```bash theme={null}
curl -X PUT https://api.stellartools.dev/customers/cus_01jx... \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Jane Doe" }'
```

### Body

<ParamField body="email" type="string">
  New email address.
</ParamField>

<ParamField body="name" type="string">
  New name.
</ParamField>

<ParamField body="phone" type="string">
  New phone number.
</ParamField>

<ParamField body="image" type="string">
  New image URL.
</ParamField>

<ParamField body="metadata" type="object">
  Merged with existing metadata.
</ParamField>

***

## Delete a customer

`DELETE /customers/{customer_id}`

Returns `null` on success.

```bash theme={null}
curl -X DELETE https://api.stellartools.dev/customers/cus_01jx... \
  -H "x-api-key: YOUR_API_KEY"
```