Billing Information — Management API: Keys & Billing

Manage billing via the API

The Billing section of the Management API lets you retrieve and update your billing information, fetch invoices, and monitor spending—all programmatically. No more jumping back and forth to the console to check payment status.

GET

Retrieve

POST

Update

Invoice statuses

Monthly

Billing cycle

Retrieve billing information

Billing details seem harmless until accounting rejects an invoice because of the wrong name or missing VAT number. Verifying them via the API takes one request and prevents an unfixable error: as the note below explains, you cannot regenerate an issued invoice with new details.

curl "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/billing-info" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

The response contains the registered billing details: company name, address, country, and VAT number if applicable.

Update information

To modify your billing information:

curl -X POST "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/billing-info" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "companyName": "My Company SAS",
    "address": "15 Peace Street",
    "city": "Paris",
    "country": "FR",
    "vatNumber": "FR12345678901"
  }'

Important note on existing invoices

Updated billing information applies only to future invoices. You cannot retroactively regenerate an invoice with new details. Verify your information before the billing cycle ends to ensure accurate invoices.

Retrieve invoices

The GET /v1/billing/teams/{teamId}/invoices endpoint returns your invoice history:

# Invoices for a specific month
curl "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/invoices?billingCycle.year=2026&billingCycle.month=3" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

# Invoices since a given month
curl "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/invoices?since.year=2026&since.month=1" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

Filtering parameters

billingCycle.year and billingCycle.month: retrieve invoices for a specific cycle
since.year and since.month: retrieve all invoices since a given month

Invoice statuses

Of these four statuses, only one requires immediate action. FAILED means the charge did not go through—expired card, limit reached, dispute—and an unpaid invoice eventually leads to service suspension. This is the status you need to monitor automatically, as shown in the payment methods lesson; you review the other three, but you alert on this one.

PENDING: the invoice is being processed; payment has not yet been charged
PAID: payment was successful
FAILED: the charge failed (expired card, insufficient funds, etc.)
WILL_NEVER_BE_CHARGED: the invoice will never be charged (credit, adjustment)

xAI billing logic

Understanding how the two modes interact prevents misinterpretations of your dashboard. Prepaid credits are used first; monthly billing kicks in only once the balance is exhausted. A zero balance with active service is not an anomaly: it means you are now consuming on a postpaid basis, and the end-of-month invoice is accumulating.

Prepaid credits

Purchased credits are charged immediately at the time of purchase. Each API call consumes credits based on the number of tokens processed. Credits are used first.

Monthly billing (postpaid)

If your credits are exhausted or you have none, consumption is billed at the end of the month. The cost of each API call is calculated immediately, but the charge occurs at the end of the cycle.

Token counting differences

Expect a discrepancy between your local count and the billing count, and it is better to know this before spending half a day tracking it down. Billing is authoritative: base your cost estimates on the analytics API figures, never on a count performed with a client-side tokenizer. This is normal: inference endpoints add internal tokens for processing (system instructions, formatting), which slightly increases the billed count compared to raw text.

View current charges

To view accumulated charges before the cycle ends:

curl "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/postpaid/invoice/preview" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

This preview is the only way to know the current amount before the invoice is issued. Checked once a week, it turns monthly billing into something manageable: you see cost drift midway through, when there is still time to route traffic to a cheaper model or lower a limit.

Key takeaways

GET and POST on /v1/billing/teams/{teamId}/billing-info to retrieve and modify information
Invoices have 4 statuses: PENDING, PAID, FAILED, WILL_NEVER_BE_CHARGED
Billing changes are not retroactive on existing invoices
xAI combines prepaid credits (priority) and monthly billing
The charges preview (invoice/preview) lets you anticipate costs