Skip to content

Test and trial accounts

A trial is an operator billing arrangement (a grant) on an existing tenant. The tenant signs up normally, or you declare it in bootstrap, and a platform operator sets the arrangement. Every command on this page needs a platform-operator session. For the arrangement fields themselves, see admin billing grant.

Terminal window
frameworks admin billing grant set --email [email protected] --tier enterprise \
--base-fee 0 --waive-usage --until 2026-12-31 --reason "Enterprise evaluation"
frameworks admin billing grant show --email [email protected]
  • --until takes a date, which includes that UTC day, or an RFC3339 timestamp for an exact deadline. Without it the grant lasts until you revoke it.
  • --tier assigns the tier in the same step. The tier the tenant had before is remembered as the fallback restored when the grant ends; --fallback-tier names another active tier.
  • A tenant that owes nothing (base fee 0 and usage waived) needs no card. With a base fee or billed usage and provider collection, rated work waits until the tenant adds a card.
  • Complete or recover a pending provider checkout before setting a grant. The refusal names the checkout deadline; it is not a deadline for the grant. See Checkout reservations.
  • An existing Stripe or Mollie subscription must be cancelled before a base-fee override.
  • An expired grant that is still awaiting reconciliation must be ended with grant revoke --tier or set-tier before you set another one. A refused replacement leaves the original grant and billing phase unchanged.

Run grant set again with the new deadline or terms. Renewing keeps the original fallback, also when --tier is omitted or unchanged, and keeps the current billing period open when only the deadline or nothing changes. Changed prices apply from the change on: closing documents keep the charges from before the grant and waive only the granted phase.

frameworks admin billing set-tier changes the granted tier through a billing boundary. An explicit set-tier clears the remembered fallback, and the arrangement continues on the assigned tier until it ends. An unchanged set-tier request is refused while a grant is outstanding: end the grant first, or assign a different tier.

To find trials that are about to end:

Terminal window
frameworks admin billing grant list --expiring 7d

A trial ends at its deadline on its own, or early with a revoke:

Terminal window
frameworks admin billing grant revoke --email [email protected] --reason "Evaluation complete"

A minute sweep closes an expired grant and restores its fallback tier. What the tenant can do next depends on that tier:

  • Back on zero-balance pay as you go, the tenant cannot start ingest or playback until it adds funds. An already running publisher with a positive balance is not stopped; prepaid suspension ends it once its balance becomes negative.
  • Without a recorded fallback, the current tier stays and collection readiness keeps deciding rated API work. Existing postpaid media admission is unchanged.
  • Free requires no payment provider.

If the recorded fallback tier was retired, grant revoke --tier <active-tier> chooses an active tier while closing the grant at its expiry boundary. Ended and replaced grants stay readable with grant list --include-expired for audit and historical pricing.

Signed media permission never outlasts the trial deadline, including on a media cell that is disconnected from the control plane. An early revoke reaches connected cells through authority refresh; a disconnected cell keeps already-issued permission until its signed expiry. Gateway billing caches refresh within about two minutes.

The billing page shows a “Plan arranged by FrameWorks” banner with the end date, the base fee, whether usage is waived, invoice collection, and the plan the account returns to when the arrangement ends. Usage stays metered and appears on each invoice at no charge when it is waived. Plan changes and checkouts are refused with the code OUTSTANDING_GRANT while the grant is in force, and the page tells the customer to contact FrameWorks instead. A scheduled downgrade waits until the grant ends.

Purser emails the tenant’s billing email once a grant’s end date is seven days or less away, and again when any grant ends, by expiry or grant revoke, naming the plan the account returns to. A closed account gets no ended email. Moving the end date drops a queued ending email that no longer applies. Failed sends are retried with backoff and abandoned after five attempts; purser_operator_grant_notice_repeatedly_failed_items counts the ones still failing and PurserOperatorGrantNoticeStuck fires on it (see Grant emails). Requeue an abandoned one with frameworks admin billing grant notice --tenant-id <uuid> --reason <reason>. Without a billing email nothing is sent, so tell the customer yourself. Customer-facing terms are in Billing.

Deactivation is reversible:

Terminal window
frameworks admin users deactivate --email [email protected] --reason "Evaluation paused"
frameworks admin users activate --email [email protected] --reason "Evaluation resumed"

