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

# Managing Customers

> Create, update, search, and delete customers in Fluxrate.

## CRUD Operations

### Create

```bash theme={null}
curl -X POST https://api.fluxrate.co/api/v1/customers \
  -H "Content-Type: application/json" \
  -H "Cookie: access_token=<token>" \
  -d '{
    "name": "Acme Corp",
    "email": "billing@acme.com",
    "external_id": "acme-corp-001"
  }'
```

### Read

```bash theme={null}
# Get by ID
GET /api/v1/customers/<customer_id>

# List with pagination
GET /api/v1/customers?page=1&page_size=20
```

### Update

```bash theme={null}
curl -X PUT https://api.fluxrate.co/api/v1/customers/<customer_id> \
  -H "Content-Type: application/json" \
  -H "Cookie: access_token=<token>" \
  -d '{
    "name": "Acme Corporation",
    "billing_address_country": "US",
    "billing_address_state": "CA"
  }'
```

### Delete

```bash theme={null}
DELETE /api/v1/customers/<customer_id>
```

<Warning>
  Deleting a customer is permanent and will cascade-delete their subscriptions and associated data. Consider marking customers as inactive instead of deleting them.
</Warning>

## Customer Response Object

```json theme={null}
{
  "id": "550e8400-...",
  "organization_id": "...",
  "name": "Acme Corp",
  "email": "billing@acme.com",
  "external_id": "acme-corp-001",
  "phone": "+1-555-0100",
  "billing_address_line1": "123 Main St",
  "billing_address_city": "San Francisco",
  "billing_address_state": "CA",
  "billing_address_country": "US",
  "billing_address_postal_code": "94105",
  "created_at": "2025-01-01T00:00:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}
```

## Pagination

All list endpoints support pagination:

| Parameter   | Default | Description              |
| ----------- | ------- | ------------------------ |
| `page`      | 1       | Page number (1-indexed)  |
| `page_size` | 20      | Items per page (max 100) |

Response includes:

```json theme={null}
{
  "data": [...],
  "meta": {
    "page": 1,
    "page_size": 20,
    "total": 342,
    "total_pages": 18
  }
}
```