Billing And Usage

InvokeTool uses Better Auth for accounts, sessions, organizations, roles, and API keys. Dodo Payments owns checkout, subscriptions, billing portal flows, and billing webhooks.

The Cloudflare Worker creates Better Auth with the request's D1 DB binding, the organization plugin, the admin/access-control plugin, and API keys. The tracked 0000_better_auth.sql migration creates those auth tables before the marketplace and billing migrations run.

Server-Owned Billing State

Billing state is stored in billing_account and updated from verified Dodo webhooks. Webhook events are persisted in dodo_webhook_event by webhook ID so retries are idempotent.

Hosted Billing API

The API exposes authenticated billing procedures:

• billing.account returns the current Dodo customer, subscription, plan, status, period dates, and update timestamp for an organization.
• billing.checkout creates a Dodo checkout session for the configured Pro product or an explicit product ID. The server must have DODO_PRO_PRODUCT_ID and DODO_SUCCESS_URL configured unless the caller supplies explicit overrides.
• billing.changePlan starts a checkout flow for a new product or plan.
• billing.portal creates a time-bound Dodo customer portal URL from the stored Dodo customer ID.

Checkout requests include organization_id metadata so subsequent verified webhooks can update the correct billing account. Billing checkout, plan changes, and portal access require an interactive Better Auth browser session. API keys can only read billing/account and usage metadata when they carry project:read and metadata for the same organization_id. Session callers must be active members of the requested organization.

Billable Usage

InvokeTool bills only for hosted integration downloads. Hosted marketplace/API tool calling is metered for usage visibility but priced at zero by default, and runtime activity inside an embedding application's SDK process is not a hosted billable signal.

The API writes metered rows to billable_event for:

• marketplace.api_call: authenticated organization-scoped marketplace API calls, priced at zero by default.
• artifact.download: internal meter name for signed integration download access.

Integration download history is stored in artifact_download with organization, module, version, checksum, SDK name, SDK version, user agent, hashed IP address, and timestamp. Provider credentials are never included in billing or download records. Usage summaries are always organization-scoped: the console requests metrics for the active organization workspace, API keys fall back to their Better Auth organization_id metadata, and unscoped API keys are rejected. Only paid integration-download usage is ingested into Dodo metering. Free marketplace/API calls and integration downloads inside the monthly allowance stay in InvokeTool usage history without creating Dodo usage charges.

Marketplace Caching

Read-only marketplace metadata is cached at the Cloudflare edge before returning to SDKs and the console. Search results use a short cache window, stable module and category metadata use a longer cache window, and exact version/snapshot metadata is treated as immutable for a day. Installs, updates, uninstalls, integration download records, wallet debits, and Dodo webhook processing are never served from cache.

This reduces repeated D1 reads for hot modules and SDK install paths while keeping billable usage, integration download history, and wallet ledger writes on the authoritative path.

Wallet Credits And Auto-Refill

Organizations can use a prepaid wallet for integration downloads. Wallet state is stored separately from Dodo subscription state:

• wallet_account stores balance, currency, auto-refill settings, and the billing email used to create refill checkout sessions.
• wallet_ledger_entry stores every credit and debit with the resulting balance so usage can be audited.
• wallet_top_up tracks Dodo checkout sessions used to add funds, including auto-refill sessions created after low-balance usage.

The hosted API exposes wallet procedures:

• billing.wallet returns the current organization wallet.
• billing.walletLedger returns recent ledger entries.
• billing.walletTopUp creates a Dodo one-time checkout session for adding funds. The checkout metadata includes wallet_operation=top_up, organization_id, and wallet_amount_cents.
• billing.walletSettings enables or updates auto-refill thresholds and refill amounts.

When recordBillableUsage writes a billable event, it prices the event with fractional millicent rates. MARKETPLACE_API_CALL_PRICE_MILLICENTS=0 keeps cached marketplace browse/search and hosted tool calling free, and ARTIFACT_DOWNLOAD_FREE_ALLOWANCE_MONTHLY=500 includes the first 500 integration downloads per organization each UTC calendar month. After that allowance, ARTIFACT_DOWNLOAD_PRICE_MILLICENTS=2 charges $0.02 per 1,000 integration downloads independent of download byte size. Download byte counts are still stored as metadata for audit and cost analysis, but they do not affect wallet pricing. Sub-cent charges accumulate in wallet_meter_accumulator until they reach one cent, then the API debits the organization wallet and records the debit in the wallet ledger. If the balance falls at or below auto_refill_threshold_cents, the API creates one pending Dodo checkout session for auto_refill_amount_cents and stores it in wallet_top_up.

Dodo webhook processing credits the wallet only after a verified webhook carries top-up metadata. Existing pending top-ups are marked completed, and duplicate completed checkout sessions are ignored so repeated webhooks do not double-credit the wallet.

Operational Checks

Production deployments should monitor:

• Dodo webhook verification failures.
• Duplicate webhook retries.
• Billing state update failures.
• Integration download failures.
• Billable usage write or Dodo ingestion failures.
• Wallet debit failures and low-balance auto-refill checkout failures.