> ## 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.

# Customers Overview

> Manage your end customers — create profiles, track usage, and view billing history.

In Fluxrate, a **Customer** represents one of your end users or companies. Each customer can have subscriptions, usage history, and invoices.

## Creating a Customer

<Tabs>
  <Tab title="Dashboard">
    1. Go to **Customers** in the sidebar
    2. Click **Add Customer**
    3. Fill in name, email, and optional external ID
    4. Click **Save**
  </Tab>

  <Tab title="API">
    ```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",
        "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"
      }'
    ```
  </Tab>
</Tabs>

## Customer Fields

| Field               | Required      | Description                                          |
| ------------------- | ------------- | ---------------------------------------------------- |
| `name`              | ✅             | Customer display name                                |
| `email`             | ✅             | Billing contact email                                |
| `external_id`       |               | Your own system's customer ID (used in SDK tracking) |
| `phone`             |               | Customer phone number                                |
| `billing_address_*` | For invoicing | Used for tax calculation                             |

<Note>
  A **billing address with `country`** is required to create manual invoices (needed for tax calculation). Add it when creating the customer or update it before creating their first invoice.
</Note>

## External ID

The `external_id` is the bridge between your system and Fluxrate. When sending usage events via the SDK, you reference customers by their `external_id`:

```json theme={null}
{
  "meter_token": "...",
  "customer_external_id": "acme-corp-001",
  "quantity": 100
}
```

Use your existing customer identifier (user ID, account ID, etc.) as the `external_id` to avoid maintaining ID mappings.

## Customer Subscriptions

View all subscriptions for a customer:

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

## Customer Invoices

View all invoices for a customer:

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

## Customer Usage

View aggregated usage across all meters for a customer:

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

## Listing Customers

```bash theme={null}
GET /api/v1/customers?page=1&page_size=20
```

Response includes pagination metadata and a list of customer objects.