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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.promptshuttle.com/api-reference/customers.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.