# Pricing, balance and usage (https://docs.getbeel.com/en/api/pricing)

Pay as you go from a prepaid balance. The price list, the balance, top-ups, usage and the 402 insufficient_balance error.

Using Getbeel is free: the app, sandbox, API, MCP server, webhooks, deadline calendar, registers and exports. You only pay for what costs money, from **one prepaid EUR balance per billing account**. A gestore with many client companies has one balance, and the tiers count all its companies. Prices exclude VAT.

## Price list [#price-list]

**Sending to SDI** (invoices, credit notes, autofatture TD16–TD20: every document sent to SDI), in tiers per calendar month:

| Sends per month | Price per send |
| --------------- | -------------- |
| 1–1,000         | €0.15          |
| 1,001–10,000    | €0.12          |
| above 10,000    | €0.10          |

| Item                                                         | Price  |
| ------------------------------------------------------------ | ------ |
| Invoice received from SDI                                    | €0.15  |
| Document read by AI (email scan, forwarding address, upload) | €0.03  |
| Connected bank account, per month                            | €2.00  |
| Imported bank movement                                       | €0.02  |
| F24 paid (any F24: VAT, bollo, withholdings, INPS, advances) | €1.00  |
| LIPE filed                                                   | €3.00  |
| OSS return filed                                             | €3.00  |
| Annual VAT return filed                                      | €12.00 |
| IRES/IRAP return filed                                       | €9.00  |
| Redditi PF return filed (self-employed, any regime)          | €9.00  |

A filing is charged once per type, period and company, when it is paid or filed (its receipt recorded): preparing it (by hand or automatically), preparing it again and skipping it are free. Saving the tax estimate inputs is free. A bank movement is charged once, when it is imported (bank feed or statement upload): importing it again (the same statement, a sync returning it, an overlapping statement) is free, and an uploaded statement does not save again a movement already imported for the same bank account (recognised by bank name and last 4 digits). The tax profile, regime detection, the calendar and alerts are free. Quotes, proforma, PDFs, reminders and resending after a rejection are free.

Example: 200 companies that send 20 invoices and receive 30 a month through SDI make 4,000 sends (€510) and 6,000 receipts (€900): €1,410 a month.

`GET /billing/prices` returns the same list (cents, net of VAT).

## Balance and top-ups [#balance-and-top-ups]

- **Welcome credit**: €1 once per account (and per card and VAT number), valid 90 days, when you save your first card. A card that already got it on another team gets no second one: Billing & usage says "The welcome credit applies only once per card." The welcome credit is for new accounts only.
- **Top-ups**: from €10, with an invoice for every top-up (VAT at checkout). Paid credit is valid 12 months.
- **Auto top-up**: off by default; when the balance drops below a threshold it adds an amount with the saved card. If the card is declined it retries once after 24 hours, then turns off.
- **Low-balance alert**: the warning on Billing & usage, the red sidebar balance and the email start once you have paid credit: a top-up (by hand or automatic) not refunded in full; the welcome credit alone does not count. The line is €10 unless you change it.
- **Balance at zero**: new paid actions stop. Receiving invoices from SDI never stops: it can take the balance down to -€10, taken from the next top-up.

`GET /billing/balance` returns `pricing` (`pay_as_you_go`, or `legacy_plan`: see [Accounts on a plan](#accounts-on-a-plan)), the balance in cents (`balance_cents`), credit expiring in the next 30 days (`expiring_soon_cents`), auto top-up and the low-balance alert, `welcome_credit` (`granted`, and `not_granted_reason`: `card_already_used`, `legacy_plan`, `no_card` or null), and `topup_url`. The balance may lag by up to a minute.

`POST /billing/topups` with `amount_cents` creates a Stripe payment link (`checkout_url`) for a person to pay: the API never charges a card. It needs a live key with the `billing:write` scope (never ticked by default), created by someone who manages billing. With a client company's own key the `/billing` endpoints answer 403 `billed_to_parent`: the balance and usage are on the gestore's account. The Stripe page opens in the language of the person who created the key (else the team owner's, else Italian for an Italian company) and offers only the current default card (Stripe Checkout cannot preselect one saved card, so the others are hidden there; another card can still be typed in).

```bash
curl https://getbeel.com/api/v1/billing/balance \
  -H "Authorization: Bearer $GETBEEL_LIVE_KEY"

curl -X POST https://getbeel.com/api/v1/billing/topups \
  -H "Authorization: Bearer $GETBEEL_LIVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount_cents": 2500}'
```

`POST /billing/payment-method` (no body) creates a Stripe link (`checkout_url`, setup mode: nothing is charged) where a person enters a new card: it becomes the default card and the one auto top-ups charge. The same card saved twice is kept once. Same key and scope as top-ups; 409 `no_card` when no card is saved yet, as `application/problem+json` in the same shape as the 402 below. MCP: `create_billing_card_link`.

## Usage [#usage]

`GET /billing/usage?month=2026-12` returns per item (`by_meter`) the quantity, amount and the next send's price at this month's tier, and per company (`by_company`) for a gestore.

## Insufficient balance (402) [#insufficient-balance-402]

A paid action the balance does not cover answers **402** `application/problem+json` with `code` `insufficient_balance`, `balance_cents`, `required_cents` and `topup_url`, plus the usual `error` object. Here `balance_cents` is the available balance (the balance minus amounts reserved for actions in progress), never below 0. For a client company billed to its gestore the answer has no `balance_cents` and no `topup_url` (the balance is the gestore's): the message asks the account that bills the company to add credits. MCP tools return the same text. See [Errors](/en/api/errors).

## Accounts on a plan [#accounts-on-a-plan]

Customers who signed up before 13 November 2026 keep their plan (or the SDI add-on), its prices and everything it includes, with no end date: with an active paid plan, tax filings and connected bank accounts are included, and without a plan they stay closed as before (402 `subscription_required`). Pay as you go is only for accounts created from that day.

For these accounts `GET /billing/balance` answers with `pricing: "legacy_plan"`, amounts at 0, `topup_url` null and `welcome_credit.not_granted_reason: "legacy_plan"`. `GET /billing/usage`, `POST /billing/topups` and `POST /billing/payment-method` answer 409 `not_pay_as_you_go`. `GET /usage` returns the month's SDI transactions (`sdi_transactions`, `free_allowance`, `email_extractions`, `estimated_amount`, `rate_card`, `received_unit_amount`, `email_extraction_unit_amount`).
