Set the default payment method via the xAI Management API

Point a team's default payment method at an existing paymentMethodId over HTTP when prepaid top-ups, auto top-up, or monthly invoiced charges must hit a specific card or bank account already on file. Official Billing Management documents POST /v1/billing/teams/{team_id}/payment-method/default on https://management-api.x.ai, authorized with a management key, with a JSON body that carries only paymentMethodId. The same reference documents GET /v1/billing/teams/{team_id}/payment-method to inventory methods first, and states that you add or delete payment methods on console.x.ai. 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 at least one saved payment method whose paymentMethodId you trust. List responses expose redacted card brand and last4 (or ACH / Link fields) so you can confirm the right instrument before you POST. Adding a brand-new card still happens in Console under Billing → Billing details → Add Payment Information, covered in Add a payment method in the xAI Console. Neighboring spend jobs include List payment methods via the xAI Management API, Top up prepaid credits via the xAI Management API, and Purchase prepaid credits on the xAI Console. More API jobs live on the API hub.

Choose the default method

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. List payment methods and copy the paymentMethodId you want as default (match brand, last4, or ACH fields from the response):

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

3. Set that id as the team's default payment method:

curl "https://management-api.x.ai/v1/billing/teams/${XAI_TEAM_ID}/payment-method/default" \
  -X POST \
  -H "Authorization: Bearer ${XAI_MANAGEMENT_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"paymentMethodId":"pm_xxxxxxxxxxxxxxxxxxxxxxxx"}'

4. Expect an empty JSON object {} on success per the billing reference, then re-run the GET list (or a small prepaid top-up in a non-production team) when your runbook requires proof that the new default will be charged. Keep every call on https://management-api.x.ai; an inference Bearer against https://api.x.ai will not reach these billing routes.

Pair with Console and spend limits

Use this POST after finance rotates the primary card or after ACH verification finishes and a pending method becomes a real paymentMethodId. Pair with Raise the invoiced billing limit in the xAI Console when monthly invoiced billing above $0 should charge that default at cycle end, and with Set auto top-up on the xAI Console when prepaid refill should draw from the same instrument.

Pitfalls

Posting a typo'd or deleted paymentMethodId fails the default switch even though the GET list still shows other cards. Assuming the Management API can add a brand-new card skips the Console Add Payment Information path the docs require. Leaving the old default in place after a lost card means prepaid top-ups and invoiced charges keep hitting the wrong instrument until this POST succeeds.