Billing & Credits

Hobby, Pro and Scale remain wallet-credit subscriptions with account resource limits. Spend their credits on capped PAYG or a prepaid monthly resource pool. There is one wallet and ledger; monthly coverage records an upfront spend from that balance. Personal scope is the default and namespaces are optional. Read /credits/plans for account tiers and the capacity catalog for USD resource rates. Existing usage contracts retain their saved metering terms until explicitly changed.

For new capacity contracts, PAYG meters active CPU, reserved running RAM and retained provisioned storage. Monthly payment covers the purchased CPU/RAM/disk pool and an included managed-internet transfer allowance throughout the paid period. PAYG transfer and optional monthly overage use the same credit wallet, with warnings, bounded courtesy grace and configurable spending limits. The dashboard shows actual cap discounts and a comparison that includes prepaid fees. A cap limits a usage bill; it does not itself buy a month. See managed transfer.

Choose the matching billing reference

Deploying the new compute product does not migrate existing subscriptions. Read billing.capacity(namespace) and billing.entitlement(namespace) to determine the saved contract. Use the documented mode or plan change to adopt different terms. Changing a credit quota or resource limit alone does not purchase capacity.

Legacy credit metering

1. While a workspace is running, the platform collects usage metrics (CPU time, memory, disk I/O, network)
2. Metrics are collected and converted to pricing units
3. Credits are debited from your account balance

Credits vs. quotas — two layers

For existing credit-metered contracts, Oblien separates money from limits:

• Credit balance + ledger — your spendable balance, backed by an immutable transaction ledger. Usage deducts; top-ups and grants add. This is the source of truth for "how many credits were used."
• Namespace quotas (optional) — per-(namespace, service) ceilings with overdraft + threshold actions, for capping what a tenant can spend. A quota is a consumption allowance. In Mode A your backend owns renewal; in hosted Mode B Oblien applies each verified paid renewal once (see Namespace quotas).

Use the balance alone, or layer namespace quotas on top for hard per-tenant caps.

Pricing units

The following units belong to the existing credit meter. New capacity contracts use active CPU, reserved RAM and retained provisioned storage as described in PAYG and monthly compute.

Credit rates

Rates and monthly discounts for the existing credit meter are available at GET /pricing/calculator and Existing credit-contract rates. New compute quotes use /billing/capacity/catalog. An unavailable API does not produce a fallback price quote.

A direct wallet deposit starts at $5 and buys 100 credits per USD. New wallet packages use the same rate; there is no automatic bulk bonus. Saved paid orders and subscriptions keep their recorded price and credit grant. Custom reseller offers still support $1–$10,000 independently of the direct wallet minimum.

Monthly workspace discounts and namespace budgets

The legacy workspace meter applies per-workspace CPU, memory and network discounts in each UTC calendar month. Read their current amounts from /pricing/calculator; an opened cap record keeps its saved rates. These discounts limit legacy metered charges. Prepaid capacity has its own paid billing period and saved terms.

Discount consumption is persisted for the owner, namespace, workspace and month. Cap state, wallet debit, namespace usage, ledger entry and credit-alert outbox commit in one database transaction. Frozen node billing windows replay with the same identity and amounts after a lost response or restart. Prices are saved when the month's cap record is opened; configuration changes do not reprice that record.

Top-ups, refunds, namespace quota resets and API restarts do not reset consumed discounts. A resize preserves already charged credits; the legacy policy retains the highest allocation's cap for that calendar month. Crossing a UTC month apportions the window's usage by elapsed time because legacy counters do not timestamp individual events. This calendar is independent of the subscription's paid anniversary.

Under the legacy credit contract, namespace budgets block new work and can stop running workspaces when exhausted. Already consumed usage is settled before the exhaustion action; a distributed meter does not provide an instantaneous zero-overshoot cutoff.

Historical compute proposal — preview only

GET /pricing/compute-rate-cards describes the earlier workspace-2026-09-29 proposal, and POST /pricing/compute-estimate estimates it. That proposal remains chargeEnabled: false.

The deployed capacity product has its own versioned tariff and active meters. Read /billing/capacity/catalog for its actual prices. The historical proposal's disk and public-egress terms do not describe current capacity checkout. Existing contracts continue using their saved terms.

What costs credits

This table describes the legacy workspace credit meter only. With current PAYG, retained storage remains billable while stopped and reserved RAM remains billable while paused. A prepaid monthly fee remains fixed throughout its paid period.

CDN media

