Admin User Guide

Overview

The YSS Client Portal is a web platform for managing dental clinics, their subscriptions, users, promotions, and analytics. This guide covers the Admin section of the portal — the screens and actions available to Super Admins and Group Admins.

After signing in, you are automatically redirected to the area relevant to your role:

Super Admin lands on the Clinics list (/clinics).
Group Admin lands on their group’s Analytics dashboard (/groups/:id/analytics).
Clinic Admin and Clinic Staff are covered in the separate Clinic Guide.

Roles & Access

Role	What they manage	Default landing page
Super Admin	Full platform — all clinics, groups, users, billing catalog, and global module catalog	`/clinics`
Group Admin	All clinics and users within their assigned group	`/groups/:id/analytics`
Clinic Admin	Their own clinic — covered in the Clinic Guide	`/analytics`
Clinic Staff	Day-to-day clinic operations — covered in the Clinic Guide	`/my-clinic`

Role restrictions are noted throughout this guide where they apply to specific actions.

Clinics

Viewing the Clinic List

The Clinics list (/clinics) shows all clinics on the platform. Each row displays:

ID — a shortened identifier (last six characters of the full ID).
Clinic Name — click to open the clinic’s detail page.
Region — the geographic region entered for the clinic.
Last Active — date and time the clinic was last active.
Conversion Rate (%) — the percentage of visitors who requested an appointment.
Status — ACTIVE or INACTIVE.

Filtering and sorting the list

Use the controls above the table to narrow results:

Region — filter by a specific geographic region, or choose “All”.
Status — filter by Active, Inactive, or show all.
Search — type a clinic name or email address to search in real time.
Sort by — choose a sort field and direction from the dropdown (options include name A–Z, name Z–A, last active newest/oldest, and conversion rate).

The list is paginated. The footer shows the current range (e.g. “Showing 1 to 9 of 42 Results”) and previous/next page controls.

Adding a clinic

Click Add Clinic in the top-right corner. The Add Clinic drawer opens — see Editing a Clinic for the full field reference. Super Admins can create clinics scoped to any group or as independent clinics. Group Admins creating clinics from the Clinics list will have their group pre-selected.

Clinic Details

Click any clinic row to open its detail page (/clinics/:id). The page is divided into several sections:

Header card

Displays the clinic’s full name, internal ID, email address, phone number, contact address, and billing address. Two shareable links are shown with a copy button:

Promote Link — the patient-facing URL that includes the booking flow. Share this with patients or use it in marketing.
Simulate Link — an internal URL for clinic staff to preview the visualizer without creating a real booking.

Active Users

A table listing all users attached to this clinic (name, role, email, status). Each name links through to that user’s detail page. Click Add User to create a new user scoped to this clinic.

Subscription & Payment

Shows two side-by-side cards:

Current Plan — plan name, status, billing cycle, and cost per period.
Payment Method — the Stripe card on file (masked card number, expiry date, billing email).

If an active subscription exists, a Try-Ons this month progress bar also appears, showing how many try-ons have been used versus the monthly limit. The bar turns amber when usage reaches 80 % and red when fully consumed.

Use the buttons in this section header to:

Manage Modules — toggle which treatment modules are enabled (visible to Super Admin, Group Admin of the parent group, and the clinic’s own Clinic Admin).
Add or Update — open the subscription management drawer.

Promotions

A table of promotions attached to this clinic. Columns: Module, Discount %, Treatment Price, Period (date range or “Ongoing”), and Status (Active/Inactive). Each row has edit and delete icon buttons.

Click Add Promo to create a new promotion. See Promotions for details.

Invoices

A paginated table of the clinic’s internal invoices with columns: Invoice Number, Issue Date, Due Date, and Status (Billed / Paid / Overdue). Paid invoices are highlighted; overdue invoices appear with a plain badge.

After a Stripe Checkout

If a clinic administrator completed (or cancelled) a Stripe Checkout session, a one-line confirmation banner appears at the top of the page:

Green banner — “Subscription updated. It may take a moment for billing details to refresh.”
Blue banner — “Checkout cancelled — no changes were made.”

