From 9130c0669206df15150932fe64e6f597bb83a45a Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 2 Jun 2026 02:09:43 +0000 Subject: [PATCH 1/4] docs: add self-serve billing and access-gating guide --- billing.mdx | 105 ++++++++++++++++++++++++++++++++ docs.json | 1 + getting-started/first-steps.mdx | 8 +++ settings.mdx | 2 +- 4 files changed, 115 insertions(+), 1 deletion(-) create mode 100644 billing.mdx diff --git a/billing.mdx b/billing.mdx new file mode 100644 index 0000000..e871de4 --- /dev/null +++ b/billing.mdx @@ -0,0 +1,105 @@ +--- +title: "Billing & Plans" +description: "Pick or change your plan, manage your subscription through Stripe, and understand what happens when billing lapses." +--- + +UMS includes a self-serve billing area where organisation administrators can choose a plan, change plans, and manage payment details without contacting Utilified. Billing lives under **Settings → Billing**. + +## When to use this + +Use the billing area when you need to: + +- Subscribe to a plan for the first time after signing up. +- Change to a different plan as your usage grows. +- Update your payment method or download invoices via Stripe. +- Restore access after a failed payment. + +## Who can manage billing + +Only users with the **Manage billing** permission (`can_manage_billing`) can start a checkout, change plans, or open the Stripe Billing Portal. This typically maps to organisation administrators. + +Users without this permission can still see the current plan and usage on the Billing page, but the **Subscribe**, **Manage subscription**, and Stripe Billing Portal actions are hidden. If billing lapses, non-admins are asked to contact an administrator. + +## Choosing or changing a plan + +The **Choose or change your plan** section on the Billing page lists every available plan side-by-side. Each plan card shows: + +- Plan name, monthly base price, and a short description +- The features included in the plan +- Any usage limits (for example, connections or users) +- A **Subscribe** button — or a **Current plan** badge if your organisation is already on that plan + + + + Navigate to **Settings → Billing**. + + + Scroll down to the **Choose or change your plan** section to compare available plans. + + + Click **Subscribe** on the plan you want. UMS opens a secure Stripe Checkout session in the same window. + + + Enter your payment details in Stripe Checkout. When the payment succeeds you are returned to UMS and your new plan is active immediately. + + + + + Changing plans uses the same flow as subscribing for the first time. Stripe prorates the change automatically. + + +## Managing your subscription + +Once your organisation has an active Stripe subscription, a **Manage subscription** button appears at the top of the Billing page. This opens the Stripe Billing Portal in a new tab, where you can: + +- Update your payment method +- Download invoices and receipts +- Change billing address and tax details +- Cancel the subscription + +If your organisation is billed by Utilified directly (no Stripe subscription), the page instead shows a note prompting you to contact Utilified for changes. + +## What happens when billing lapses + +UMS derives a billing **access state** from Stripe's subscription status. This drives the in-app behaviour you see when payments fail or a subscription is cancelled. + +| Access state | Meaning | What you see | +| ------------ | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | +| `exempt` | No Stripe subscription — billed by Utilified directly | No banner. Billing actions show a contact-Utilified message. | +| `active` | Subscription active or trialing | Full access. No banner. | +| `grace` | Stripe is retrying a failed payment (past due) | Full access, plus a dismissible warning banner with an **Update billing** shortcut. | +| `blocked` | Subscription has lapsed | A non-dismissable **Billing Locked** screen replaces the app until billing is resolved. | + +### Grace-period banner + +When a payment fails but Stripe is still retrying, UMS shows a warning banner at the top of every page: + +> We couldn't process your latest payment. Update your billing details to avoid interruption. + +The banner has an **Update billing** button that links straight to Settings → Billing. You can dismiss the banner for the rest of the tab session, but it returns on the next reload until the payment is resolved. + +### Billing Locked screen + +If retries are exhausted and the subscription lapses, UMS replaces the main app with a full-screen lock that cannot be dismissed. + +- **Billing managers** see two actions: **Manage billing** (opens the Stripe Billing Portal to pay the overdue invoice or update the payment method) and **Choose a plan** (jumps to the plan picker in Settings → Billing). +- **Other users** see a message asking them to contact their organisation's administrator. + +Both views also offer a **Sign out** action. + + + **Settings and onboarding stay reachable while locked.** Even when your organisation is in the `blocked` state, billing managers can still navigate to **Settings** and **Onboarding** so they can resolve payment. All other routes redirect to the Billing Locked screen until access is restored. + + +## Billing during onboarding + +Plan selection is **optional** during sign-up. On the **Plan** step of onboarding you can either: + +- Pick a plan and complete Stripe Checkout up front, or +- Click **Skip for now — set up billing later** to continue onboarding without a subscription. + +If you skip, you can subscribe at any time from **Settings → Billing**. Your organisation will keep working until the billing gate kicks in — once your trial or grace period ends without an active subscription, the Billing Locked screen prompts an administrator to choose a plan. + + + Skipping is useful when you want to invite your team and start configuring accounts before deciding on a plan. Just remember that a billing manager will need to subscribe before the grace period ends. + diff --git a/docs.json b/docs.json index c20e135..da01927 100644 --- a/docs.json +++ b/docs.json @@ -111,6 +111,7 @@ "settings/personal", "settings/organisation", "settings/white-label", + "billing", "imports", "notifications" ] diff --git a/getting-started/first-steps.mdx b/getting-started/first-steps.mdx index c529f5f..a030fdc 100644 --- a/getting-started/first-steps.mdx +++ b/getting-started/first-steps.mdx @@ -9,6 +9,10 @@ This guide walks you through setting up your organisation in UMS **by hand**, on Setting up a whole portfolio? The faster path is the [guided onboarding wizard](/getting-started/getting-set-up) — upload documents for AI to read, or load everything from a single file, then review and create it all at once. Come back here when you want to add records manually. + + Plan selection is **optional** during sign-up. You can skip the **Plan** step and finish onboarding without a subscription — just click **Skip for now — set up billing later** on the plan picker. A billing manager can subscribe at any time from [Settings → Billing](/billing); the billing gate will prompt you once your trial or grace period ends. + + ## Step 1: Create your accounts Accounts are the top-level containers — typically one per customer or business entity. @@ -153,3 +157,7 @@ For large portfolios, use the **Bulk Upload Wizard** to import accounts, sites, ### Invite your team Add colleagues to your organisation and control what each of them can access. See [Setting Up a User](/guides/setting-up-a-user). + +### Subscribe to a plan + +If you skipped plan selection during onboarding, choose a plan from **Settings → Billing** before your grace period ends. See [Billing & Plans](/billing). diff --git a/settings.mdx b/settings.mdx index ed2fe45..53a85b1 100644 --- a/settings.mdx +++ b/settings.mdx @@ -37,7 +37,7 @@ Settings that affect your whole organisation. | **General** | Organisation profile, logo, and timezone | [Organisation Settings](/settings/organisation) | | **Users** | Invite users, assign roles, manage access | [Setting Up a User](/guides/setting-up-a-user) | | **Auto-Pilot** | AI automation for the invoice pipeline | [Organisation Settings](/settings/organisation) | -| **Billing** | Plan, usage, and payments | [Organisation Settings](/settings/organisation) | +| **Billing** | Plan, usage, and payments | [Billing & Plans](/billing) | | **Portal & Domain** | White-label customer portal and custom domain | [Portal & Single Sign-On](/settings/white-label) | | **Single Sign-On** | SSO against your identity provider | [Portal & Single Sign-On](/settings/white-label) | From f7995061f00f5797ed88be08cb64a88783d67b2a Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 2 Jun 2026 02:11:15 +0000 Subject: [PATCH 2/4] docs: tighten billing page description and fix dismissible spelling --- billing.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/billing.mdx b/billing.mdx index e871de4..a72f525 100644 --- a/billing.mdx +++ b/billing.mdx @@ -1,6 +1,6 @@ --- title: "Billing & Plans" -description: "Pick or change your plan, manage your subscription through Stripe, and understand what happens when billing lapses." +description: "Choose or change your UMS plan, manage your subscription through Stripe Checkout and the Billing Portal, and recover from a lapsed subscription." --- UMS includes a self-serve billing area where organisation administrators can choose a plan, change plans, and manage payment details without contacting Utilified. Billing lives under **Settings → Billing**. @@ -68,7 +68,7 @@ UMS derives a billing **access state** from Stripe's subscription status. This d | `exempt` | No Stripe subscription — billed by Utilified directly | No banner. Billing actions show a contact-Utilified message. | | `active` | Subscription active or trialing | Full access. No banner. | | `grace` | Stripe is retrying a failed payment (past due) | Full access, plus a dismissible warning banner with an **Update billing** shortcut. | -| `blocked` | Subscription has lapsed | A non-dismissable **Billing Locked** screen replaces the app until billing is resolved. | +| `blocked` | Subscription has lapsed | A non-dismissible **Billing Locked** screen replaces the app until billing is resolved. | ### Grace-period banner From c163703689d7a4a372a51c22ea48bbac40ef2044 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Thu, 4 Jun 2026 02:14:09 +0000 Subject: [PATCH 3/4] docs: document 12-month commitment gating and request-only plans --- billing.mdx | 28 +++++++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/billing.mdx b/billing.mdx index a72f525..d71892f 100644 --- a/billing.mdx +++ b/billing.mdx @@ -13,6 +13,7 @@ Use the billing area when you need to: - Change to a different plan as your usage grows. - Update your payment method or download invoices via Stripe. - Restore access after a failed payment. +- Request access to an Enterprise (request-only) plan. ## Who can manage billing @@ -48,6 +49,30 @@ The **Choose or change your plan** section on the Billing page lists every avail Changing plans uses the same flow as subscribing for the first time. Stripe prorates the change automatically. +### Enterprise and other request-only plans + +Some plans — typically **Enterprise** and other usage-based plans — are **request-only**: they don't have a fixed monthly price and can't be subscribed to directly from Stripe Checkout. Their plan card shows: + +- A custom pricing summary instead of a monthly figure (for example, *"from $400/mo + 50¢/meter"*). +- A **Request access** button instead of **Subscribe**. + +Clicking **Request access** opens a short form where you can confirm your name and email and add an optional message about your needs (for example, how many meters you manage). Submitting the form creates a lead and notifies the Utilified team, who will follow up to set up the plan for you. + + + The form pre-fills your name and email from your UMS profile. Edit them if a different contact should hear back about the enquiry. + + +## 12-month commitment + +Paid plans run on a **12-month commitment**. While the commitment is active: + +- An info banner on the Billing page shows the date your term ends — for example, *"You're on a 12-month commitment until 1 Dec 2026."* +- **Upgrades** to a higher-priced plan stay available at any time. Choosing an upgrade resets the 12-month clock from the new start date. +- **Downgrades** and **cancellation** are locked until the term ends. Plan cards priced below your current plan show a disabled button with a *"Committed until …"* helper instead of **Subscribe**. +- Request-only plans (such as Enterprise) are not affected by commitment gating — you can submit an enquiry at any time. + +Once the commitment end date passes, all plan-change options become available again from the same plan picker. + ## Managing your subscription Once your organisation has an active Stripe subscription, a **Manage subscription** button appears at the top of the Billing page. This opens the Stripe Billing Portal in a new tab, where you can: @@ -55,7 +80,7 @@ Once your organisation has an active Stripe subscription, a **Manage subscriptio - Update your payment method - Download invoices and receipts - Change billing address and tax details -- Cancel the subscription +- Cancel the subscription (after the commitment term ends) If your organisation is billed by Utilified directly (no Stripe subscription), the page instead shows a note prompting you to contact Utilified for changes. @@ -96,6 +121,7 @@ Both views also offer a **Sign out** action. Plan selection is **optional** during sign-up. On the **Plan** step of onboarding you can either: - Pick a plan and complete Stripe Checkout up front, or +- Request access to a request-only plan (such as Enterprise) using the same contact form available in Settings → Billing, or - Click **Skip for now — set up billing later** to continue onboarding without a subscription. If you skip, you can subscribe at any time from **Settings → Billing**. Your organisation will keep working until the billing gate kicks in — once your trial or grace period ends without an active subscription, the Billing Locked screen prompts an administrator to choose a plan. From 7b89eddf8faeb49e0291fd7600a4eb6ed9b7b67c Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 9 Jun 2026 02:10:05 +0000 Subject: [PATCH 4/4] docs: update Billing page for redesigned summary, usage meters, manual billing mode --- billing.mdx | 50 +++++++++++++++++++++++++++++++++----------------- 1 file changed, 33 insertions(+), 17 deletions(-) diff --git a/billing.mdx b/billing.mdx index d71892f..5038c22 100644 --- a/billing.mdx +++ b/billing.mdx @@ -11,6 +11,7 @@ Use the billing area when you need to: - Subscribe to a plan for the first time after signing up. - Change to a different plan as your usage grows. +- Check current usage against your plan limits. - Update your payment method or download invoices via Stripe. - Restore access after a failed payment. - Request access to an Enterprise (request-only) plan. @@ -19,34 +20,49 @@ Use the billing area when you need to: Only users with the **Manage billing** permission (`can_manage_billing`) can start a checkout, change plans, or open the Stripe Billing Portal. This typically maps to organisation administrators. -Users without this permission can still see the current plan and usage on the Billing page, but the **Subscribe**, **Manage subscription**, and Stripe Billing Portal actions are hidden. If billing lapses, non-admins are asked to contact an administrator. +Users without this permission can still see the current plan and usage on the Billing page, but the **Subscribe**, **Manage billing**, and **Change plan** actions are hidden. If billing lapses, non-admins are asked to contact an administrator. -## Choosing or changing a plan +## The Billing page + +The Billing tab gives you a single-panel summary of your subscription: + +- **Current plan** — Plan name with a status dot (Active, Trial, or Cancelled), the monthly price, and the next renewal date. +- **Manage billing** — Opens the Stripe Billing Portal in a new tab (Stripe-billed orgs only). +- **Usage** — A three-up row of usage meters: **Connections**, **Users**, and **Invoices this month**. Each meter shows your current count against the plan limit (or *Unlimited*) and turns amber as you approach the limit. +- **Change plan** — A button that reveals the plan picker on demand. Use it when you want to compare or switch plans. +- **Commitment notice** — When your organisation is inside its 12-month term, a short line under the price summarises when downgrades and cancellation become available. + +### Billing modes -The **Choose or change your plan** section on the Billing page lists every available plan side-by-side. Each plan card shows: +How your organisation pays for UMS determines which controls appear on the page: + +| Billing mode | What you see | +| ------------ | ------------------------------------------------------------------------------------------------------------------------- | +| `stripe` | Self-serve **Manage billing** and **Change plan** controls. | +| `manual` | A *"Your subscription is billed directly by Utilified"* notice. Stripe controls and the plan picker are hidden — contact Utilified to make changes. | + +## Choosing or changing a plan -- Plan name, monthly base price, and a short description -- The features included in the plan -- Any usage limits (for example, connections or users) -- A **Subscribe** button — or a **Current plan** badge if your organisation is already on that plan +Click **Change plan** on the Billing page to reveal the plan picker. Each plan card shows the plan name, monthly base price, a short description, included features, usage limits, and a **Subscribe** button — or a **Current plan** badge if your organisation is already on that plan. Navigate to **Settings → Billing**. - - Scroll down to the **Choose or change your plan** section to compare available plans. + + Click **Change plan** to reveal the list of available plans below the summary. - - Click **Subscribe** on the plan you want. UMS opens a secure Stripe Checkout session in the same window. + + Click **Subscribe** on the plan you want. - - Enter your payment details in Stripe Checkout. When the payment succeeds you are returned to UMS and your new plan is active immediately. + + - **New subscribers** — UMS opens a secure Stripe Checkout session. Enter your payment details; when payment succeeds Stripe returns you to **Settings → Billing** with a confirmation, and your new plan is active. + - **Existing subscribers** — UMS changes the plan in place on your current Stripe subscription. There's no redirect: you see a success message and the page refreshes to show the new plan immediately. - Changing plans uses the same flow as subscribing for the first time. Stripe prorates the change automatically. + Stripe prorates plan changes automatically — you're only charged the difference for the rest of the current billing period. ### Enterprise and other request-only plans @@ -66,7 +82,7 @@ Clicking **Request access** opens a short form where you can confirm your name a Paid plans run on a **12-month commitment**. While the commitment is active: -- An info banner on the Billing page shows the date your term ends — for example, *"You're on a 12-month commitment until 1 Dec 2026."* +- A note under the current plan shows the date your term ends — for example, *"On a 12-month commitment until 1 Dec 2026."* - **Upgrades** to a higher-priced plan stay available at any time. Choosing an upgrade resets the 12-month clock from the new start date. - **Downgrades** and **cancellation** are locked until the term ends. Plan cards priced below your current plan show a disabled button with a *"Committed until …"* helper instead of **Subscribe**. - Request-only plans (such as Enterprise) are not affected by commitment gating — you can submit an enquiry at any time. @@ -75,14 +91,14 @@ Once the commitment end date passes, all plan-change options become available ag ## Managing your subscription -Once your organisation has an active Stripe subscription, a **Manage subscription** button appears at the top of the Billing page. This opens the Stripe Billing Portal in a new tab, where you can: +Once your organisation has an active Stripe subscription, a **Manage billing** button appears on the Billing page. This opens the Stripe Billing Portal in a new tab, where you can: - Update your payment method - Download invoices and receipts - Change billing address and tax details - Cancel the subscription (after the commitment term ends) -If your organisation is billed by Utilified directly (no Stripe subscription), the page instead shows a note prompting you to contact Utilified for changes. +If your organisation is billed by Utilified directly (manual billing mode), the page shows a *"billed by Utilified"* notice instead — contact Utilified to make any changes. ## What happens when billing lapses