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)

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)

{
  "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

POST /api/v1/customers

{
  "externalId": "customer_123",
  "name": "Acme Corp",
  "email": "[email protected]",
  "metadata": {
    "plan": "enterprise",
    "region": "eu"
  }
}

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

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.

List customers

GET /api/v1/customers

Get a customer

GET /api/v1/customers/{id}

Update a customer

PUT /api/v1/customers/{id}

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

Only provided (non-null) fields are updated.

Delete a customer

DELETE /api/v1/customers/{id}

Deactivate a customer

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

PUT /api/v1/customers/{id}

{ "isActive": false }

Usage tracking

Per-customer usage

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

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:

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

This shows all requests attributed to that customer.