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

# Customers

> Create and manage customers for your account. Customers are the entities that make cryptocurrency payments for your products and services.

This API allows you to create and manage customers for your account. Customers are the entities that will make cryptocurrency payments for your products and services.

## The customer object

<ResponseField name="id" type="string">
  Unique identifier with `cust_` prefix (e.g., `cust_abc123def456`).
</ResponseField>

<ResponseField name="email" type="string">
  The customer's email address. Automatically converted to lowercase.
</ResponseField>

<ResponseField name="first_name" type="string">
  The customer's first name.
</ResponseField>

<ResponseField name="last_name" type="string">
  The customer's last name.
</ResponseField>

<ResponseField name="created_at" type="string">
  When the customer was created (ISO 8601).
</ResponseField>

<ResponseField name="updated_at" type="string">
  When the customer was last updated (ISO 8601).
</ResponseField>

## List customers

```
GET /v1/customers
```

Retrieves a paginated list of all customers in your account.

<ParamField query="page" type="integer" default="1">
  Page number for pagination. Results are returned 25 items per page.
</ParamField>

```bash theme={null}
curl https://api.gettrxn.com/v1/customers \
  -H "Authorization: Bearer $TRXN_TOKEN"
```

```json Response theme={null}
{
  "customers": [
    {
      "id": "cust_abc123def456",
      "email": "john.doe@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "created_at": "2024-01-01T12:00:00Z",
      "updated_at": "2024-01-01T12:00:00Z"
    },
    {
      "id": "cust_xyz789ghi012",
      "email": "jane.smith@example.com",
      "first_name": "Jane",
      "last_name": "Smith",
      "created_at": "2024-01-02T10:30:00Z",
      "updated_at": "2024-01-02T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pages": 3,
    "count": 67
  }
}
```

## Get customer

```
GET /v1/customers/:id
```

Retrieves a specific customer by ID.

<ParamField path="id" type="string" required>
  The customer's ID (e.g., `cust_abc123def456`).
</ParamField>

```bash theme={null}
curl https://api.gettrxn.com/v1/customers/cust_abc123def456 \
  -H "Authorization: Bearer $TRXN_TOKEN"
```

```json Response theme={null}
{
  "id": "cust_abc123def456",
  "email": "john.doe@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "created_at": "2024-01-01T12:00:00Z",
  "updated_at": "2024-01-01T12:00:00Z"
}
```

## Create customer

```
POST /v1/customers
```

Creates a new customer in your account. A cryptocurrency wallet is automatically created for the customer.

<ParamField body="email" type="string" required>
  The customer's email address. Must be a valid email format. Automatically converted to lowercase. Must be unique within your account.
</ParamField>

<ParamField body="first_name" type="string">
  The customer's first name.
</ParamField>

<ParamField body="last_name" type="string">
  The customer's last name.
</ParamField>

```bash theme={null}
curl -X POST https://api.gettrxn.com/v1/customers \
  -H "Authorization: Bearer $TRXN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "new.customer@example.com",
    "first_name": "New",
    "last_name": "Customer"
  }'
```

```json Response theme={null}
{
  "id": "cust_new123customer456",
  "email": "new.customer@example.com",
  "first_name": "New",
  "last_name": "Customer",
  "created_at": "2024-01-15T14:30:00Z",
  "updated_at": "2024-01-15T14:30:00Z"
}
```

### Validation errors

```json Email cannot be blank theme={null}
{
  "errors": {
    "email": ["can't be blank"]
  }
}
```

```json Invalid email format theme={null}
{
  "errors": {
    "email": ["is invalid"]
  }
}
```

```json Duplicate email theme={null}
{
  "errors": {
    "email": ["has already been taken"]
  }
}
```

## Update customer

```
PATCH /v1/customers/:id
```

Updates an existing customer.

<ParamField path="id" type="string" required>
  The customer's ID (e.g., `cust_abc123def456`).
</ParamField>

<ParamField body="email" type="string">
  The customer's email address. Must be a valid email format.
</ParamField>

<ParamField body="first_name" type="string">
  The customer's first name.
</ParamField>

<ParamField body="last_name" type="string">
  The customer's last name.
</ParamField>

```bash theme={null}
curl -X PATCH https://api.gettrxn.com/v1/customers/cust_abc123def456 \
  -H "Authorization: Bearer $TRXN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "updated.email@example.com",
    "first_name": "Updated"
  }'
```

```json Response theme={null}
{
  "id": "cust_abc123def456",
  "email": "updated.email@example.com",
  "first_name": "Updated",
  "last_name": "Doe",
  "created_at": "2024-01-01T12:00:00Z",
  "updated_at": "2024-01-15T16:45:00Z"
}
```

## Delete customer

```
DELETE /v1/customers/:id
```

Deletes a customer from your account.

<Warning>
  This action is irreversible and will also delete the customer's associated wallet and crypto addresses.
</Warning>

<ParamField path="id" type="string" required>
  The customer's ID (e.g., `cust_abc123def456`).
</ParamField>

```bash theme={null}
curl -X DELETE https://api.gettrxn.com/v1/customers/cust_abc123def456 \
  -H "Authorization: Bearer $TRXN_TOKEN"
```

Returns `204 No Content` on successful deletion.

## Customer features

### Automatic wallet creation

When a customer is created, a cryptocurrency wallet is automatically created for them. This wallet can hold multiple cryptocurrency addresses for receiving payments.

### Email validation

* Email addresses must be in a valid format.
* Email addresses are automatically converted to lowercase.
* Email addresses must be unique within your account (but can be duplicated across different accounts).

### Prefixed IDs

All customer IDs are returned with the prefix `cust_` followed by a unique identifier (e.g., `cust_abc123def456`). This makes it easy to identify customer IDs in your application.

## Pagination

By default, the API returns 25 customers per page. Use the `page` query parameter to navigate through pages.

The `pagination` object in the response includes:

<ResponseField name="page" type="integer">
  Current page number.
</ResponseField>

<ResponseField name="pages" type="integer">
  Total number of pages.
</ResponseField>

<ResponseField name="count" type="integer">
  Total number of items across all pages.
</ResponseField>

## Integration example

```bash theme={null}
# 1. Create a customer
curl -X POST https://api.gettrxn.com/v1/customers \
  -H "Authorization: Bearer $TRXN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "customer@example.com", "first_name": "John", "last_name": "Doe"}'

# Response: {"id": "cust_abc123def456", ...}

# 2. Create a payment claim link for the customer
curl -X POST https://api.gettrxn.com/v1/payment_claim_links \
  -H "Authorization: Bearer $TRXN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"customer_id": "cust_abc123def456"}'

# 3. Send the payment link to the customer
# 4. Customer submits payment information
# 5. Review and approve the payment claim
```

## Sandbox support

<Note>
  The API respects sandbox scoping. If your API token is associated with a sandbox, you can only access customers created in that sandbox. Email uniqueness is enforced separately within each sandbox.
</Note>