Click Dismiss to clear the banner. The page automatically strips the ?checkout= query parameter so that refreshing does not re-show the banner.

Editing a Clinic

Click Edit on a Clinic Details page to open the Edit Clinic drawer. The form is divided into sections:

Scope banner (read-only)

Shows whether the clinic belongs to a group (“Group: [name]”) or is independent. This cannot be changed from the edit form.

General Info

Clinic name — required. Only Super Admins can rename a clinic; the field is disabled for all other roles.
Phone — optional telephone number.
Email address — required. Only Super Admins can change the clinic email address.
Region — free-text geographic region (e.g. “Ontario”, “Pacific Northwest”).

Contact Info

Physical address of the clinic: street, city, province/state, country, and postal/zip code.

Billing Info

Billing address for invoices. Check Same as contact info to auto-fill all billing fields from the contact address. When the checkbox is ticked, the billing fields become read-only mirrors of the contact fields.

Subscription Discount (Super Admin only)

A percentage discount (0–100) applied as a Stripe coupon to this clinic’s platform plan subscription. When greater than zero, this overrides the parent group’s discount. Leave at 0 to inherit the group discount (if any).

Click Save to apply changes. A green confirmation message appears briefly before the drawer closes. Click Cancel to discard changes and close without saving.

Managing Modules

From a Clinic Details page, click Manage Modules to open the Manage Modules dialog.

This screen lists every module in the global catalog that is currently enabled platform-wide (the list is sorted to match the patient-facing visualizer’s treatment-selection screen). Each module shows its name and optional description alongside a toggle switch.

Toggle a module on to make it available to this clinic.
Toggle a module off to remove it from this clinic’s offering.

Module access is independent of billing. You can enable or disable modules regardless of whether the clinic has an active subscription. However, the public-facing visualizer will not display any modules to patients until the clinic has an active subscription.

Click Save to apply changes (the button is disabled until at least one module is toggled). Click Cancel to discard.

Access: Super Admin, the Group Admin of the clinic’s parent group, or the clinic’s own Clinic Admin.

Managing Subscriptions

From a Clinic Details page, click Add (for a new subscription) or Update (to change an existing one) to open the Manage Subscription drawer.

Plan summary

Shows the platform plan name and current status badge. Displays the plan price for the selected billing cycle. If a discount applies (set at the clinic or group level), the original catalog price is shown struck-through with the discount percentage noted.

Try-on usage (existing subscriptions only)

A progress bar showing try-ons used this month versus the monthly cap. The cap is the base plan allowance plus any extra packs purchased. The bar turns amber at 80 % and red at 100 %.

Extra Try-On Packs

Packs add a fixed number of extra try-ons per month on top of the plan’s base allowance.

Use the − and + buttons to decrease or increase the number of packs. Changes take effect immediately against the live Stripe subscription for existing subscribers.
On annual subscriptions, a Pack billing cadence toggle appears. Switch between Monthly (default) or Yearly billing for packs. Yearly packs are billed once a year at a discount; the extra try-ons are still credited each month with no rollover.

Billing controls

Billing Cycle — choose Monthly or Yearly. Switching to Yearly shows potential annual savings as a percentage badge.
Cost — displayed as a read-only calculated amount for the selected cycle.
Stripe — for first-time subscriptions, Clinic Admins see a “Subscribe with Stripe” button that opens a Stripe Checkout session in the same browser tab. After payment, Stripe returns the user to the clinic page with a success banner. For existing subscriptions, the button reads “Manage subscription in Stripe”.
Billing Email — the email address Stripe sends receipts to. Editable by Super Admin and Clinic Admin.

Cancelling or resuming a subscription (Clinic Admin only)

At the bottom of the drawer, a Subscription section shows the current renewal status.

Click Cancel subscription and then Confirm cancel at period end to schedule cancellation. The clinic keeps full access until the end of the current billing period. No refund is issued.
If a cancellation is already scheduled, click Resume subscription to reverse it. A cancellation date is shown in the plan summary.

Click Save to persist billing cycle and email changes. Click Cancel to close without saving.

Clinic Invoices

