Skip to content

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_ledger is append-only (dx_app can SELECT and INSERT; UPDATE, DELETE and TRUNCATE are revoked). Entry types: grant, topup, consume, refund, expire, adjustment. Every write locks the organization's single ee_credit_balance row, so balance_after is consistent under any concurrency and the sum of the ledger always equals the balance. Entries are idempotent by idempotency_key.
  • Reservation. POST /v1/runs (and rerun, batch, one-shot extract) creates the run and, in the same transaction, the guard compares the estimate with balance − live reservations and with every budget that counts the run. If it does not fit the transaction rolls back: 402 insufficient_credits or budget_exceeded, no run exists and nothing was enqueued. If it fits, the run holds a reservation until it finishes (or until DX_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), or released for a cancelled run.
  • Estimate. pages × Σ tier rate of the workflow's billable nodes, minus the allowance left; pages defaults to estimate.default_pages of plans.yaml because 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

  1. Create the Stripe account, complete the business profile and activate Managed Payments in Dashboard → Settings → Managed Payments. Work in the sandbox first.
  2. Create a restricted key (rk_test_…, later rk_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 in DX_STRIPE_SECRET_KEY; the bootstrap warns when it is an sk_ key. 3. Set DX_BILLING_MODE=saas, DX_STRIPE_SECRET_KEY and, 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) and DX_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 [email protected].
  • [ ] 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_*_URL point at https://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 (none and manual grant 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).