Deactivation ends the user’s interactive sessions, API-token WebSockets and stream-key publishing. Tenant-owned streams and VODs stay playable. Activation requires a fresh interactive login; revoked sessions do not return. Billing restrictions still apply to API work, ingest and playback.

Connected cells receive the stream-key revocation and an active-ingest stop through Commodore’s durable refresh queue, and enforce it even while Commodore is unavailable. Unreachable cells are retried and raise CommodoreAccountIngestRevocationStuck; see Session stops. A reactivation supersedes queued stops, but a stop already in flight can end a newly connected publisher once; reconnect after reactivation if that happens.

Bridge closes API-token WebSockets on the revocation event. A Bridge replica that missed the event rechecks ValidateAPIToken every minute, which bounds the remaining socket access.

Closure is permanent:

Terminal window
frameworks admin tenants deactivate <UUID> --yes --tenant-name "Exact Tenant Name" \
--reason "Account closed"

The tenant name must match Quartermaster’s. Omit --yes and --tenant-name to type the name interactively; --tenant-name requires --yes. Closure:

  • closes every user and queues a durable stop for their active ingest;
  • publishes tenant-inactive authority, without authorizing data deletion;
  • blocks new active users locally, even while Quartermaster is unavailable;
  • ends the tenant in Quartermaster independently of the session stops; failures retry and raise CommodoreTenantAccountClosureStuck;
  • stops billing, as described in Account closure billing.

Remove closed users from bootstrap declarations before the next release apply; otherwise validation refuses their reactivation. Read the private deactivation and closure reasons, and the account’s closure and session-stop state, with:

Terminal window
frameworks admin tenants get <UUID>
frameworks admin tenants history <UUID>

An operator-owned test account is declared in the cluster’s GitOps bootstrap overlay (clusters/<cluster>/bootstrap.yaml): a Quartermaster tenant, its Purser billing with an operator_grant, and its users under accounts. Passwords come from SOPS secret references.

quartermaster:
tenants:
- alias: frameworks-qa
name: FrameWorks QA
accounts:
- kind: customer
tenant:
ref: quartermaster.tenants[frameworks-qa]
users:
role: owner
first_name: FrameWorks
last_name: QA
password_ref:
sops: ../../secrets/staging.env
key: QA_ACCOUNT_PASSWORD
wallet: "0x0000000000000000000000000000000000000001" # optional, for wallet sign-in
purser:
customer_billing:
- tenant:
ref: quartermaster.tenants[frameworks-qa]
model: postpaid
tier: enterprise
cluster_access: derived
operator_grant:
base_fee: "0"
waive_usage: true
reason: Internal QA account
# until: 2026-12-31 # optional; omit for an account that lasts until revoked
  • Add the password to the SOPS file with gitops/scripts/sops-env.sh set <file> <KEY> <VALUE>.
  • wallet is an optional Ethereum address (0x and 40 hex characters) linked to the user for wallet sign-in, so automation can sign in as the account with the matching key instead of a password. The address is public; keep the private key in your secrets store. An address declared for two users fails validation. An address already linked to a different user is never moved: bootstrap reports that user’s wallet as deferred and exits non-zero, so unlink the wallet from the old user first, signed in as that user. Removing the field leaves an existing link in place.
  • An account entry carries no billing of its own; validation refuses one. Billing is declared once per tenant in purser.customer_billing.
  • operator_grant takes the same fields as grant set: base_fee, waive_usage, collection (provider or invoice), until and a required reason.

frameworks cluster release apply runs the Purser bootstrap and then commodore bootstrap --accounts-only, so a declared account is created or updated on the next release apply. It never resets an existing password. frameworks cluster control-plane reconcile applies a changed declaration between releases.

A live declaration owns the grant and logs any CLI arrangement it replaces. Reapplying an identical grant changes nothing. An expired declaration is inert and leaves later CLI grants alone. Remove a live declaration before a permanent CLI revoke, or the next release apply restores it.

Release apply first tries to finish a pending grant expiry before it applies a live declaration; --dry-run leaves pending expiries untouched and reports those tenants as deferred. When a tenant is deferred, healthy tenants commit, the bootstrap exits non-zero and release apply stops before the accounts step. Fix the reported failure and rerun release apply. When expiry restored a different billing model, first run frameworks admin billing set-tier with the declared tier, --billing-model and a reason, so the normal transition handles balances and credits. An obsolete fallback can be recovered with grant revoke --tier <active-tier> or an explicit set-tier; both close the expired grant at its deadline.

