Skip to main content
POST
Twitter API billing: instant X API credit top-up
Add X API credits for tweet, follower, monitor, webhook, export, and write calls. Use this Twitter API billing route with an existing saved payment method.

Add API credits with a saved payment method

Use quick top-up when the account already has a reusable payment method. Send a USD amount from 10 through 500. The route funds tweet, profile, follower, monitor, webhook, export, and X write requests without creating a hosted checkout page. Read outcome before handling any other response field. charged means the credits and new balance are ready. requires_action means the client must complete the payment confirmation flow. Another outcome can require adding a payment method first. Never print or persist clientSecret. Pass it directly to the payment confirmation flow. Log only the outcome, added credits, and resulting balance after a successful charge. Quick top-up differs from standard checkout status. The status route polls a hosted checkout session by session_id. This route returns its own immediate payment outcome for the saved payment method.
Free - does not consume credits

Headers

string
required
Your API key. Session cookie authentication is also supported.
string
required
Must be application/json.

Body

number
required
Amount in US dollars to charge. Minimum 10,maximum10, maximum 500.
At USD 0.00015 per credit, a USD 25 quick top-up adds 166,666 credits, rounded down to whole credits. Only the charged outcome grants credits and updates balance. If the endpoint returns requires_action, complete payment authentication with clientSecret before retrying the metered API call. Pass clientSecret to the billing confirmation flow only; do not print it in logs. If it returns no_payment_method, create a checkout top-up instead.

Response

200 Charged

Payment succeeded immediately. Credits added to your balance.
string
Always "charged".
string
Updated credit balance after top-up (Bigint string).
string
Number of credits added (Bigint string).

200 Requires action

Payment requires additional authentication (e.g., 3D Secure). Use the returned client secret with the billing confirmation flow to complete the payment.
string
Always "requires_action".
string
Payment client secret for completing the payment.

200 No payment method

No saved payment method on file. Redirect the user to add one via the billing portal, or use the standard top-up endpoint instead.
string
Always "no_payment_method".

400 Invalid input

The request body is missing a numeric dollars value or includes too many decimal places.

401 Unauthenticated

Missing or invalid API key.

429 Rate limited

Too many requests. Wait for the Retry-After header before retrying.