Navigate to /clinics/:id/invoices to view a clinic’s full Stripe invoice history. This page is separate from the invoice summary shown on the Clinic Details page.

The list displays each Stripe invoice as a card with:

Invoice number (with a status badge — Paid, Open, Draft, or Void).
Created date and due date.
Customer email.
Amount paid and amount due (if different).

Use the Show dropdown in the top-right corner to control how many invoices are loaded at once (5, 10, 20, or 50).

Groups

Viewing Groups

The Groups list (/groups) shows all groups on the platform. Each row displays:

ID — shortened identifier.
Group Name — click to open the group’s detail page.
Region — derived from the group’s country field.
Last Active — date and time the group was last active.
Clinics — the number of clinics in this group.
Status — ACTIVE or INACTIVE.

Filtering and sorting

Region — filter by country, or choose “All”.
Status — filter by Active, Inactive, or all.
Search — search by group name.
Sort by — Last Active (newest/oldest) or Name (A–Z / Z–A).

Results are paginated with a record count in the footer.

Adding a group

Click Add Group to open the Add Group drawer. See Editing a Group for the field reference.

Group Details

Click any group row to open its detail page (/groups/:id). The page contains:

Header card

Displays the group name, internal ID, email, phone, contact address, and billing address.

Active Users

A table of users assigned to this group (name, role, email, status). Names link through to individual user detail pages. Click Add User to create a new user scoped to this group.

Promotions

A table of promotions applied at the group level (Module, Discount %, Treatment Price, Period, Status). Group-level promotions apply to all clinics in the group unless overridden at the clinic level. Each row has edit and delete buttons.

Click Add Promo to create a new group promotion. See Promotions for details.

Try-On Usage

When clinics in the group have active subscriptions, a roll-up panel shows:

Total try-ons used across all clinics this month versus the combined monthly limit.
A group-wide progress bar (amber at 80 %, red at 100 %).
A per-clinic breakdown sorted by usage (highest first), each row linking directly to that clinic’s detail page. A clinic’s pack count is noted if packs have been purchased.

This panel is useful for spotting which clinics are at risk of hitting their quota before the reset date shown in the panel header.

Clinics

A paginated table of clinics in this group (ID, Clinic Name, Region, Status). Clinic names link to their detail pages. Click Add Clinic to create a new clinic pre-scoped to this group.

Editing a Group

Click Edit on a Group Details page to open the Edit Group drawer.

General Info

Group name — required. Editable by Super Admin and Group Admin; read-only for other roles.
Phone — optional.
Email address — required. Editable by Super Admin and Group Admin.

Contact Info

Street, city, province/state, country, and postal/zip code.

Billing Info

Separate billing address, or tick Same as contact info to mirror the contact fields. When ticked, billing fields are read-only.

Subscription Discount (Super Admin only)

A group-wide discount percentage (0–100) applied to the platform plan for every clinic in the group. A clinic-level discount overrides this when it is greater than zero.

Click Save to apply. A confirmation message appears briefly before the drawer closes. Click Cancel to discard.

Promotions

Promotions can be created at either the group level (from the Group Details page) or the clinic level (from the Clinic Details page). The same form is used in both cases.

Add / Edit Promotion

Click Add Promo or the edit icon on an existing promotion to open the Promotion drawer.

Fields:

Module — select the treatment module the promotion applies to. Only modules that are currently enabled for the clinic or group are available for selection.
Treatment Original Price — the full (pre-discount) treatment price, used to calculate savings shown to patients.
Discount % — the percentage discount (0–100) to apply. Required.
Timed Promotion — toggle this switch on to restrict the promotion to a specific date range. When on, two date fields appear (From and To). When off, the promotion is ongoing with no expiry date. Turning the toggle off clears any previously entered dates.

Click Add Promotion (create) or Save Changes (edit) to save. Click Cancel to discard.

Deleting a Promotion

Click the delete (bin) icon on any promotion row. The deletion takes effect immediately with no confirmation dialog. This action cannot be undone.

Users

Viewing the User List

The Users list (/users) shows all platform users. Each row on desktop displays:

