> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xquik.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Twitter API billing: instant X API credit top-up

> Charge a saved method for USD 10-500 in the Xquik dashboard. Handle authentication, declines, and checkout fallback without double billing or server errors.

<Panel>
  <Tabs defaultTabIndex={0} sync={false}>
    <Tab title="200" id="response-credits-quick-topup-200">
      ```json theme={null}
      {
        "outcome": "charged",
        "balance": "1450",
        "credits": "1000"
      }
      ```
    </Tab>

    <Tab title="400" id="response-credits-quick-topup-400">
      ```json theme={null}
      {
        "error": "invalid_input",
        "message": "Invalid input. Check the request body."
      }
      ```
    </Tab>

    <Tab title="401" id="response-credits-quick-topup-401">
      ```json theme={null}
      {
        "error": "unauthenticated",
        "message": "Authentication required. Provide a valid API key or bearer token."
      }
      ```
    </Tab>

    <Tab title="429" id="response-credits-quick-topup-429">
      ```json theme={null}
      {
        "error": "rate_limit_exceeded",
        "message": "Too many requests. Try again later.",
        "retryAfter": 60
      }
      ```
    </Tab>
  </Tabs>
</Panel>

<blockquote className="agent-llms-directive">
  For the complete documentation index, see <a href="/llms.txt">llms.txt</a>.
</blockquote>

Add API credits from the Xquik dashboard with a saved payment method.

## Add API credits with a saved payment method

Use quick top-up after the dashboard confirms an amount from USD 10 through 500. This route requires a same-origin Xquik session. External integrations
must use the [hosted top-up endpoint](/api-reference/credits/topup).

Read `outcome` before handling any other response field. `charged` means the
credits and new balance are ready. `requires_action` means the client must
complete payment authentication. `declined` means the saved method failed.
`no_payment_method` means the account has no reusable payment method.

Never print or store `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.

<Callout icon="circle-check" color="#16a34a">
  **Free.** This endpoint does not consume credits.
</Callout>

<CodeGroup>
  ```javascript Dashboard browser theme={null}
  const response = await fetch("/api/v1/credits/quick-topup", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ dollars: 25 }),
  });
  const result = await response.json();

  if (result.outcome === "charged") {
    window.location.reload();
  } else if (result.outcome === "requires_action") {
    await confirmSavedPayment(result.clientSecret);
  } else {
    window.location.assign("/account/subscription");
  }
  ```
</CodeGroup>

| Credit top-up outcome | Response fields | Next action |
| - | - | - |
| Immediate charge | `outcome: "charged"` | Store `credits` and the updated `balance`. |
| Payment authentication | `outcome: "requires_action"` | Complete the billing confirmation flow. |
| Missing payment method | `outcome: "no_payment_method"` | Create a checkout top-up instead. |
| Declined payment method | `outcome: "declined"` | Ask for another payment method. |
| Added credits | `credits` | Treat the bigint value as a string. |
| Updated balance | `balance` | Check it before the next tweet, follower, or monitor job. |
| Confirmation secret | `clientSecret` | Send it only to the billing confirmation flow. |

## Headers

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`.
</ParamField>

## Body

<ParamField body="dollars" type="number" required>
  Amount in US dollars to charge. Minimum USD 10, maximum USD 500.
</ParamField>

At USD 0.00015 per credit, a USD 25 quick top-up adds 166,666 credits, rounded down to whole credits.

Only `charged` grants credits. Complete `requires_action` with `clientSecret`.
Use hosted checkout for `declined` or `no_payment_method`.

## Response

### 200 Charged

The payment succeeded. Xquik added the credits to your balance.

<ResponseField name="outcome" type="string">
  Always `"charged"`.
</ResponseField>

<ResponseField name="balance" type="string">
  Updated credit balance after top-up (Bigint string).
</ResponseField>

<ResponseField name="credits" type="string">
  Number of credits added (Bigint string).
</ResponseField>

```json theme={null}
{
  "outcome": "charged",
  "balance": "466666",
  "credits": "166666"
}
```

### 200 Requires action

Payment requires more authentication, such as 3D Secure. Use the returned client secret with the billing confirmation flow to complete the payment.

<ResponseField name="outcome" type="string">
  Always `"requires_action"`.
</ResponseField>

<ResponseField name="clientSecret" type="string">
  Payment client secret for completing the payment.
</ResponseField>

```json theme={null}
{
  "outcome": "requires_action",
  "clientSecret": "pi_3abc...secret_xyz"
}
```

### 200 No payment method

The account has no saved payment method. Redirect the user to add one in the billing portal, or use the standard [top-up endpoint](/api-reference/credits/topup) instead.

<ResponseField name="outcome" type="string">
  Always `"no_payment_method"`.
</ResponseField>

```json theme={null}
{
  "outcome": "no_payment_method"
}
```

### 200 Declined

The saved method failed. Open hosted checkout so the user can choose another.

<ResponseField name="outcome" type="string">
  Always `"declined"`.
</ResponseField>

```json theme={null}
{
  "outcome": "declined"
}
```

### 400 Invalid input

```json theme={null}
{ "error": "Invalid input" }
```

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

### 401 Unauthenticated

```json theme={null}
{ "error": "unauthenticated" }
```

Missing or expired dashboard session. This route does not accept API keys.

### 429 Rate limited

```json theme={null}
{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Try again later.",
  "retryAfter": 60
}
```

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

<Note>
  **Related.** [Top Up Credits](/api-reference/credits/topup) · [Get Top-Up Status](/api-reference/credits/topup-status) · [Get Credits](/api-reference/credits/get) · [Billing Guide](/guides/billing)
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.