# Customers

Track per-customer usage and costs by associating requests with your end-customers. This is useful when you're building on top of PromptShuttle and want to attribute costs to your own users.

## How it works

1. Pass a customer identifier with each request
2. PromptShuttle auto-creates a customer record on first use
3. View per-customer usage and cost breakdowns

## Identifying customers on requests

Pass the customer ID on any request via header or body field:

### Via header (all endpoints)

```bash
curl -X POST https://app.promptshuttle.com/api/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Shuttle-Customer-Id: customer_123" \
  -H "Content-Type: application/json" \
  -d '{ ... }'
```

### Via request body (flow execution)

```json
{
  "parameters": { "..." },
  "customerId": "customer_123"
}
```

The header takes precedence over the body field. The `user` field on the OpenAI endpoint also works as a fallback.

## Managing customers

### Create a customer

```bash
POST /api/v1/customers
```

```json
{
  "externalId": "customer_123",
  "name": "Acme Corp",
  "email": "contact@acme.com",
  "metadata": {
    "plan": "enterprise",
    "region": "eu"
  }
}
```

`externalId` must be unique within your tenant. This is the ID you pass in `X-Shuttle-Customer-Id`.

{% hint style="info" %}
Customers are auto-created when you pass an unknown `X-Shuttle-Customer-Id` or `customerId`. You only need to explicitly create customers if you want to set name, email, or metadata upfront.
{% endhint %}

### List customers

```bash
GET /api/v1/customers
```

### Get a customer

```bash
GET /api/v1/customers/{id}
```

### Update a customer

```bash
PUT /api/v1/customers/{id}
```

```json
{
  "name": "Acme Corporation",
  "metadata": { "plan": "enterprise", "region": "us" }
}
```

Only provided (non-null) fields are updated.

### Delete a customer

```bash
DELETE /api/v1/customers/{id}
```

### Deactivate a customer

Set `isActive: false` to exclude a customer from usage reports without deleting them:

```bash
PUT /api/v1/customers/{id}
```

```json
{ "isActive": false }
```

## Usage tracking

### Per-customer usage

```bash
GET /api/v1/customers/{id}/usage?period=30.00:00:00
```

Returns credits used, request count, and cost for the specified period (default 30 days).

### All customers usage

```bash
GET /api/v1/usage/by-customer?period=7.00:00:00
```

Returns usage summary grouped by all customers — useful for billing dashboards.

## Filtering logs by customer

The invocation log supports filtering by customer:

```bash
GET /api/v1/llm-logs?customerId=customer_123
```

This shows all requests attributed to that customer.