How Billing Works

Every order is settled one of two ways:

• Billed to your organization — debited from your prepaid balance at your wholesale rates. There is no checkout step; the debit happens when the order is placed.
• Paid by your end user — a card payment through in-app Stripe checkout, at the retail prices you set. You never front the money; FileForms collects the wholesale portion and your margin is the difference.

Which one applies depends on where the order comes from and on your billing mode:

• API orders are always billed to your organization.
• Dashboard orders follow the billing mode set in Settings → Billing → Billing mode: everyone pays in-app (the default), organization admins are billed to the organization while other users pay in-app, or everyone is billed to the organization.

Both paths charge the state fee on top of the service fee — see State fees.

Setting up billing

Billing setup is required before you can create an API key or place organization-billed orders. An organization admin sets it up in Settings → Billing:

1. Add a payment method — card or US bank account (ACH).
2. Make your initial top-up — minimum $500. Your balance activates when the top-up settles: instantly for cards, about 4 business days for bank accounts.
3. Configure auto top-up (recommended) — see below.

The prepaid balance

Your balance is a ledger: top-ups credit it, orders debit it, and every entry is visible under Settings → Billing → Transactions (with CSV export).

When an order is billed to your organization — any API order, or a dashboard order covered by your billing mode — the debit is wholesale service fee + state fee, charged at order creation. If a filing is later cancelled, the debit is automatically reversed to your balance.

Auto top-up

When a debit takes your balance below your balance threshold (default $1,000), FileForms automatically charges your payment method for your replenish amount (default $5,000, minimum $500). Both are configurable in Settings → Billing.

Insufficient balance

If an order would overdraw your balance, FileForms first attempts an immediate shortfall top-up from your saved payment method. If that can't settle instantly (card declined, your payment method is ACH, or a top-up is already in flight), the order is rejected with 402 Payment Required:

{
  "message": "Insufficient organization balance for this order. Top up your balance in Settings → Billing to place new orders.",
  "balance": 12050,
  "required": 38800
}

balance and required are in cents. The order is not placed — top up and retry. If billing isn't set up at all, order endpoints return 403 instead.

In-app checkout

When a dashboard user isn't covered by your billing mode, they pay by card in a Stripe checkout composed of:

• Your retail price for each product (set in Custom pricing, or the FileForms list price if you haven't set one)
• The state fee as a separate line item
• For subscription products (annual report, registered agent), a recurring annual subscription

One behavior worth knowing: formation packages that include registered agent (the tier 2 and 3 packages) add the RA subscription as its own line item at checkout — the price your user sees is the formation price plus the RA price. See Custom pricing.

One balance, one currency of truth

The dashboard shows prices in dollars; API error responses and the transactions ledger use cents. Amounts on GET /organization/prices (defaultAmount, retailAmount, wholesaleAmount) are whole dollars.