Top up prepaid credits via the xAI Management API

Charge the team's default payment method and add prepaid credits over HTTP when automation, runbooks, or paging need to refill the pool without opening Console Guest Checkout. Official Billing Management documents POST /v1/billing/teams/{team_id}/prepaid/top-up on https://management-api.x.ai, authorized with a management key. The request body carries an amount object whose val is USD cents as a string, and the response returns a change row with changeOrigin, topupStatus, amount, and payment-processor metadata. Create the management key first with Create a management key in the xAI Console if you do not already have one.

What you need

A management key that can call billing routes for the team, the team id in the path, a default payment method already on file in Console (the Management API lists methods but directs add/delete to console.x.ai), and an amount in USD cents that matches what finance approved. Amounts follow the same {"val": "500"} cent-string shape used elsewhere in billing. For the click-through purchase and threshold auto-refill paths, use Purchase prepaid credits on the xAI Console and Set auto top-up on the xAI Console. After a top-up, confirm the pool with Check prepaid credit balance via the xAI Management API. More API jobs live on the API hub.

Call the prepaid top-up endpoint

1. Export the management key and team id outside of source control:

export XAI_MANAGEMENT_KEY="your_management_key"
export XAI_TEAM_ID="your_team_id"

2. Confirm a default payment method exists before you charge. List methods with the billing reference route GET /v1/billing/teams/{team_id}/payment-method, and if you need a different card to be default, use POST /v1/billing/teams/{team_id}/payment-method/default with that paymentMethodId. Add or remove cards only in Console as the docs state.

3. Top up with an amount in USD cents. The example below charges five dollars (500 cents):

curl "https://management-api.x.ai/v1/billing/teams/${XAI_TEAM_ID}/prepaid/top-up" \
  -X POST \
  -H "Authorization: Bearer ${XAI_MANAGEMENT_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": {
      "val": "500"
    }
  }'

4. Read the response change object. Documented origins for purchases include PURCHASE; topupStatus may be TO_CHARGE, SUCCEEDED, FAILED_TO_CHARGE, or related invoice-generation states while the processor finishes. Purchase amounts appear negative in the documented sense for credits added through checkout. Capture invoiceId / invoiceNumber when present for finance reconciliation.

5. Poll prepaid balance until total.val reflects the new credits and a matching change row shows a terminal success status:

curl "https://management-api.x.ai/v1/billing/teams/${XAI_TEAM_ID}/prepaid/balance" \
  -H "Authorization: Bearer ${XAI_MANAGEMENT_KEY}"

Keep every call on https://management-api.x.ai. An inference API key against https://api.x.ai will not answer billing routes.

Use top-up in ops

Wire the POST into the same alert that watches total.val so humans and automation refill from one number. Prefer Management top-up when a runbook must charge a known cent amount immediately; prefer Console auto top-up when you want a standing threshold and monthly max without custom code. Bank-transfer methods added in Console can still take two to three business days before credits grant, so treat TO_CHARGE and pending invoice states as in-flight rather than failed until the processor settles.

Pitfalls

Sending dollars instead of cents (for example "5" when you meant five dollars) underfunds the pool by two orders of magnitude. Calling top-up with no default payment method on file yields charge failures that look like empty change history until you inspect topupStatus. Declaring success from the first TO_CHARGE response without polling balance leaves traffic on an empty pool. Mixing this prepaid team pool with SuperGrok consumer weekly usage on grok.com produces refill scripts that never match Console Billing. Using the Console purchase how-to's Guest Checkout flow and this Management route interchangeably without checking which payment method is default can charge the wrong card on file.