Usage, credits, plans and budgets (commercial edition)
Example prices, not final
Every rate on this page and in plans.yaml is an example taken from the pricing proposal
(research/11 §3), except the credit packs, whose prices the owner has decided (below). All of
them are data: change plans.yaml (or point DX_BILLING_PLANS_FILE at your own) without
touching code.
This layer lives in ee/ (FSL-1.1-ALv2, see Editions). Without extractit-ee
installed /v1/usage, /v1/billing/* and /v1/budgets answer 404, no run is ever refused for
credits or budget, the page does not appear in Settings, and the core's node_run and model-call
ledgers keep recording tokens and measured cost.
What is metered
Every activity the interpreter closes (a node and its scope, T26) writes one usage_event:
pages, input and output tokens, measured cost (cost_micro_usd), the tier, the plan, the
billable_credits, env (production or test) and byok. The row is idempotent by
(tenant_id, idempotency_key) with idempotency_key = sha256(run_id | node_id | scope_key): a retry
or a recovered run leaves one row and one consumption.
Not charged: failed activities, cache hits (they did no work), deterministic validations, exports,
parse (its pages are included in the tier price of the extract that consumes them) and every run
of purpose test. One-shot POST /v1/parse and POST /v1/extract runs have no activities: they are
metered once when the run finishes, from the run's own totals.
Plans and rates (plans.yaml)
credit_eur: 0.001 # 1 credit = 0.001 EUR
tiers: {flash: 4, fast: 12, standard: 22, agentic: 90} # credits per page
byok_platform_fee: 6 # credits per page when the customer pays its own model provider
plans:
pay_as_you_go: {included_pages_per_month: 0} # the default plan
developer: {included_pages_per_month: 1000}
business: {included_pages_per_month: 50000}
billable_credits = billed_pages × rate. The plan's monthly allowance (calendar month, UTC) is
used before any purchased credit: pages 1 to 1 000 of the month are free on developer, page 1 001
costs 22 in standard, and on the first day of the next month the allowance renews. A change of
plan in mid-month keeps the pages already used (left = included − pages of the month). AI rules are
billed per evaluation (validate: {billing: per_model_call, credits: 2}), deterministic ones cost 0.
GET /v1/billing/plans lists the catalog and the organization's plan; PUT /v1/billing/plan (Owner)
changes it.
Credits: ledger, reservations, settlement
- Ledger.
ee_credit_ledgeris append-only (dx_appcanSELECTandINSERT;UPDATE,DELETEandTRUNCATEare revoked). Entry types:grant,topup,consume,refund,expire,adjustment. Every write locks the organization's singleee_credit_balancerow, sobalance_afteris consistent under any concurrency and the sum of the ledger always equals the balance. Entries are idempotent byidempotency_key. - Reservation.
POST /v1/runs(and rerun, batch, one-shot extract) creates the run and, in the same transaction, the guard compares the estimate withbalance − live reservationsand with every budget that counts the run. If it does not fit the transaction rolls back: 402insufficient_creditsorbudget_exceeded, no run exists and nothing was enqueued. If it fits, the run holds a reservation until it finishes (or untilDX_BILLING_RESERVATION_TTL_SECONDS). - Settlement. Consumption is recorded as activities close. When the run reaches a terminal
status the reservation is settled: it records the real consumption next to the estimate
(
actual_credits,status = settled), orreleasedfor a cancelled run. - Estimate.
pages × Σ tier rate of the workflow's billable nodes, minus the allowance left;pagesdefaults toestimate.default_pagesofplans.yamlbecause the size of a packet is not known when the run is created. It can differ from the real consumption; settlement uses the real one. Consumption of work already done may take the balance slightly below zero; the next admission then fails with 402.
Hook points used (declared by the core, see Editions): runs.created
(guard and reservation), runs.finished (settlement) and interpreter.activity_closed (metering).
Billing modes (DX_BILLING_MODE)
| Mode | Who adds credits | Limits runs by credits | POST /v1/billing/topups |
Stripe imported |
|---|---|---|---|---|
none (default) |
nobody | no (budgets still apply) | 409 TOPUPS_MANUAL |
no |
manual (self-hosted) |
an administrator: POST /v1/billing/credits:grant (admin scope) |
yes | 409 TOPUPS_MANUAL |
no |
saas |
the customer, buying a credit pack with Stripe Checkout | yes | 201 with the Checkout URL |
yes, lazily |
saas mode reads DX_STRIPE_SECRET_KEY and DX_STRIPE_WEBHOOK_SECRET (never logged) and needs the
stripe SDK (pip install extractit-ee[stripe]). The full set-up is in
Stripe (credit packs and Managed Payments).
Stripe is only exercised with a simulated transport
The tests replace Stripe's HTTP transport (respx) and sign webhooks with a made-up secret;
no Stripe account, key or sandbox was used. Run the bootstrap, a Checkout and the webhooks
against the Stripe sandbox before enabling saas (see the checklist below).
Stripe (credit packs and Managed Payments)
Customers buy prepaid credits in packs with card, on Stripe-hosted Checkout. Stripe acts as the
merchant of record (Managed Payments):
it calculates and declares the tax, handles fraud and disputes, and issues the receipts. The packs
are data in plans.yaml (final prices, with a volume discount against pack_10k: 1.00 € per 1 000
credits, 0.90 € (−10 %) and 0.80 € (−20 %)):
credit_packs:
- { id: pack_10k, credits: 10000, price_eur: 10 }
- { id: pack_50k, credits: 50000, price_eur: 45 }
- { id: pack_200k, credits: 200000, price_eur: 160 }
stripe:
managed_payments: true # false: an ordinary (non-merchant-of-record) Checkout
product_tax_code: txcd_10000000 # must be eligible for Managed Payments
tax_behavior: exclusive # tax added on top of price_eur
The client is pinned to Stripe API version 2026-10-28.endive and the latest Python SDK (17.x). Checkout
never sets payment_method_types (dynamic payment methods are managed in the Dashboard), and it does not set
automatic_tax, customer_update or tax_id_collection: with Managed Payments Stripe owns the tax, so those
parameters are left out.
1. Account and keys
- Create the Stripe account, complete the business profile and activate Managed Payments in Dashboard → Settings → Managed Payments. Work in the sandbox first.
-
Create a restricted key (
rk_test_…, laterrk_live_…) with exactly these permissions:Resource Permission Products, Prices Write Checkout Sessions Write Customers Write Customer portal (Billing Portal: sessions and configurations) Write Events Read Do not use the secret key
sk_…in production. Put the key inDX_STRIPE_SECRET_KEY; the bootstrap warns when it is ansk_key. 3. SetDX_BILLING_MODE=saas,DX_STRIPE_SECRET_KEYand, after step 3,DX_STRIPE_WEBHOOK_SECRET. Make the redirects absolute:DX_BILLING_SUCCESS_URL(https://app.extractit.dev/settings/usage-billing?topup=success),DX_BILLING_CANCEL_URL(…?topup=cancelled) andDX_BILLING_PORTAL_RETURN_URL(https://app.extractit.dev/settings/usage-billing). The success page only informs the customer: credits are added from webhooks, never from the redirect.
2. Bootstrap (idempotent)
DX_STRIPE_SECRET_KEY=rk_test_… python -m extractit_ee.billing.stripe_setup
It creates or updates the product ExtractIt credits (extractit_credits, with the tax code), one
Price per pack whose lookup_key is the pack id (found by lookup_key before creating: running
it again changes nothing; if you change a pack's price a new Price takes the key and the old one is
archived) and a Billing Portal configuration (invoice history) when the account has none. It prints
Stripe ids, never keys. Run it again after editing credit_packs.
3. Webhook
Subscribe an endpoint https://<your API>/webhooks/stripe to exactly these events and copy its
signing secret to DX_STRIPE_WEBHOOK_SECRET:
| Event | Effect |
|---|---|
checkout.session.completed |
adds the credits when payment_status is paid |
checkout.session.async_payment_succeeded |
adds the credits of a delayed payment method |
checkout.session.async_payment_failed |
recorded, nothing is added |
charge.refunded |
a negative ledger entry (adjustment) for the share of the credits refunded |
charge.dispute.created |
a negative entry for the share of the credits disputed |
Any other event answers 200 and changes nothing. Each event id is applied once and each Checkout
Session adds its credits once even if both completed and async_payment_succeeded arrive. A
reversal can take the balance below zero; the guard then refuses new runs with 402
insufficient_credits until the customer buys again. A refund or a dispute never takes back more
credits than the purchase gave, in total (refund 25 % then 50 % reverses 50 %; a dispute after a
full refund reverses nothing more).
4. Test locally
stripe listen --forward-to localhost:8000/webhooks/stripe # prints the whsec_… to use locally
stripe trigger checkout.session.completed # no tenant metadata: answers 400
Buy a pack from Settings → Usage and billing with the test card 4242 4242 4242 4242; the credits
arrive when the forwarded checkout.session.completed is processed. The opt-in test
ee/tests/test_ee_stripe_live.py (marker stripe_live) runs the bootstrap and creates a real
Checkout Session in the sandbox; it is skipped unless the key starts with rk_test_ or sk_test_.
5. Customers and the portal
The first purchase creates a Stripe Customer for the organization (stored in ee_stripe_customer,
tenant-isolated) that later purchases reuse; creation is idempotent per organization.
POST /v1/billing/portal (admin scope) returns a Stripe Billing Portal URL for it, with the
invoice history, and sends the customer back to DX_BILLING_PORTAL_RETURN_URL; it answers 409 until
the organization has bought something.
Go-live checklist
- [ ] Managed Payments is activated and the product's tax code is eligible (Settings → Managed Payments).
- [ ] A public website with prices (the packs and what a credit buys), terms of service,
privacy policy, refund policy and the contact
billing@extractit.dev. - [ ] Bootstrap and webhook repeated with the live restricted key (
rk_live_…) and the live signing secret; the five events above, no more. - [ ] A live purchase of the smallest pack, its receipt and its refund verified (the refund must take the credits back).
- [ ]
DX_BILLING_*_URLpoint athttps://app.extractit.dev/…; the Stripe account's statement descriptor and support details are correct. - [ ] Alerts on webhook failures (Dashboard → Developers → Webhooks) and a rotation plan for the key.
Budgets and alerts
PUT /v1/budgets creates or replaces the budget of one target: the organization, a project
(prj_…) or a workflow (wf_…), monthly, in credits or usd (the measured model cost of events
that did not use the customer's own credentials). With hard_stop a run that would pass the limit
(consumed + reserved + estimate) is refused before it exists (402 budget_exceeded, with the
budget in budget); without it the run is accepted and the alert is emitted. A workflow budget only
blocks its workflow.
At 50, 80 and 100 % of the limit each budget emits one budget.threshold_reached event per
period and threshold (a unique (budget_id, period, threshold) row), visible in
GET /v1/budgets/{id}/alerts and in the outbox of the run that crossed it. The next month can alert
again. The event is documented by schemas/events/budget.threshold_reached-1.0.json, generated from
extractit_ee.billing.events (T27's webhooks subscribe to the outbox without changes).
Notification channels (Apprise)
PUT /v1/billing/notification-channels replaces the organization's channels. Each channel is an
Apprise URL (slack://…, msteams://…, mailto://…,
json://…): sealed with the organization's key (T11), write-only, listed masked
(slack://••••••abcd) and never logged. After the transaction that created an alert commits, a
background thread sends it with up to DX_BILLING_NOTIFY_RETRIES (3) attempts and exponential backoff;
a failing channel never blocks the settlement (the alert is marked failed). With no channel the
alert is stored as no_channel and only the event is emitted. The event and
GET /v1/budgets/{id}/alerts are the source of truth: a permanently failing channel can lose a
notification.
Welcome credits (saas)
Every new organization of the managed service gets 1 000 welcome credits (T64). They are promotional credits, kept apart from the purchased ones:
- they pay pages of the Flash tier only (
welcome_credits.max_tier); a page of a higher tier never spends them; - they expire 30 days after the grant and are not refundable;
- they are granted once per organization and once per verified email, never to a disposable
email domain, and only with
DX_BILLING_MODE=saas(noneandmanualgrant nothing).
# plans.yaml
welcome_credits: { credits: 1000, max_tier: flash, expires_days: 30 } # credits: 0 turns them off
When they are granted. There is no self-service sign-up in the core: an organization gets its first
Owner from DX_BOOTSTRAP_OWNER_EMAIL (first login) or python -m extractit.identity.admin grant-owner.
Both refuse an email the identity provider did not verify (email_verified claim of the ID token,
stored in users.email_verified). When that Owner is created, the core runs the hook
identity.owner_verified and the commercial edition grants the credits. If the hook fails the
ownership stands and the failure is logged. An organization whose Owner has no verified email gets
nothing.
Spending order. A page of a tier up to max_tier spends welcome credits first (earliest expiry
first), then purchased credits. A page of a higher tier spends purchased credits only. The usage event
of the page records both parts (billable_credits, promo_credits); the purchased part is the
consume entry of the ledger, so Σ ledger = balance still holds and refunds and disputes (T61) only
ever see purchases.
Admission. The guard splits the estimate of a run by tier. The part welcome credits can pay is held
in ee_credit_reservation.promo_amount, the rest in purchased credits. When the purchased credits
do not cover the part in uncovered tiers the run is refused with 402 credits-tier-not-covered
(welcome credits cover the Flash tier; buy credits to use Standard); when the tier is covered but the
credits are not enough it stays insufficient_credits. A run is never downgraded to Flash silently.
Expiry is computed on read: a bucket with expires_at <= now stops counting for balance,
admission and consumption. There is no welcome_expired ledger entry to schedule or get wrong, the
purchased balance is never touched, and amount - remaining stays as the audit of what was spent.
Anti-abuse. The email is canonicalized (lower case, +tag removed, dots removed for Gmail and
googlemail.com mapped to gmail.com) and only its SHA-256 is stored in ee_welcome_claim, a table
with no foreign key to the organization: deleting an organization does not free its email. Disposable
domains come from ee/src/extractit_ee/billing/data/disposable_email_domains.txt, the
disposable-email-domains
blocklist (CC0 1.0, commit pinned in the file header, listed in NOTICE); a domain or any parent
domain in the list is refused. Refresh the file by copying the upstream
disposable_email_blocklist.conf under the same header. This does not stop someone with many real
mailboxes: it raises the cost, it is not identity proofing.
What the Flash tier runs today. flash is a billing tier of the node (tier: flash; classify and
split are always Flash) and a parse profile (ParseProfile.tier). The Flash parse
(see Parsing digital PDFs) calls no model: it reads the text layer with local layout and
table models. For model calls, the router picks the model from the policy of the organization and the
catalog in Models; the Flash tier is meant for the cheapest paid models of the fast
tier (for example anthropic:claude-haiku-5-5, gemini:gemini-3.5-flash-lite, openai:gpt-6-luna),
which are paid APIs with provider terms that do not train on API data. A free API tier that trains on
data is never used for welcome credits. There is no automatic mapping from the flash billing tier to
one model: a node pinned to a model, or a policy that resolves a more expensive one, is still billed at
the tier of the node.
API
| Route | Permission | Notes |
|---|---|---|
GET /v1/usage?group_by=project\|workflow\|operator\|model\|day&from&to |
usage:read (Owner, Admin, Auditor) |
totals = sum of the rows = what the ledger consumed |
GET /v1/usage/export.csv |
usage:read |
cells starting with =, +, -, @ are prefixed with ' |
GET /v1/billing/balance, /ledger, /plans |
usage:read |
balance also returns paid (amount, reserved, available: the purchased credits, same as the top-level balance, reserved, available) and promo (amount, reserved, available, expires_at, max_tier: welcome credits not expired; 0 and null when none) |
PUT /v1/billing/plan |
org:manage (Owner) |
|
POST /v1/billing/topups |
project:manage |
{"pack_id"} (or credits equal to one pack, else 400): Checkout URL in saas; otherwise 409 TOPUPS_MANUAL |
POST /v1/billing/portal |
project:manage (admin scope) |
Stripe Billing Portal URL; 409 before the first purchase |
POST /v1/billing/credits:grant |
project:manage (admin scope) |
manual mode; idempotent by idempotency_key |
GET/PUT /v1/billing/notification-channels |
read / project:manage |
|
GET/PUT /v1/budgets, DELETE /v1/budgets/{id}, GET /v1/budgets/{id}/alerts |
read / project:manage |
|
POST /webhooks/stripe |
signature | saas only |
Errors are RFC 9457: 402 insufficient_credits, 402 budget_exceeded, 409 TOPUPS_MANUAL, 400 validation-error (unknown pack). These
codes exist only with the commercial edition (they are not in the community OpenAPI snapshot).
Settings page
Usage and billing (S15) in Settings, only in the ee build of the Studio: balance and plan, usage with a grouping selector, totals and CSV download, budgets with their alerts, notification channels (URLs masked) and the top-up of the billing mode (credit packs with Checkout and a Manage billing button for the portal, manual grant, or hidden). Owner and Admin manage; an Auditor reads. Texts are text nodes; Spanish and English.
Configuration
| Variable | Default | |
|---|---|---|
DX_BILLING_MODE |
none |
none, manual or saas |
DX_STRIPE_SECRET_KEY, DX_STRIPE_WEBHOOK_SECRET |
— | saas only; restricted rk_ key |
DX_BILLING_SUCCESS_URL, DX_BILLING_CANCEL_URL, DX_BILLING_PORTAL_RETURN_URL |
relative Studio paths | make them absolute (https://app.extractit.dev/…) |
DX_BILLING_PLANS_FILE |
the shipped plans.yaml |
your own prices |
DX_BILLING_RESERVATION_TTL_SECONDS |
21600 |
a run that never finishes loses its hold |
DX_BILLING_NOTIFY_RETRIES, DX_BILLING_NOTIFY_BACKOFF_SECONDS |
3, 1 |
Apprise delivery |
Migrate with python -m extractit.store.admin migrate (core, then the ee chain: ee_0004).