Preview a postpaid invoice via the xAI Management API

Fetch the in-progress postpaid invoice draft for the current billing period over HTTP when finance needs accrual numbers before the month closes or when on-call wants to see how close the team sits to the effective spending limit. Official Billing Management documents GET /v1/billing/teams/{team_id}/postpaid/invoice/preview on https://management-api.x.ai, authorized with a management key. The response returns a coreInvoice object with line items and cent amounts, plus effectiveSpendingLimit, defaultCredits, and the active billingCycle year/month. 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, and a clear split between prepaid credits already purchased and postpaid usage that will invoice at cycle end. Documented fields include amountBeforeVat, vatCost, amountAfterVat, auto and default credits issued, prepaidCredits / prepaidCreditsUsed, and totalWithCorr. Amounts are USD cent strings, matching the rest of the billing API. Settled history still comes from List invoices via the xAI Management API; this preview is for the open period. Neighboring controls include Set postpaid spending limits via the xAI Management API and Check prepaid credit balance via the xAI Management API. More API jobs live on the API hub.

Call the postpaid invoice preview

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. Request the current-period preview:

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

3. Read billingCycle.year and billingCycle.month so you know which calendar month the draft covers. Compare effectiveSpendingLimit (USD cents) to the postpaid amounts on coreInvoice when deciding whether to raise the soft limit or pause traffic.

4. Walk coreInvoice.lines for cluster, description, unit type, unit price, unit count, and line amount when you need the same shape as settled invoice lines. Use amountAfterVat and totalWithCorr.val for the rollup finance will recognize once the cycle closes. Prepaid fields on the preview show remaining and used prepaid credits in cent form so you can see how much of the cycle still draws from the prepaid pool first.

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

Use the preview in ops

Schedule a mid-cycle preview into the same sheet that stores settled invoice totals so month-end surprises shrink. When effectiveSpendingLimit is near exhaustion and prepaid is empty, either top up with Top up prepaid credits via the xAI Management API or adjust the soft limit with the spending-limits route before requests start failing. Historical usage buckets that explain why the draft grew live in Get usage analytics via the xAI Management API.

Pitfalls

Treating the preview as a settled PAID invoice row breaks reconciliation when charger attempts have not run yet. Comparing cent strings as floating dollars invents variance against finance systems that store major units. Expecting an unfinalized month to appear in the invoices list instead of this preview endpoint leaves automation with an empty array. Mixing SuperGrok consumer receipts on grok.com with these team Management previews produces a ledger that never closes.