Customers API

Manage the customers whose usage you are tracking.

List customers

GET/v1/customers

Returns all customers for the authenticated tenant. Supports cursor-based pagination with page_size and page_token query parameters.

Response is a PaginatedList: { "data": [...], "has_more": false, "next_page_token": null }

Create a customer

POST/v1/customers

Field	Type	Required	Description
`external_id`	string	Yes	Your system's customer identifier
`name`	string	No	Display name
`metadata`	object	No	Arbitrary key-value data
`billing_provider_id`	string	No	Stripe customer ID or similar

Example

bash

curl -X POST https://api.meterd.io/v1/customers \
  -H "Authorization: Bearer mtd_adm_..." \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "cust_stripe_123",
    "name": "Acme Corp",
    "metadata": { "plan": "pro", "region": "us-east-1" }
  }'

Response

json

{
  "id": "01HQXYZ...",
  "tenant_id": "01HQABC...",
  "external_id": "cust_stripe_123",
  "name": "Acme Corp",
  "billing_provider_id": null,
  "metadata": { "plan": "pro", "region": "us-east-1" },
  "created_at": "2024-01-15T10:00:00Z"
}

Get a customer

GET/v1/customers/:external_id

Retrieve a customer by their external ID.

Lookup customer by external ID

GET/v1/customers/by-external-id?external_id=...

Look up a customer by their external ID using a query parameter. Useful when the external ID contains characters that are not URL-path safe.

Upsert a customer

PUT/v1/customers/:external_id/upsert

Create or update a customer by external ID. Useful for keeping Meterd in sync with your customer database.

This is the recommended approach for syncing customers from your application — call upsert on every relevant user action and let Meterd handle the create-or-update logic.