The sections below explain what Purser and Commodore retry on their own and what to run when an alert fires. Alerting lists each alert with the command that names the tenant.

A failed expiry reconciliation is recorded with a five-minute backoff and raises PurserOperatorGrantExpiryStuck; later expiries continue. grant show and grant list --include-expired show its last error and failed-attempt count. Correct the underlying billing or pricing error; the retry runs automatically.

A grant with no recorded assigned tier has nothing for the sweep to restore. It stops applying at its deadline without denying the tenant, and collection readiness decides admission, including while its closing boundary is refused.

Cancelling a subscription keeps its grant, so recoverable provider states such as Stripe unpaid do not lose waived usage. Revoking or expiring a grant on a cancelled subscription archives it at the cleanup time without changing the tier or issuing a closing document. Revoke it before starting a new provider checkout. A renewal of the same established Stripe subscription may restore status and dates and keep the grant; a new checkout or activation must end it first.

A checkout reservation has a deadline and belongs to one provider attempt. A failure before the checkout is created, or a definite provider rejection, releases the reservation at once. An ambiguous result stays reserved until the durable provider inbox reconciles it after the deadline. A completed checkout keeps its reservation while payment settles, even past the deadline. Historical receipts already installed as the tenant’s subscription do not block grants; other unresolved receipts are queued for recovery before they release their reservation.

Terminal window
frameworks admin billing recovery list --tenant-id <uuid>
frameworks admin billing recovery checkout --tenant-id <uuid> --reservation-id <uuid> \
--reason "Abandoned evaluation checkout"
frameworks admin billing recovery list --tenant-id <uuid> --history

Recovery shows the provider, state and checkout amount before it asks for confirmation; --yes confirms without a prompt. It reports whether the checkout expired, the subscription activated, cancellation and refund reconciliation finished, or work remains pending. Every request keeps its operator, reason and outcome in history and emits audit events; a later request does not overwrite it.

An on-time completed purchase becomes its subscription when settlement succeeds, and a failed settlement releases its reservation. An abandoned or unbound attempt can be recovered before its deadline. Failed recovery stays durable. For cluster purchases only the initial unactivated purchase is returned; its operator credit is voided without reversing credit for delivered recurring service.

A timed-out create is retried with its original parameters and idempotency key, for up to 23 hours on Stripe and 45 minutes on Mollie, and only with the credential that made the request. Outside that window recovery locates the existing provider objects instead of creating another purchase. A prepared attempt that never reached the provider can be closed while the provider is down. When the provider has not supplied an amount, the preview says it is unknown.

An accepted refund request can still be waiting for bank settlement. Refund work stays in recovery list until Stripe or Mollie confirms the returned amount. Settlement polling reads provider receipts. A confirmed failed Stripe refund re-enters the same capped compensation with a failure-bound idempotency key; pending refunds keep waiting without another request. A failed bank return raises PurserProviderWebhookInboxStuck: inspect the exact provider payment and repair the return in that provider’s console.

Historical Mollie first payments are linked to local activation records during recovery after the provider mandate is verified. When recovery cannot prove delivery from local activation or an attached invoice, it records ambiguous delivery, with the exact subscription and payment in its diagnostic. Check the receipt and service history in the provider console. A platform operator can then attest delivered service without refunding it:

Terminal window
frameworks admin billing recovery checkout --tenant-id <uuid> --reservation-id <uuid> \
--retain-delivered --reason "Verified delivered service from historical records"

The attestation previews first and requires confirmation. It records the operator, reason and delivered outcome, keeps the payment, and creates no subscription or access. It needs the recorded ambiguous-delivery state, and refuses current checkouts, receipts already retained and any payment already owed a refund or returned by the provider. It shares the compensation lock with the worker, so a concurrent refund cannot race it.

Normal settlement waits back off from one minute to six hours and keep their reason visible; a wait past fourteen days raises PurserProviderWebhookInboxStuck. A provider activation waiting for complete usage metering keeps the first webhook receipt as its billing boundary, and an open metering anomaly holds the activation until it is resolved.

Terminal window
frameworks admin billing recovery upgrade --tenant-id <uuid> --upgrade-id <uuid> \
--reason "Reconcile purchase"

