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

# Manage Customers

> Create, retrieve, list, and delete customer records and wallet payment methods.

## Customer Actions

### Create a Customer

Creates a new customer profile. Once the customer is created and a `customer_id` is returned, payment methods can be added to the customer's wallet.

```bash theme={null} theme={null}
POST /v1/customers
```

```json theme={null} theme={null}
{
  "first_name": "Jane",
  "last_name": "Smith",
  "email_address": "jane@example.com",
  "phone_number": "8005550100",
  "shipping_address": {
    "line1": "123 Main St",
    "city": "Austin",
    "state": "TX",
    "postal_code": "78701",
    "country": "US"
  },
  "metadata": {
    "account_id": "ACC-001234",
    "loyalty_tier": "gold",
    "store_location": "Austin-TX-01"
  }
}
```

```json theme={null} theme={null}
{
  "customer": {
    "id": "00000000-0000-0000-0000-000000000000",
    "first_name": "Jane",
    "last_name": "Smith",
    "email_address": "jane@example.com",
    "metadata": {
      "account_id": "ACC-001234",
      "loyalty_tier": "gold",
      "store_location": "Austin-TX-01"
    }
  },
  "request_id": "000000000000000000000"
}
```

Store the returned `id` -- it is required for all subsequent customer and wallet operations.

<Tip>
  Use `metadata` to attach any key-value data from your internal systems to a customer record. Common uses include internal account IDs, CRM references, loyalty tiers, and location codes. Metadata is returned on all API responses that include the customer object.
</Tip>

***

### Get a Customer

Retrieves a single customer record by ID.

```bash theme={null} theme={null}
GET /v1/customers/{Customer}
```

***

### List Customers

Returns all active customers on your account in descending order by creation date. Results are paginated with a default page size of 100.

```bash theme={null} theme={null}
GET /v1/customers
```

| Parameter | Type    | Description                                            |
| --------- | ------- | ------------------------------------------------------ |
| `Page`    | integer | Page number to retrieve. Default: `1`                  |
| `Size`    | integer | Number of results per page. Default: `100`, max: `100` |

***

### Delete a Customer

Permanently deletes a customer record and all associated wallet payment methods.

```bash theme={null} theme={null}
DELETE /v1/customers/{Customer}
```

<Warning>
  Deleting a customer invalidates all stored wallet tokens. Cancel any active subscriptions or installment plans linked to the customer before deletion.
</Warning>

***

## Wallet Actions

A customer wallet stores up to 4 payment methods. Payment methods are added to the wallet after the customer record is created using the customer's `id`.

### Add a Payment Method

Adds a credit card or ACH payment method to the customer's wallet. A payment method can be added using either a token from the `/v1/tokens` endpoint or the `transactionId` from a previously approved transaction.

```bash theme={null} theme={null}
POST /v1/customers/{Customer}/wallet
```

```json theme={null} theme={null}
{
  "token": "00000000-0000-0000-0000-000000000000",
  "default": true,
  "billing_address": {
    "line1": "123 Main St",
    "city": "Austin",
    "state": "TX",
    "postal_code": "78701",
    "country": "US"
  }
}
```

```json theme={null} theme={null}
{
  "wallet": {
    "id": "00000000-0000-0000-0000-000000000000",
    "network": "visa",
    "account_number": "4***********1111",
    "default": true
  },
  "request_id": "000000000000000000000"
}
```

***

### List Wallet Payment Methods

Returns all payment methods stored in the customer's wallet.

```bash theme={null} theme={null}
GET /v1/customers/{Customer}/wallet
```

| Parameter | Type    | Description                                            |
| --------- | ------- | ------------------------------------------------------ |
| `Page`    | integer | Page number to retrieve. Default: `1`                  |
| `Size`    | integer | Number of results per page. Default: `100`, max: `100` |

***

### Get a Wallet Payment Method

Retrieves a single wallet payment method by ID.

```bash theme={null} theme={null}
GET /v1/customers/{Customer}/wallet/{Wallet}
```

***

### Set Default Payment Method

Sets a wallet payment method as the default. The default payment method is used when charging a customer without specifying a wallet ID.

```bash theme={null} theme={null}
PUT /v1/customers/{Customer}/wallet/{Wallet}
```

```json theme={null} theme={null}
{
  "default": true
}
```

***

### Delete a Wallet Payment Method

Removes a payment method from the wallet and invalidates its token.

```bash theme={null} theme={null}
DELETE /v1/customers/{Customer}/wallet/{Wallet}
```

***

## Next Steps

With your customer profiles and wallet payment methods in place, you're ready to start charging customers on file.

<Card title="Charge Customer Wallet" icon="credit-card" href="/docs/charge-customer-wallet">
  Learn how to charge a customer's default or saved payment method, including one-time payments, subscriptions, and installment billing.
</Card>

<Card title="Create Subscriptions and Installment Plans" icon="sparkles">
  Learn how to create ongoing subscriptions or break up large payments into installment plans with customer wallets. 
</Card>