Images, videos, documents and archives debit the same wallet with service: "cdn". Storage is charged by retained byte-time; delivery is charged by bytes sent from Oblien. Namespace byte ceilings and CDN spending quotas apply together. Monthly VM capacity does not cover CDN usage. Read CDN storage and traffic and the current /cdn/catalog rates.

Managing costs

Use temporary mode

Auto-expire workspaces to avoid forgetting to stop them:

await ws.create({
  config: { ttl: '1h', ttl_action: 'stop' },
});

Stopping a current PAYG workspace releases running compute after confirmation; retained disks keep accruing storage usage. A monthly fee is unchanged by stop or pause. Billing expiry retains data under the saved retention policy; it does not invoke a user-configured delete-on-TTL action.

Right-size resources

Don't over-provision. Start small and scale up:

// Start with minimum resources
await ws.create({
  config: { cpus: 1, memory_mb: 256 },
});

// Scale up only when needed
await ws.resources.update(id, { cpus: 4, memory_mb: 4096, apply: true });

Pause when idle

Pausing removes active CPU work but retains RAM. Under reserved-memory PAYG, paused RAM continues to be billed; hibernation releases it. A monthly fee is unchanged while paused:

await ws.pause(id); // Freeze; RAM remains allocated.
await ws.resume(id); // Resume when needed

Set namespace quotas

For legacy metered allowances, cap per-tenant spending with namespace quotas. For current compute contracts, use the saved PAYG cap or paid monthly pool and read billing.balance(namespace).blocking. A paid monthly pool has no second finite compute allowance.

Monitor usage

Track legacy credit consumption:

// Credits chart for a workspace
const chart = await ws.usage.creditsChart(id);
console.log(`Total credits burned: ${chart.total}`);

For current compute, read billing.capacity(namespace) for coverage, retained-storage amounts due, transfer and USD savings. monthlyDifference includes prepaid fees and can be negative for an idle pool.

Namespace quotas

Optional per-(namespace, service) spending ceilings for the existing metered product and other credit-billed services. They do not replace paid capacity coverage. Set them from the SDK (client.namespaces.setQuota) or the Dashboard. Key semantics:

• setQuota replaces the configured ceiling and preserves consumption. Mode A operators can change their allowance without resetting quota_used. Use hosted billing.checkout({ kind: 'topup', ... }) for purchased credits: verified payment adds a separate purchased allowance and preserves usage. Do not implement a purchased top-up as an unprotected read/increment/write or change a paid Mode B contract with setQuota.
• Usage auto-increments quota_used by the same credits charged to the balance.
• Mode A renewal uses the idempotent period operation documented in Namespaces API; use a stable cycle identity. Mode B renewal comes from the verified paid invoice: Oblien resets the included allowance once and carries only unused purchased credits. Do not run a second reset cron for hosted subscriptions. Neither operation resets workspace monthly discounts.
• Overdraft + thresholds — overdraft is a grace zone beyond the limit; onOverdraftAction (block | stop_workspaces) fires when it's exceeded; notificationThresholds (default [80, 95]) fire the namespace.quota.threshold webhook.
• Refunds of metered usage restore the appropriate wallet/usage amount. Payment refunds reverse the verified payment grant according to its saved cycle, without reducing a newer subscription cycle. They do not reset monthly discounts.

Full reference: Namespaces API → Quotas.

Using Oblien as your billing source of truth

For the existing credit-metered product:

• Raw usage units — client.namespaces.usageUnits(ns, { from, to, groupBy }) returns time-bucketed raw metered units (cpu_time_minutes, memory_gb_minutes, disk_io_gb, network_gb, plus derived vcpu_hours / gb_hours) so you can apply your own rates. Deterministic for a range → poll and idempotency-key on (namespace, bucket). Or subscribe the credits.usage webhook for the same units pushed per billing cycle.
• credits is authoritative. The credits value (in usageUnits, the ledger, and the credits.usage webhook) all come from one pricing engine — the exact amount charged to your balance and quota. There's no separate conversion table to maintain. The ledger value is the source of truth to display.
• Choose one renewal owner. Your backend applies Mode A cycles idempotently. Oblien applies hosted Mode B renewals. The separate legacy workspace discount uses a UTC calendar month; it does not change the customer's subscription anniversary.
• Retention — the transaction ledger is immutable and retained indefinitely, so 90-day (and longer) historical queries via usageUnits are safe. Usage read endpoints aren't rate-limited.

Plan allowances & credit packages

Use the Pricing page for current compute offers and wallet deposits. Existing account plans and credit subscriptions remain in the billing dashboard, with saved terms exposed by the billing APIs.