Billing
Package: agentrouter.billing.v1 Service: BillingService
Endpoints
Get your balance
Changed in v0.11.0 (new features): Self-service balance, top-ups, auto top-up and cards through the API.
Connect / gRPC only
What it does: Returns the caller's balance.
Request body: None.
Response fields:
| Field | Required | Description |
|---|---|---|
balance | no | undocumented |
currency | no | undocumented |
{"signatures":{"go":"c.Billing().GetMyBalance(ctx, \u0026billingv1.GetMyBalanceRequest{...})","python":"client.billing.getmybalance(...)","typescript":"client.billing.getmybalance({...})"},"examples":{"go":"// No Go SDK wrapper for BillingService yet -- use the CLI or curl example below.","python":"# No Python SDK wrapper for BillingService yet -- use the CLI or curl example below.","typescript":"// No TypeScript SDK wrapper for BillingService yet -- use the CLI or curl example below."},"persona":"Dashboard user (session token)","slug":"get-your-balance"}List your transactions
Changed in v0.11.0 (new features): Self-service balance, top-ups, auto top-up and cards through the API.
Connect / gRPC only
What it does: Pages through the caller's ledger, newest first.
Request fields:
| Field | Required | Description |
|---|---|---|
page | no | 1-based. Zero means the first page. |
page_size | no | At most 100. Zero means 10. |
type | no | "credit" or "debit". Empty means both. |
Response fields:
| Field | Required | Description |
|---|---|---|
transactions | no | undocumented |
total_count | no | undocumented |
{"signatures":{"go":"c.Billing().ListMyTransactions(ctx, \u0026billingv1.ListMyTransactionsRequest{...})","python":"client.billing.listmytransactions(...)","typescript":"client.billing.listmytransactions({...})"},"examples":{"go":"// No Go SDK wrapper for BillingService yet -- use the CLI or curl example below.","python":"# No Python SDK wrapper for BillingService yet -- use the CLI or curl example below.","typescript":"// No TypeScript SDK wrapper for BillingService yet -- use the CLI or curl example below."},"persona":"Dashboard user (session token)","slug":"list-your-transactions"}List your top-ups
Changed in v0.11.0 (new features): Self-service balance, top-ups, auto top-up and cards through the API.
Connect / gRPC only
What it does: Pages through the caller's top-up attempts, newest first.
Request fields:
| Field | Required | Description |
|---|---|---|
page | no | undocumented |
page_size | no | undocumented |
type | no | "manual" or "auto". Empty means both. |
status | no | "pending", "success", "failed" or "cancelled". Empty means all. |
Response fields:
| Field | Required | Description |
|---|---|---|
topups | no | undocumented |
total_count | no | undocumented |
{"signatures":{"go":"c.Billing().ListMyTopups(ctx, \u0026billingv1.ListMyTopupsRequest{...})","python":"client.billing.listmytopups(...)","typescript":"client.billing.listmytopups({...})"},"examples":{"go":"// No Go SDK wrapper for BillingService yet -- use the CLI or curl example below.","python":"# No Python SDK wrapper for BillingService yet -- use the CLI or curl example below.","typescript":"// No TypeScript SDK wrapper for BillingService yet -- use the CLI or curl example below."},"persona":"Dashboard user (session token)","slug":"list-your-top-ups"}Get a receipt
Changed in v0.11.0 (new features): Self-service balance, top-ups, auto top-up and cards through the API.
Connect / gRPC only
What it does: Returns the Stripe receipt of one of the caller's card payments. receipt_url is empty when the transaction has no receipt.
Request fields:
| Field | Required | Description |
|---|---|---|
transaction_id | no | undocumented |
Response fields:
| Field | Required | Description |
|---|---|---|
receipt_url | no | undocumented |
transaction | no | The transaction the receipt is for. |
{"signatures":{"go":"c.Billing().GetMyReceiptUrl(ctx, \u0026billingv1.GetMyReceiptUrlRequest{...})","python":"client.billing.getmyreceipturl(...)","typescript":"client.billing.getmyreceipturl({...})"},"examples":{"go":"// No Go SDK wrapper for BillingService yet -- use the CLI or curl example below.","python":"# No Python SDK wrapper for BillingService yet -- use the CLI or curl example below.","typescript":"// No TypeScript SDK wrapper for BillingService yet -- use the CLI or curl example below."},"persona":"Dashboard user (session token)","slug":"get-a-receipt"}Get your auto top-up settings
Changed in v0.11.0 (new features): Self-service balance, top-ups, auto top-up and cards through the API.
Connect / gRPC only
What it does: Returns the caller's auto top-up settings. It writes nothing: a caller with no Stripe customer gets no settings.
Request body: None.
Response fields:
| Field | Required | Description |
|---|---|---|
settings | no | Absent when the caller has no Stripe customer yet. |
{"signatures":{"go":"c.Billing().GetMyAutoTopupSettings(ctx, \u0026billingv1.GetMyAutoTopupSettingsRequest{...})","python":"client.billing.getmyautotopupsettings(...)","typescript":"client.billing.getmyautotopupsettings({...})"},"examples":{"go":"// No Go SDK wrapper for BillingService yet -- use the CLI or curl example below.","python":"# No Python SDK wrapper for BillingService yet -- use the CLI or curl example below.","typescript":"// No TypeScript SDK wrapper for BillingService yet -- use the CLI or curl example below."},"persona":"Dashboard user (session token)","slug":"get-your-auto-top-up-settings"}List your payment methods
Changed in v0.11.0 (new features): Self-service balance, top-ups, auto top-up and cards through the API.
Connect / gRPC only
What it does: Lists the caller's saved cards. It writes nothing: a caller with no Stripe customer gets an empty list.
Request body: None.
Response fields:
| Field | Required | Description |
|---|---|---|
payment_methods | no | undocumented |
{"signatures":{"go":"c.Billing().ListMyPaymentMethods(ctx, \u0026billingv1.ListMyPaymentMethodsRequest{...})","python":"client.billing.listmypaymentmethods(...)","typescript":"client.billing.listmypaymentmethods({...})"},"examples":{"go":"// No Go SDK wrapper for BillingService yet -- use the CLI or curl example below.","python":"# No Python SDK wrapper for BillingService yet -- use the CLI or curl example below.","typescript":"// No TypeScript SDK wrapper for BillingService yet -- use the CLI or curl example below."},"persona":"Dashboard user (session token)","slug":"list-your-payment-methods"}Start a top-up
Changed in v0.11.0 (new features): Self-service balance, top-ups, auto top-up and cards through the API.
Connect / gRPC only
What it does: Starts a manual top-up. With use_saved_card, Stripe charges the caller's default card now. Without it, the response carries the client secret of a payment intent that the browser confirms. The credit lands when Stripe reports the payment. A second manual top-up while one is pending gets FAILED_PRECONDITION; more manual top-ups in an hour than the deployment allows get RESOURCE_EXHAUSTED.
Request fields:
| Field | Required | Description |
|---|---|---|
amount_cents | no | Whole cents, from 1000 to 1000000 ($10 to $10,000). |
use_saved_card | no | Charge the default saved card now instead of returning a client secret. |
save_payment_method | no | For a new card: keep it for later payments and make it the default. |
Response fields:
| Field | Required | Description |
|---|---|---|
topup_id | no | The pending top-up attempt. |
payment_intent_id | no | undocumented |
client_secret | no | For a new card: the browser confirms this with Stripe. |
succeeded | no | For a saved card: whether Stripe accepted the charge. False means the card was declined; the attempt is failed. |
{"signatures":{"go":"c.Billing().StartTopup(ctx, \u0026billingv1.StartTopupRequest{...})","python":"client.billing.starttopup(...)","typescript":"client.billing.starttopup({...})"},"examples":{"go":"// No Go SDK wrapper for BillingService yet -- use the CLI or curl example below.","python":"# No Python SDK wrapper for BillingService yet -- use the CLI or curl example below.","typescript":"// No TypeScript SDK wrapper for BillingService yet -- use the CLI or curl example below."},"persona":"Dashboard user (session token)","slug":"start-a-top-up"}Cancel a pending top-up
Changed in v0.11.0 (new features): Self-service balance, top-ups, auto top-up and cards through the API.
Connect / gRPC only
What it does: Cancels one of the caller's pending top-ups, for a browser payment the user abandoned.
Request fields:
| Field | Required | Description |
|---|---|---|
topup_id | no | undocumented |
{"signatures":{"go":"c.Billing().CancelPendingTopup(ctx, \u0026billingv1.CancelPendingTopupRequest{...})","python":"client.billing.cancelpendingtopup(...)","typescript":"client.billing.cancelpendingtopup({...})"},"examples":{"go":"// No Go SDK wrapper for BillingService yet -- use the CLI or curl example below.","python":"# No Python SDK wrapper for BillingService yet -- use the CLI or curl example below.","typescript":"// No TypeScript SDK wrapper for BillingService yet -- use the CLI or curl example below."},"persona":"Dashboard user (session token)","slug":"cancel-a-pending-top-up"}Update your auto top-up settings
Changed in v0.11.0 (new features): Self-service balance, top-ups, auto top-up and cards through the API.
Connect / gRPC only
What it does: Changes the caller's auto top-up settings.
Request fields:
| Field | Required | Description |
|---|---|---|
enabled | no | With enabled false and both amounts zero, auto top-up turns off and keeps its stored amounts. |
threshold_cents | no | Whole cents, from 1000 to 100000. With enabled, above zero. |
target_balance_cents | no | Whole cents, from 100 to 1000000. With enabled, at least $5 above the threshold. |
Response fields:
| Field | Required | Description |
|---|---|---|
settings | no | undocumented |
{"signatures":{"go":"c.Billing().UpdateMyAutoTopupSettings(ctx, \u0026billingv1.UpdateMyAutoTopupSettingsRequest{...})","python":"client.billing.updatemyautotopupsettings(...)","typescript":"client.billing.updatemyautotopupsettings({...})"},"examples":{"go":"// No Go SDK wrapper for BillingService yet -- use the CLI or curl example below.","python":"# No Python SDK wrapper for BillingService yet -- use the CLI or curl example below.","typescript":"// No TypeScript SDK wrapper for BillingService yet -- use the CLI or curl example below."},"persona":"Dashboard user (session token)","slug":"update-your-auto-top-up-settings"}Start saving a card
Changed in v0.11.0 (new features): Self-service balance, top-ups, auto top-up and cards through the API.
Connect / gRPC only
What it does: Starts saving a new card: the browser confirms the returned client secret with Stripe.
Request body: None.
Response fields:
| Field | Required | Description |
|---|---|---|
client_secret | no | undocumented |
{"signatures":{"go":"c.Billing().CreateMySetupIntent(ctx, \u0026billingv1.CreateMySetupIntentRequest{...})","python":"client.billing.createmysetupintent(...)","typescript":"client.billing.createmysetupintent({...})"},"examples":{"go":"// No Go SDK wrapper for BillingService yet -- use the CLI or curl example below.","python":"# No Python SDK wrapper for BillingService yet -- use the CLI or curl example below.","typescript":"// No TypeScript SDK wrapper for BillingService yet -- use the CLI or curl example below."},"persona":"Dashboard user (session token)","slug":"start-saving-a-card"}Set your default card
Changed in v0.11.0 (new features): Self-service balance, top-ups, auto top-up and cards through the API.
Connect / gRPC only
What it does: Makes one of the caller's saved cards the default.
Request fields:
| Field | Required | Description |
|---|---|---|
payment_method_id | no | undocumented |
{"signatures":{"go":"c.Billing().SetMyDefaultPaymentMethod(ctx, \u0026billingv1.SetMyDefaultPaymentMethodRequest{...})","python":"client.billing.setmydefaultpaymentmethod(...)","typescript":"client.billing.setmydefaultpaymentmethod({...})"},"examples":{"go":"// No Go SDK wrapper for BillingService yet -- use the CLI or curl example below.","python":"# No Python SDK wrapper for BillingService yet -- use the CLI or curl example below.","typescript":"// No TypeScript SDK wrapper for BillingService yet -- use the CLI or curl example below."},"persona":"Dashboard user (session token)","slug":"set-your-default-card"}Remove a card
Changed in v0.11.0 (new features): Self-service balance, top-ups, auto top-up and cards through the API.
Connect / gRPC only
What it does: Removes one of the caller's saved cards.
Request fields:
| Field | Required | Description |
|---|---|---|
payment_method_id | no | undocumented |
{"signatures":{"go":"c.Billing().DeleteMyPaymentMethod(ctx, \u0026billingv1.DeleteMyPaymentMethodRequest{...})","python":"client.billing.deletemypaymentmethod(...)","typescript":"client.billing.deletemypaymentmethod({...})"},"examples":{"go":"// No Go SDK wrapper for BillingService yet -- use the CLI or curl example below.","python":"# No Python SDK wrapper for BillingService yet -- use the CLI or curl example below.","typescript":"// No TypeScript SDK wrapper for BillingService yet -- use the CLI or curl example below."},"persona":"Dashboard user (session token)","slug":"remove-a-card"}