Billing

Last updated: 2026-03-26 Owner: Product Writer Audience: owner, tenant admin, billing_admin

Purpose

Explain how to use the Billing module to control the tenant plan, subscription status, renewal, checkout flow and synchronisation with the payment provider.

Prerequisites

• an authorised tenant commercial role
• the correct tenant selected

Roles currently allowed by runtime:

• owner
• admin
• billing_admin

What the module shows

The module exposes at least:

• active plan
• subscription status
• last known payment
• next expected renewal
• business-first billing profile
• available plan catalog
• recent plan-change history
• sync, cancel or resume actions when allowed
• provider technical details only in a secondary area

Commercial states you may encounter:

• Trial
• Checkout pending
• Active
• Past due
• Suspended
• Canceled
• Expired

Operational steps

1. Open Billing from the workspace.
2. Check the active plan, subscription status, last payment and next expected renewal.
3. Review the billing profile for the tenant commercial picture.
4. Start checkout when you need to change plan, only if the role can really administer the subscription.
5. Use sync, cancel or resume only when you need to realign tenant state with the payment provider.
6. If Resume checkout appears, use it before creating a new checkout.
7. If the tenant is already active, the catalog explains whether you are performing an upgrade, downgrade, or simple plan update.
8. For already active tenants, the new recurring amount applies from the next eligible renewal, without opening a new checkout.
9. If Realign with provider appears, use it when the tenant state requires an external reconciliation check.
10. Open provider technical details only for support or operational checks.
11. After checkout, wait for the webhook/provider update for the final status confirmation.
12. If the status is Past due, also check the grace-period deadline before the tenant is suspended.
13. Use Plan change history to review the most recent commercial changes already registered for the tenant.
14. Also read the event origin to understand whether the change came from the tenant, the platform control plane, or the provider.

Expected result

The tenant keeps commercial plan, subscription status and renewals aligned without exposing provider technical references as primary page content.

Common errors

• Returned from checkout but status is not updated yet
• cause: the application redirect arrived before the provider webhook
• solution: wait for automatic synchronisation or use sync if the operating process allows it

• An open payment already exists
• cause: a previous checkout is still open
• solution: use Resume checkout to reopen the existing payment instead of creating a new one

• Tenant state does not look aligned with the provider
• cause: the provider may have advanced before the application state was reconciled
• solution: use Realign with provider to force a runtime check

• Action not available
• cause: the role can view billing but cannot administer the subscription
• solution: involve an authorised owner, admin or billing_admin

• Access denied for an operational tenant role
• cause: hr_admin, manager and user are outside the subscription/payment perimeter
• solution: involve owner, admin or billing_admin

• Provider data looks inconsistent
• cause: temporary drift between tenant state and the external provider
• solution: run sync again and review the provider technical details only when support needs them

• Workspace reduced after suspension
• cause: the tenant moved to Suspended or Expired
• solution: use Billing for commercial recovery if your role is owner, admin, or billing_admin; the main tenant APIs now follow the same restriction

FAQ

Does changing plan always start a checkout?

Not always. In some cases the system can update the subscription directly without a new checkout.

When do upgrades and downgrades become effective?

For already active tenants, the new recurring amount applies from the next eligible renewal.

Is this billing module the same as platform-wide billing?

No. This module belongs to the current tenant, not the SaaS platform's multi-tenant governance layer.

How does NBN read the global plan-change timeline?

Inside Platform Billing, NBN uses dedicated filters for tenant status, tenant, event, direction, and time window, so the recent global timeline stays aligned with the billing portfolio currently under review.

Can NBN export the filtered global timeline?

Yes. Platform Billing exposes an Export timeline CSV action that uses the same active filters as the current view, so the exported file stays aligned with the portfolio currently under review.

What does event origin mean in the timeline?

The timeline uses readable labels such as Tenant user, Platform operator, Provider webhook, or System, so both NBN and the tenant can immediately understand who originated the change without reading a technical code.

When the system knows the human actor, the timeline shows the actual name or operational email instead of a generic label.

When role and scope are verifiable, the timeline also shows the actor governance context, for example Tenant owner, Tenant billing admin, or Platform super admin.

Are Mollie references always visible?

No. They remain available only as secondary technical details, not as primary page content.

What does `Checkout pending` mean?

It means checkout has been started or the user has returned from checkout, but the final confirmation still depends on the webhook/provider update.

What does `Past due` mean?

It means the tenant is not suspended yet, but a renewal or collection requires commercial attention.

What happens during the grace period?

The tenant can remain operational for a limited window. If the payment is not recovered before the grace deadline, the commercial status can move to Suspended.