Billing & Usage - mAIvn Docs

#Billing models

The SDK exports billing and plan-limit read models so applications can validate usage payloads obtained from an authorized application integration:

BillingUsage, BillingUsageBreakdown, BillingUsageProject, BillingUsageApiKey, and BillingUsageTotals
BillingPlan and BillingCurrentUsage

These are data models, not a billing client. The public Client does not expose get_usage() or another billing-fetch method. Obtain billing data through a documented application integration, then validate it explicitly:

Python

from maivn import BillingUsage

payload: dict[str, object] = {
    "organization_id": "org-123",
    "period_start": "2026-08-01T00:00:00Z",
    "period_end": "2026-09-01T00:00:00Z",
    "usage": {},
    "breakdown": {
        "organization_id": "org-123",
        "period_start": "2026-08-01T00:00:00Z",
        "period_end": "2026-09-01T00:00:00Z",
    },
}

usage = BillingUsage.model_validate(payload)
print(usage.organization_id)
print(usage.breakdown.totals.billed_tokens)

Treat these models as the schema for a payload, not proof that every declared limit is enforced in every environment. The service that supplies the payload remains authoritative for current plan availability, prices, allowances, and enforcement.

#Automatic reload

Automatic reload is a per-organization Portal setting. It is off by default and requires an eligible plan, a saved payment method, and an environment where billing is enabled. The Portal hides the control while hosted billing is disabled.

When available, the setting includes:

Field	Meaning
`enabled`	Whether future reload attempts are allowed.
`reload_dollars`	Whole US dollars requested for each reload, within the limits returned by the service.
`trigger`	A remaining-percent or remaining-units threshold.
`period_cap_cents`	Optional maximum automatic-reload spend for one billing period.

The readout returns whether reload is available, the current quote for the chosen amount, payment-method readiness, period status, and any paused reason. Use that readout rather than copying plan amounts or rates into application code. Catalog, plan, and price values can change independently of the SDK.

Saving a setting is not a charge. When billing is enabled, each reload attempt has an idempotent identity so a transport retry refers to the same charge. A failed charge grants no allowance and can pause the setting. Exact retry timing, notifications, allowances, and plan eligibility remain service behavior and must be confirmed in the environment where billing is enabled.

The public SDK does not expose an automatic-reload client. Use the Developer Portal or another documented application integration rather than guessing private service routes.