Customers

Search the book, read one customer, and pull their movement and invoice history.

List customers

GET/api/v1/customers

Every customer the workspace knows about, newest cursor first, with their current MRR. Filters combine, so a status and a query narrow together.

Query parameters

per_page integer	1 to 200. Defaults to 50.
cursor string	Opaque cursor from the previous page.
status string	active or cancelled.
email string	Exact match, case insensitive.
external_id string	Exact match on the id from your billing source.
q string	Substring search across name, email and external id.

curl -G https://kometrics.com/api/v1/customers \
  -H "Authorization: Bearer ko_your_api_key" \
  -d status=active \
  -d per_page=2

Privacy mode

A workspace can run in anonymized mode, where customer emails are never stored. Those responses drop the email field entirely and carry "anonymized": true in its place, so an integration can tell a missing email from a withheld one.

{
  "external_id": "cus_9QK2mFvR",
  "name": "Acme Cloud",
  "anonymized": true,
  "country": "US",
  "source": "stripe",
  "status": "active",
  "mrr": 29900,
  "arr": 358800,
  "customer-since": "2025-03-14",
  "last-activity": "2026-08-01"
}

Retrieve a customer

GET/api/v1/customers/{external_id}

One customer with their subscriptions attached. Responds 404 when the external id is not in this workspace.

Additional fields

subscriber-since YYYY-MM-DD \| null	When their paid life started.
net-payments integer	Everything they have paid, net of refunds, in cents.
subscriptions array	One object per subscription, shown opposite.

curl https://kometrics.com/api/v1/customers/cus_9QK2mFvR \
  -H "Authorization: Bearer ko_your_api_key"

Activities and invoices

GET/api/v1/customers/{external_id}/activities

GET/api/v1/customers/{external_id}/invoices

One customer's full MRR movement history, and their full invoice history. Both return everything in a single response and always report has_more: false, so neither takes pagination parameters.

curl https://kometrics.com/api/v1/customers/cus_9QK2mFvR/invoices \
  -H "Authorization: Bearer ko_your_api_key"