The command previews a pending tier upgrade before it asks for confirmation. It cancels a request only after confirming the provider did not apply it; otherwise it reconciles the accepted purchase, and it never starts another purchase. A Stripe purchase the provider already applied still waits for complete usage metering before its local billing boundary can close. --waive-metering on such a purchase closes the old phase on the usage recorded so far, and is audited with your identity and reason. Get the purchase UUID and its retry errors from recovery list.

A downgrade the provider confirmed is held when its period’s closing invoice is a draft or in manual review, or the subscription refuses the tier change. The customer’s tier changes are refused while it is held, and PurserTierDowngradeHeld fires. recovery list names each held downgrade with its target tier, effective time and invoice, and the downgrade command shows what holds it:

Terminal window
frameworks admin billing recovery list
frameworks admin billing recovery downgrade --tenant-id <uuid> --reason "Invoice reviewed"

Confirming closes the tenant’s billing period again and applies the downgrade when nothing still holds it. A manual_review invoice waits for the cluster pricing it names; configure it with admin billing set-cluster-pricing, then run the command again.

A cancelled tenant moves to Free when its paid term ends, and a failed payment moves it to Free after its grace period. An outstanding grant holds that move until the grant ends. Setting, renewing or ending a grant keeps the cancellation schedule, also when the paid term has already ended, and never reactivates the cancelled paid subscription.

recovery list shows a scheduled fallback with its move date, state and last error. An explicit set-tier cancels the fallback before provider cancellation starts, restores invoicing, and detaches only native subscriptions proven to have ended after their paid term. Tier assignment and grant changes are refused while an ended subscription still has paid time left. Explicit assignment finalizes the ended provider-managed periods before detaching their identities, so each monthly allowance stays separate and the base fee already collected is excluded. A live native subscription or a stop already in flight must finish reconciliation first; the command returns a precondition error.

Fallback email delivery stops after five failures. The notice_abandoned row keeps the reason and delivery error and no longer counts toward PurserFreeFallbackStuck. Correct billing_email, then requeue the grace or completed-move notice:

Terminal window
frameworks admin billing recovery notice --tenant-id <uuid> --reason "Billing email repaired"

The command previews the recipient and requires confirmation. The billing audit records the operator and reason. It does not change the tier, restore collection or refund anything, and an email failure never blocks the billing move.

A suspended tenant’s session-stop request is queued with its suspension. Partial cell failures and Commodore outages retry durably. Resumption is checked under the subscription lock before each retry, so a completed resumption clears the queued stop without ending a new stream.

Purser consumes the closure event and records the billing cutoff. It cancels established Stripe and Mollie subscriptions without refunding completed service and finalizes the open billing phase at the cutoff; no later recurring invoice starts. Provider outages and incomplete metering keep the finalization pending in recovery list. An outstanding grant first closes at the cutoff through the normal expiry worker. Late paid or settling cluster callbacks queue provider cancellation, also after final billing, and cannot restore access or finalize another billing document.

Open cluster checkouts are expired so they cannot accept another purchase. Activated paid cluster subscriptions are cancelled without refunding or crediting their unused paid time. A paid tenant or cluster checkout that never activated is refunded only for its checkout payment or first invoice; recurring service payments are never part of checkout compensation. Normal cancellation stops renewal at the paid-through date, while permanent closure ends access immediately. Checkout recovery is a separate compensation action, not a refund policy for ordinary cancellation.

User deactivation and tenant closure stop active ingest on every cell that recorded the account’s streams. A per-user stop never falls back to stopping the whole tenant, and new publishes are refused independently of the stop. A cell that cannot be reached is retried, including backoff, and CommodoreAccountIngestRevocationStuck fires; frameworks admin tenants get <UUID> lists each pending stop with its cells and last error. Restore the cell and the stop completes. A Foghorn that returns Unimplemented for per-user stops keeps them queued until it is upgraded.

For a cell that was removed for good, record its retirement so the stops owed to it settle:

Terminal window
frameworks admin clusters retire <cluster-id> --reason "Cell decommissioned"

Commodore refuses while any registered Foghorn of the cell still answers. A stop still owed to another unreachable cell keeps waiting for that cell, and a retired cell that comes back still receives its stops. frameworks admin clusters unretire <cluster-id> --reason <reason> removes a retirement made by mistake; stops that already settled are not reopened.