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

# Billing and top-ups

> Top up your prepaid balance with Stripe, manage saved cards, and configure auto top-up.

Your Omnifence account uses prepaid credit. Each moderation request reduces your balance; when it reaches zero we reject new requests with [`402 PAYMENT_REQUIRED`](/errors#error-codes) until you top up.

<Note>
  Every new account starts with a **free \$1.00 credit** so you can try the API before adding a payment method. It lands in your balance automatically when you sign up.
</Note>

You can top up your account two ways:

1. **One-time top-up** through the dashboard.
2. **Auto top-up**, which automatically charges your saved card when your balance falls below a threshold you set.

## One-time top-up

1. Sign in to the [dashboard](https://app.omnifence.ai) and open **Billing**.
2. Pick a preset amount ($25 – $500) or enter a custom amount between $5 and $5000.
3. Optionally check **Save card for future top-ups** if you want to reuse the same payment method later or enable auto top-up.
4. Click **Continue to checkout**. You're redirected to a Stripe Checkout page.
5. Pay with your card. After Stripe confirms, you return to the dashboard and your balance updates.

<Note>
  Stripe processes the charge in your local currency where available (Adaptive Pricing). Your USD
  balance is always credited the amount you selected in step 2, regardless of the exchange rate
  applied at checkout.
</Note>

### Tax

If you have a billing address in a tax jurisdiction we collect from (e.g. EU VAT, certain US states), Stripe Tax adds the appropriate tax at checkout. Tax is collected and remitted by Stripe; it does not enter your prepaid balance.

You can enter a business tax ID at checkout to apply reverse-charge rules where they apply.

## Invoices

Top-ups paid through Stripe Checkout generate an invoice with a downloadable PDF. To find them, open **Billing** in the dashboard and click **View invoices** in the Billing history section. This opens the Stripe Customer Portal, where you can:

* View and download invoices for past top-ups.
* Add or remove saved cards.
* Update your billing address and tax details.

<Note>
  Top-ups charged directly against a saved card appear in your billing history but do not produce a
  separate invoice document.
</Note>

## Saved payment methods

If you opted to save your card during a top-up, you can manage saved cards under **Billing → Saved payment methods**:

* **Add a card** — opens a zero-dollar Stripe Checkout that saves a card without charging it. Useful before enabling auto top-up.
* **Remove a card** — detaches the card from your account. If the removed card was the auto top-up default, auto top-up is automatically disabled.

We store only the card brand, last four digits, and expiry. Full PAN never touches our servers.

## Auto top-up

Auto top-up charges your saved card off-session whenever your balance falls below a threshold you set. Configure it under **Billing → Auto top-up**:

| Setting                              | What it does                                                                       |
| ------------------------------------ | ---------------------------------------------------------------------------------- |
| **Trigger when balance falls below** | When this is `5`, an auto top-up fires the next time your balance drops under \$5. |
| **Top up by**                        | The USD amount to charge. Must be greater than the trigger threshold.              |
| **Payment method**                   | Which saved card to charge.                                                        |

### Auto top-up terms

By enabling auto top-up you authorise us to charge your saved card off-session under these terms (also shown in the dashboard):

* **Frequency.** Charges happen each time your balance falls below the threshold you set. There is no fixed cycle — frequency depends on your usage.
* **Amount.** Each charge is the "Top up by" amount, plus tax determined by your billing address.
* **Cancellation.** Disable the toggle in the dashboard at any time. Charges already in flight will complete.
* **Failures.** If a charge fails (declined card, [SCA required](https://stripe.com/docs/strong-customer-authentication), expired card, etc.), auto top-up is disabled with a structured reason. You can re-enable it after fixing the issue.

### When auto top-up is disabled by the system

If we disable auto top-up automatically, the dashboard shows the reason:

| Reason                    | What happened                                                                        | What to do                                                                               |
| ------------------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
| `authentication_required` | Your card issuer required 3-D Secure authentication, which can't happen off-session. | Re-authenticate by initiating a fresh one-time top-up, then re-enable.                   |
| `card_declined`           | Stripe declined the charge.                                                          | Check the card, update it in Saved payment methods, then re-enable.                      |
| `payment_method_detached` | The saved card was removed (from this dashboard or via Stripe).                      | Add a new card and re-enable.                                                            |
| `tax_address_required`    | We need a billing address to calculate tax, but the card on file has none.           | Run a fresh one-time top-up in Checkout to refresh your billing address, then re-enable. |
| `stripe_error`            | Stripe returned an unexpected error.                                                 | Contact support.                                                                         |

## Volume discounts

If your account qualifies for volume discounts, charges this calendar month are multiplied by a discount factor once your month-to-date spend crosses a threshold. The same tier set applies to both pricing methods (fixed and multiplier).

* **Threshold basis.** Sum of charges billed since the start of the current UTC calendar month, in USD.
* **Forward-only.** Discounts apply to future charges in the same month after the threshold is crossed — past charges are not retroactively credited.
* **Tier resolution.** The active tier is the one with the largest threshold that is at or below your current MTD spend. If no tier qualifies, your charges run at the un-discounted rate.
* **Per-account.** Tiers are configured globally by default. If your account has custom tiers (or is opted out), your support contact can confirm what applies.

Each ledger row that was discounted records the volume-tier factor (e.g. `0.8000`) and the base charge before the factor was applied, so discounted charges remain fully auditable in the dashboard's billing ledger.

## Refunds

To request a refund, contact [support@omnifence.ai](mailto:support@omnifence.ai). Refunds reduce your prepaid balance by the refunded amount and return funds to the original payment method.

## Dashboard only

Billing — your balance, ledger, top-ups, saved cards, and auto top-up — is managed entirely from the [dashboard](https://app.omnifence.ai). There are no billing API endpoints; programmatic API keys can't read your balance or usage, or move money. When a request is rejected with [`402 PAYMENT_REQUIRED`](/errors#error-codes), sign in and top up.