Name — click to open the user’s detail page.
Role — Super Admin, Group Admin, Administrator (Clinic Admin), or Staff (Clinic Staff).
Email — the user’s sign-in email.
Last Active — date of last sign-in.
Status — ACTIVE or INACTIVE.

On mobile, each user is shown as a compact card with the same information.

Filtering and sorting

Search — search by name or email address.
Role — filter to a specific role using the segmented button bar (All / Super Admin / Group Admin / Administrator / Staff). On mobile, role and sort controls are accessible via icon buttons.
Sort by — Last Active (newest/oldest), Name (A–Z / Z–A), Email (A–Z / Z–A), or Role (A–Z / Z–A).

Results are paginated (5 per page by default) with a record count in the footer.

Adding a user

Click Add User to open the Add User drawer. The new user is automatically scoped to the current user’s organisation (group or clinic, based on the admin’s own profile).

User Details

Click any user row (or a user’s name in a Clinic or Group Details page) to open the User Details page (/users/:id).

The page shows a breadcrumb (“Users — Detail”), the user’s full name as the page title, and a card with:

Avatar / profile photo (if set) or a generic account icon.
Full name and role label.
Organisation — the clinic or group the user belongs to, if any.
Email address.
Phone number.
Password section — see Generating a Temporary Password below.

Editing a User

Click Edit on a User Details page to open the Edit User drawer. Fields available depend on the user’s role and your own permissions, but typically include:

First name and last name.
Email address.
Phone number.
Role.
Clinic or group assignment.

Save changes by submitting the form. The User Details page refreshes automatically after the drawer closes.

Activating / Deactivating a User

The Activate or Deactivate button appears in the header of the User Details page (the label reflects the current state).

Deactivate — opens a confirmation dialog: “Deactivate this user? They will not be able to sign in.” Click Deactivate to confirm or Cancel to abort. A success message appears and the page refreshes.
Activate — opens a confirmation dialog: “Activate this user? They will be able to sign in.” Click Activate to confirm.

Generating a temporary password

Click Generate password in the Password section. A 12-character password is generated and displayed on screen. Use the Copy button to copy it to the clipboard, then share it securely with the user. Click Hide to remove it from view. This does not send any email — you must communicate the password to the user manually.

Deleting a User

The Delete User button appears in the header of the User Details page when the following conditions are met:

You are not viewing your own account (self-deletion is blocked).
The target user is not a Super Admin, unless you yourself are a Super Admin.

Clicking Delete User opens a confirmation dialog that requires you to type the user’s email address exactly before the “Delete Permanently” button becomes active. This is a deliberate safeguard against accidental deletion.

Once confirmed, the user account is permanently deleted and you are redirected back to the Users list.

Billing

Invoices

The Invoices page (/invoices) lists all platform invoices. The layout has two areas:

Invoice table (left)

Columns: Invoice Number, Issue Date, Due Date, Amount, and Status. Statuses are colour-coded:

Billed — awaiting payment.
Paid — payment received.
Overdue — past the due date without payment.

Filter controls:

Search — search by invoice number.
Status — filter to All, Billed, Paid, or Overdue using the segmented button bar.
Sort by — Issue Date (newest/oldest), Due Date (newest/oldest), Number (A–Z / Z–A), or Status (A–Z / Z–A).

On mobile, filters are accessible via icon buttons in a compact row.

Current Plan Summary (right, clinic users only)

If you are signed in as a Clinic Admin, a sidebar panel shows:

Plan name.
Billing cycle (Monthly or Yearly).
Plan cost per period.
A Change Plan button that opens the subscription drawer.

Below it, a Payment Method panel shows the Stripe card on file and an Update Billing button.

Modules

The Modules page (/billing/modules) is the global module catalog — the master list of treatment modules available across the entire platform.

Each module in the catalog shows:

Name and optional description.
A status badge (Enabled or Disabled) indicating whether the module is offered platform-wide.
A toggle switch to enable or disable the module globally. Disabling a module here prevents it from appearing in any clinic’s module selector — even if a clinic had it enabled. Re-enabling it restores the ability for clinics to offer it.
An Edit button to update the module’s name and description inline.

