Billing admin
Package: agentrouter.billing.v1 Service: BillingAdminService
Endpoints
Search billing users
Changed in v0.11.0 (new features): Administrators read their organization's balances and top-ups; operators adjust credits.
Connect / gRPC only
What it does: Finds the users whose balance the caller can see, by name or email, or by user_id.
Request fields:
| Field | Required | Description |
|---|---|---|
customer_id | no | The organization the caller acts in. Required. |
search | no | A substring of the name or email. Ignored when user_id is set. |
user_id | no | One exact user. |
limit | no | At most 25. Zero means 10. |
Response fields:
| Field | Required | Description |
|---|---|---|
users | no | undocumented |
{"signatures":{"go":"c.BillingAdmin().SearchBillingUsers(ctx, \u0026billingv1.SearchBillingUsersRequest{...})","python":"client.billingadmin.searchbillingusers(...)","typescript":"client.billingadmin.searchbillingusers({...})"},"examples":{"go":"// No Go SDK wrapper for BillingAdminService yet -- use the CLI or curl example below.","python":"# No Python SDK wrapper for BillingAdminService yet -- use the CLI or curl example below.","typescript":"// No TypeScript SDK wrapper for BillingAdminService yet -- use the CLI or curl example below."},"persona":"Admin","slug":"search-billing-users"}Get a user's balance
Changed in v0.11.0 (new features): Administrators read their organization's balances and top-ups; operators adjust credits.
Connect / gRPC only
What it does: Returns one user's balance and lifetime totals.
Request fields:
| Field | Required | Description |
|---|---|---|
customer_id | no | undocumented |
user_id | no | undocumented |
Response fields:
| Field | Required | Description |
|---|---|---|
user_id | no | undocumented |
balance | no | undocumented |
currency | no | undocumented |
lifetime_added | no | The sum of completed credits and of completed debits. |
lifetime_deducted | no | undocumented |
last_adjustment | no | The newest manual credit adjustment, when there is one. |
last_topup | no | The newest top-up attempt, when there is one. |
{"signatures":{"go":"c.BillingAdmin().GetUserBalance(ctx, \u0026billingv1.GetUserBalanceRequest{...})","python":"client.billingadmin.getuserbalance(...)","typescript":"client.billingadmin.getuserbalance({...})"},"examples":{"go":"// No Go SDK wrapper for BillingAdminService yet -- use the CLI or curl example below.","python":"# No Python SDK wrapper for BillingAdminService yet -- use the CLI or curl example below.","typescript":"// No TypeScript SDK wrapper for BillingAdminService yet -- use the CLI or curl example below."},"persona":"Admin","slug":"get-a-users-balance"}List a user's transactions
Changed in v0.11.0 (new features): Administrators read their organization's balances and top-ups; operators adjust credits.
Connect / gRPC only
What it does: Pages through one user's ledger, newest first.
Request fields:
| Field | Required | Description |
|---|---|---|
customer_id | no | undocumented |
user_id | no | undocumented |
page | no | undocumented |
page_size | no | At most 100. Zero means 25. |
include_llm_usage | no | Also return the per-request usage charges, which are hidden by default. |
Response fields:
| Field | Required | Description |
|---|---|---|
transactions | no | undocumented |
total_count | no | undocumented |
{"signatures":{"go":"c.BillingAdmin().ListUserTransactions(ctx, \u0026billingv1.ListUserTransactionsRequest{...})","python":"client.billingadmin.listusertransactions(...)","typescript":"client.billingadmin.listusertransactions({...})"},"examples":{"go":"// No Go SDK wrapper for BillingAdminService yet -- use the CLI or curl example below.","python":"# No Python SDK wrapper for BillingAdminService yet -- use the CLI or curl example below.","typescript":"// No TypeScript SDK wrapper for BillingAdminService yet -- use the CLI or curl example below."},"persona":"Admin","slug":"list-a-users-transactions"}List a user's top-ups
Changed in v0.11.0 (new features): Administrators read their organization's balances and top-ups; operators adjust credits.
Connect / gRPC only
What it does: Pages through one user's top-up attempts, newest first.
Request fields:
| Field | Required | Description |
|---|---|---|
customer_id | no | undocumented |
user_id | no | undocumented |
page | no | undocumented |
page_size | no | undocumented |
Response fields:
| Field | Required | Description |
|---|---|---|
topups | no | undocumented |
total_count | no | undocumented |
{"signatures":{"go":"c.BillingAdmin().ListUserTopups(ctx, \u0026billingv1.ListUserTopupsRequest{...})","python":"client.billingadmin.listusertopups(...)","typescript":"client.billingadmin.listusertopups({...})"},"examples":{"go":"// No Go SDK wrapper for BillingAdminService yet -- use the CLI or curl example below.","python":"# No Python SDK wrapper for BillingAdminService yet -- use the CLI or curl example below.","typescript":"// No TypeScript SDK wrapper for BillingAdminService yet -- use the CLI or curl example below."},"persona":"Admin","slug":"list-a-users-top-ups"}List top-up activity
Changed in v0.11.0 (new features): Administrators read their organization's balances and top-ups; operators adjust credits.
Connect / gRPC only
What it does: Pages through the top-ups of every user the caller can see, with counts by status and type.
Request fields:
| Field | Required | Description |
|---|---|---|
customer_id | no | undocumented |
page | no | undocumented |
page_size | no | At most 100. Zero means 10. |
search | no | A substring of the user id, name or email, the Stripe customer, the payment intent or the payment event. |
status | no | "pending", "success", "failed" or "cancelled". Empty means all. |
type | no | "manual" or "auto". Empty means both. |
sort_by | no | "user", "status", "type", "amount" or "trigger_time" (the default). |
sort_ascending | no | Ascending order. The default is newest first. |
Response fields:
| Field | Required | Description |
|---|---|---|
activities | no | undocumented |
total_count | no | undocumented |
stats | no | undocumented |
{"signatures":{"go":"c.BillingAdmin().ListTopupActivities(ctx, \u0026billingv1.ListTopupActivitiesRequest{...})","python":"client.billingadmin.listtopupactivities(...)","typescript":"client.billingadmin.listtopupactivities({...})"},"examples":{"go":"// No Go SDK wrapper for BillingAdminService yet -- use the CLI or curl example below.","python":"# No Python SDK wrapper for BillingAdminService yet -- use the CLI or curl example below.","typescript":"// No TypeScript SDK wrapper for BillingAdminService yet -- use the CLI or curl example below."},"persona":"Admin","slug":"list-top-up-activity"}Adjust a user's credit
Changed in v0.11.0 (new features): Administrators read their organization's balances and top-ups; operators adjust credits.
Connect / gRPC only
What it does: Adds credit to, or deducts it from, one user's balance. Only the operator credits: the caller needs billing.edit at the platform, or in the deployment's own organization when customer_id names it. A repeat of the same idempotency_key with the same values returns the first result and writes nothing; with other values it is ALREADY_EXISTS. A deduction below zero is FAILED_PRECONDITION.
Request fields:
| Field | Required | Description |
|---|---|---|
customer_id | no | undocumented |
user_id | no | undocumented |
direction | no | "add" or "deduct". |
amount_cents | no | Whole cents, above zero. |
reason_code | no | One of goodwill_credit, payment_correction, bonus_correction, refund_adjustment, fraud_reversal, support_resolution, other. |
note | no | Why, in 1 to 1000 characters. |
provider_reference | no | An outside reference, such as a support ticket. At most 200 characters. |
idempotency_key | no | 8 to 200 characters. Send the same key to retry safely. |
Response fields:
| Field | Required | Description |
|---|---|---|
transaction | no | undocumented |
balance | no | The user's balance after the adjustment. |
{"signatures":{"go":"c.BillingAdmin().CreateCreditAdjustment(ctx, \u0026billingv1.CreateCreditAdjustmentRequest{...})","python":"client.billingadmin.createcreditadjustment(...)","typescript":"client.billingadmin.createcreditadjustment({...})"},"examples":{"go":"// No Go SDK wrapper for BillingAdminService yet -- use the CLI or curl example below.","python":"# No Python SDK wrapper for BillingAdminService yet -- use the CLI or curl example below.","typescript":"// No TypeScript SDK wrapper for BillingAdminService yet -- use the CLI or curl example below."},"persona":"Admin","slug":"adjust-a-users-credit"}