Usage

A per-customer spend report

Usage is a per-customer spend report over a date range, broken down by credential source (customer BYOK, org BYOK, or Merge-managed) and by model, provider, and routing policy. Use it to bill your own customers or to reconcile spend.

Path: /v1/customers/{customer_id}/usage. See Checking usage on the overview for the request; this page documents the response fields.

Fields

Field	Description	Type
`customer_byok_spend`	Spend billed against the customer’s own provider keys	number
`organization_byok_spend`	Spend billed against your organization’s provider keys	number
`merge_spend`	Spend billed against Merge-managed credentials	number
`request_count`	Number of requests	integer
`per_model` / `per_provider` / `per_routing_policy`	Spend breakdowns, sorted by spend descending	list of `{…, spend}`

The three spend fields are disjoint: their sum is the customer’s total spend for the range.

Org-wide usage

GET /v1/customers/usage returns one row per customer seen across your organization for the range, sorted by total spend descending, which is the call to make when reconciling a whole billing run rather than one tenant.

cURL

$ curl "https://api-gateway.merge.dev/v1/customers/usage?start=2026-08-01&end=2026-08-31" \
>   -H "Authorization: Bearer mg_<your_production_key>"

1 {
2   "results": [
3     { "customer": "cus_9f3a2b81", "total_spend": 412.87, "byok_spend": 310.44, "merge_spend": 102.43 }
4   ]
5 }

The breakdown is two-way here rather than three-way: byok_spend combines the customer’s own keys and your organization’s, where the per-customer report separates them. A customer-scoped API key cannot call this endpoint, since it would expose every other tenant’s spend. Use an organization-level production key.