Editing a module

Click Edit on a module row to expand an inline form with name and description fields. Click Save Changes to apply or Cancel to discard. Changes affect the name and description displayed to clinic admins in the Manage Modules dialog.

Product Catalog

The Stripe Catalog page (/billing/catalog) manages the Stripe products and prices that drive every subscription checkout and pack purchase.

The page shows two product cards:

Platform Plan — the recurring base subscription that clinics pay.
Try-On Pack (1,000) — an add-on that grants 1,000 additional try-ons per month.

Each card shows the product’s Stripe ID, active/inactive status, and the currently configured Monthly and Yearly prices.

Setting or changing a price

Click Change (or Set price if no price exists yet) on any price slot to expand an inline editor:

Amount — enter the price in major currency units (e.g. 400.00 for $400).
Currency — enter a 3- or 4-letter ISO currency code (e.g. USD, CAD).

Click Save to create a new Stripe price and archive the previous one. Existing subscriptions keep their current price until their next renewal. New subscriptions and checkouts use the new price immediately.

Click Cancel to discard without saving.

Creating a product

If a product card shows “Not created”, fill in the product name (and optional description) and click Create Platform Plan or Create Try-On Pack to create the Stripe product. You can then set prices on it.

Top bar actions

Sync from Stripe — pulls the latest product and price data directly from Stripe and updates the local catalog. Use this if prices were changed in the Stripe Dashboard.
Seed from env — migrates legacy STRIPE_PRICE_* environment variables into the catalog. Safe to run multiple times.

Analytics

The Performance Dashboard (/analytics or /groups/:id/analytics) provides a unified view of patient journey data and appointment activity for a clinic or group.

Time range

Select 7d, 30d, or 90d using the buttons in the top-right corner. All charts and KPIs update to the selected period.

KPI row

Four headline cards:

Visitors — total unique visitors who opened the Promote Link in the period.
Appointments — total appointment requests submitted.
Conversion Rate — appointments as a percentage of visitors.
Top Treatment — the most-explored treatment module, with the visitor count.

Quick summary row

Four secondary statistics showing stage-to-stage progression rates:

% of link openers who visited a treatment page.
% of site visitors who ran a smile simulation.
% of simulation users who requested an appointment.
Count of appointments confirmed and scheduled.

Treatment Performance

A per-module breakdown showing, for each treatment: how many visitors Explored it, how many ran a Simulation, and how many Requested an appointment. Conversion rates (simulation-to-booked) are shown alongside each module.

Promotion Performance

Cards for each active (and recently ended) promotion, showing the discount offered, the date range or “Ongoing” label, and the number of appointments generated during the promo period.

Appointment Pipeline

A donut chart breaking down all appointment requests by status: New, Scheduled, Call Back, Not Interested. The total count is shown at the centre.

Visitor Activity

A line chart plotting daily visitor counts (solid line) against daily appointment request counts (dashed line) for the selected period. Average daily values are shown below the chart.

Patient Journey

A funnel chart showing the four stages: Visitors → Treatment Explored → Simulation Viewed → Appointment Requested. Drop-off percentages between stages are shown as labels on the connectors.

Try-On Usage (clinic-scoped dashboards only)

A bar chart showing the last 6 calendar months of try-on usage against the clinic’s monthly limit. This helps identify seasonal patterns and decide whether to purchase additional try-on packs.

Top Try-On Consumers (Super Admin only)

A ranked list of the top 10 clinics by try-on usage in the current billing period. Each row shows the clinic name, group, usage count vs limit, and a progress bar. Clicking a row navigates to that clinic’s detail page. This view helps identify clinics approaching their quota or showing unusual usage.

Empty state

If no visitors have been recorded yet, a call-to-action panel reminds you to share the clinic’s Promote Link to start collecting data.

Group dashboard

Group Admins land on the group-scoped analytics view (/groups/:id/analytics). All charts aggregate data across every clinic in the group. The Try-On Usage history card is not shown on group dashboards (per-clinic numbers do not aggregate meaningfully across the group view).