Subscription Licensing

1 How it works

A customer's entitlement is a signed licence token — a small tamper-evident record (RSA-signed, JWT-style) that carries the concurrent-seat count, the entitled add-on modules, and the validity window. One token is installed per company database (in the WEB_LICENSE table).

Subscriptions and billing are per database. Each customer has an automatically numbered Company ID on the License Server. Under it, every company of their installation is a subscription of its own, keyed by Company ID + Company Code, with its own seats, modules, term, invoices and licence key. The key names its company, so it only works in that company's database, and an unpaid invoice suspends only the database it bills. Keys issued before this change carry no company code and still cover the whole installation until Ritzy assigns the subscription a code.

New companies register themselves. Every time an installation creates a company (New Company wizard, login-page Company Setup, or DBA Console), it reports the new code and name to the License Server. When no License Server URL is set, it reports to https://lic2.ritzy.net.

• Licensed installation — it sends the licence any of its companies holds, even one it cannot verify itself (the License Server does the check), with the same contact details as below. If that licence's customer is no longer on file (deleted in the console, or the licence was signed by another server sharing the key), the License Server re-creates the customer under the licence's customer ID, from the company's details, with a note saying so, rather than recording nothing. The company then shows on the customer's page under Company databases as no subscription yet, with an Add subscription button, and the Customers list tags the customer N new.
• Installation with no licence yet (first-run, trial) — it sends the company with the contact details from the wizard (email, telephone, city, country, base currency, chosen modules and the server name). If no customer has that company name, the License Server creates one under Customers, with those details in its notes and a customer code made from the name. The company then shows on that customer's page as no subscription yet, the same as for a licensed installation. A retry or a re-created company finds the same customer rather than adding another.

The License Server keeps each company's setup details, not just its code and name: the customer's page lists them in a Registered companies card (code, name, email, telephone, location, base currency, modules, server, when it registered and when its details were last updated). Saving Settings → Company in Ritzy One sends the stored details again (after the save, so an unreachable License Server never holds it up), so the card stays current; a blank field never clears a value already held.

Nothing is billed or licensed until Ritzy adds a subscription. Companies created before the install had a licence are reported again under the customer when it is activated. If the License Server cannot be reached, or is an older version that refuses an unlicensed install, the creation log says so — the company is still created, and Ritzy adds it by hand.

Two keys, two roles:

• Private signing key — held only on the Ritzy License Server. It signs (mints) tokens. Whoever has it can create licences, so it never leaves that one box.
• Public key — deployed to every customer install. It verifies tokens but can never create them. A customer can install a key Ritzy gave them, but cannot forge or extend their own licence.

The running app enforces the token in three places: the concurrent-seat cap at login, module access (add-on routers & the sidebar menu), and expiry (login is blocked past the validity window plus grace).

What counts as a seat. Seats are counted per browser device signing in to the web app; all tabs of one browser count once. Two kinds of sign-in are exempt and consume nothing: the DBA account (so a mis-sized licence can never lock you out of the console that fixes it) and every phone app registered in Tools → PWA Apps — Track, Dues, CRM, Delivery, Notify, Ask and Support, plus any the customer adds themselves. Phone apps are companions to a desk seat, not seats of their own. Module entitlement and expiry do still apply to them: a phone app cannot reach a module the customer has not bought, and an expired subscription blocks its login like any other.

Issue mint & deliver signed keys   Enforce remote heartbeat & revocation   Bill subscriptions, auto-renew & PayPal

2 The Ritzy License Server

Licensing is run from a separate, vendor-only application — the Ritzy License Server (package license-server). You run it centrally; customers never see it. It is self-contained (its own Firebird database, LICENSE.FDB; see §16) and has its own login with optional two-factor authentication.

It is the only place the private signing key lives, so licence keys can only be minted here. A customer's own copy of Ritzy One can verify and install a key, but contains no signing path at all.

The console

The phone app (Ritzy Licensing)

Ritzy Licensing is an installable phone app for the same server, at https://<server>/app/ (for the live server, https://lic2.ritzy.net/app/). It uses the same login, two-factor, roles and permissions as the console — there is no extra port, service or installer step. Each tab and button appears only for a role that holds its permission, and the server checks every call as usual.

1. On the console Dashboard, find the Ritzy Licensing phone app card. It shows the install QR code, with Copy link, Open and Print QR.
2. Scan the QR code with the phone and sign in with your License Server account.
3. Add it to the home screen when the phone offers to install it.

Proposals, the rate card, users, the knowledge base and server settings stay in the desk console.

The customer side

On a customer install, the app's DBA Console → Licensing tab is install-only: paste the key (or upload the .lic file) Ritzy supplied and install it, view what is installed, or remove it. There is deliberately no key-issuing, key-pair, subscription or revocation tooling on a customer install.

3 One-time setup

1. Deploy & run the License Server. Install dependencies, copy .env.example to .env and set at least ADMIN_JWT_SECRET and a strong BOOTSTRAP_ADMIN_PASSWORD; then build and start it. It listens on PORT (default 4100) and serves both the API and the admin console.
2. Sign in & secure the account. Log in with the bootstrap admin, open Settings, change the password, and enable two-factor.
3. Generate the signing key pair. In Settings → Licence signing key, click Generate new key pair. The private key is stored on this server (and shown once to back up); copy the public key.
4. Trust the public key on every customer install — do it in the install itself: Tools → DBA Console → Licensing → Trusted public key. An install points at the live server https://lic2.ritzy.net out of the box (step 6), so normally you just click Auto-configure from License Server — one click, it fetches and trusts the key from that server. Otherwise enter the License Server URL (https://lic2.ritzy.net, or http://localhost:4100 for a lab box running both) and click Fetch & trust, or paste the public key PEM. It takes effect immediately, with no .env edit or restart. (Alternatively, set LICENSE_PUBLIC_KEY_FILE or LICENSE_PUBLIC_KEY in that install's .env; an env value takes precedence and pins the key.) The public-key fingerprint shown in Settings and on the Licensing tab lets you confirm a match.
5. Point each install at the server — nothing to type for the live server: an install whose URL has never been set uses https://lic2.ritzy.net, and creating a company database records that address in DBA Console → Licensing → License Server URL. To use a different server, enter its base URL there (e.g. http://localhost:4100 on a lab box); the /api/license/heartbeat path is added for you and it takes effect with no restart. A URL already saved there is never replaced. This drives the suspension/renewal heartbeat and the one-click Auto-configure from License Server button in step 4. (Equivalent env var: LICENSE_HEARTBEAT_URL, which pins it if set. For pure offline / on-prem, clear the URL in the console.)
6. Turn enforcement on where you want it — the Enforcement switch on DBA Console → Licensing. It takes effect immediately, with no .env edit or restart, and activating a code (see §4) turns it on for you. (Equivalent env var: LICENSING_ENABLED, which pins enforcement either way when set and makes the switch read-only.) Once enforced, a licence badge appears in the app header — green Licensed when a valid key is active, amber in the grace period, and red (Trial / Expired / Suspended / Unlicensed) otherwise; hover it for the plan, seats and expiry. With enforcement off it shows a neutral grey Unlicensed (the app runs unrestricted).

4 Issue & deliver a licence

In the License Server console:

1. Create the customer — Customers → New customer. The Customer code you set here is the stable id embedded in every token and used by billing and revocation. It is typed in capitals, here and wherever a customer is created from an enquiry or a proposal. Deployment (saas / onprem / hybrid, where hybrid is e.g. their own server plus Ritzy-hosted apps) is informational only: it is shown on the customer and has no effect on licensing, heartbeat or billing.
2. Issue a key, either way:
   • As a subscription (recurring) — open the customer and create a Subscription (seats, modules, dates). Saving mints the token automatically and can auto-renew it later.
   • As a stand-alone key (one-off / on-prem) — open the customer and click Issue stand-alone key on the Company databases card (or Stand-alone key beside a database that registered itself, which fills in its company code); set seats, modules, valid-to and grace, and click Issue key. No subscription, auto-renew or invoice is created.
3. Deliver it — send an activation code (the normal way). On the customer's page, Activation code → New activation code: choose how many times it may be used (1 for a single install), an optional expiry, and an internal note. The code — RTZY-XXXX-XXXX-XXXX — is shown once and copied to your clipboard. That single string is all the customer needs; no key file and no public key.
4. The customer activates, either in the last step of the New Company wizard or, if that was skipped, signed in as DBA: Tools → DBA Console → Licensing, paste the code into Activate this installation and click Activate. The install then trusts the vendor's public key, pulls and verifies its licence, saves the heartbeat URL, installs into every company, and switches enforcement on — in one step, so the trust-then-install ordering cannot be got wrong. The License Server URL field is needed only if the install does not already have one.
   Administrators can activate too, without the DBA Console: any member of the ADMINISTRATOR group clicks Activate on the licence banner at the top of the screen and pastes the code. After the trial has ended an administrator can still sign in — they see only an Activate Ritzy screen, then sign in again once it succeeds. This path always activates against the License Server the install is already configured for (it has no URL field); an install that must be pointed at a different server is activated by the DBA in the DBA Console.

Manual delivery (offline / air-gapped installs)

When the install cannot reach the License Server, fall back to the old path: Copy key or Download .lic, and have the customer use Advanced / offline setup on the Licensing tab — first Trusted public key (paste the PEM), then Install a key by hand. The key is verified against the trusted public key before it is written; an unverifiable key is refused. If the install does know a License Server URL, installing an unverifiable key now auto-fetches that server's public key and retries once rather than simply failing.

5 Seats & modules

Seats are a single global pool of concurrent devices. All tabs/windows of one browser count once; the Customer Statement PWA is exempt and never consumes a seat.

Modules are sold as per-module add-ons. Enforcement separates “installed” from “entitled”: a company database physically contains every module's tables, but if the module isn't in the token it is hidden from the menu and its routes return “not included in your subscription”. Selling a module later is just re-issuing the token with one more entry — no database change.

A newly granted module installs itself. When a key that adds a module reaches the customer — activating a code, installing a key, or a plan change delivered by the heartbeat — the install sets that module up in the company database (its menu entry, its tables and its admin rights) so it appears straight away. Only modules the new key grants and the previous one did not are installed this way; a module that was already licensed but skipped in the New Company wizard is left alone and is listed in the result, pointing at DBA Console → Modules.

6 Heartbeat & revocation

Each licensed install periodically checks in with the License Server and applies the answer — so you can cut off or restore access, and deliver renewed tokens, between renewals.

Suspend or revoke a customer

1. Open the customer (or the Revocations page) and choose Suspend (temporary, e.g. non-payment) or Revoke (permanent), with a reason.
2. On its next heartbeat the customer is blocked, with your reason shown, and add-on modules are cut off. Click Re-activate to restore.

Enable it

Installs heartbeat to https://lic2.ritzy.net/api/license/heartbeat by default. To use another server, set its URL in DBA Console → Licensing → License Server URL (or pin it with LICENSE_HEARTBEAT_URL). For offline / on-prem installs, clear the URL there (revocation then only takes effect at token expiry).

7 Billing & auto-renew

A subscription turns a licence into a recurring plan that renews itself and chases non-payment. It is managed on a customer in the License Server console.

Create a subscription

Open a customer → Create subscription and set seats, modules, currency / amount, billing cycle (Monthly / Quarterly / Half-yearly / Yearly), Days, and the three day windows below. Saving mints the first token and raises the first invoice.

Days sits between Start date and Next renewal. Picking a cycle fills it with that cycle's default — Monthly 30, Quarterly 90, Half-yearly 182, Yearly 365 — and Next renewal is the start date plus Days, recalculated as either changes. Change Days for a one-off length (a 45-day term, say). The days are stored with the database's subscription and every renewal moves on by exactly that many days; Amount / period is billed once per cycle. Subscriptions saved before Days existed keep renewing by calendar months until they are edited and saved. The company code is always stored in capitals.

Currency is picked from a searchable list (AUD, NZD, USD, EUR, GBP, SGD, INR, LKR and the Gulf currencies) and defaults to AUD; the same list is on Import invoice. Next renewal fills itself in from the start date and the billing cycle, and follows them when either changes — overwrite it only for an unusual first term.

Change a plan (upgrade / downgrade)

To add modules, change the seat count, or adjust the price mid-term, open the customer and Edit the subscription. Saving re-issues the licence token with the new entitlement and delivers it to the customer automatically on their next heartbeat — even mid-term, when the expiry date is unchanged. For on-prem, send the new .lic from the customer's Issued keys list.

• Upgrade — when the new amount is higher, an immediately-due invoice is raised for the prorated difference over the days left in the current term (e.g. 100 → 160 / month with 15 of 31 days remaining raises a 29.03 upgrade invoice). Collect it with a Payment link, the Charge saved button, or Mark paid. The console confirms the invoice on save.
• Downgrade — the lower price simply takes effect from the next renewal; nothing is charged or credited immediately.

What the daily sweep does

• Auto-renew — on the renewal date it re-issues the token with a later expiry, advances the next-renewal date, and raises the next invoice. The renewed token reaches the customer on their next heartbeat automatically.
• Dunning — an invoice left unpaid past its due date marks the subscription past due; past the dunning window it is suspended (via the revocation list). Marking the invoice paid reactivates the customer immediately. A suspended subscription does not auto-renew.

Run it any time with Settings → Run renewals now; it also runs daily when LICENSE_BILLING_ENABLED=true.

Invoices raised in Ritzy One (import)

Ritzy's own accounts run on Ritzy One, so a subscription invoice can be raised there and imported here with its PDF:

1. Raise the invoice in Ritzy One and save its PDF.
2. On the customer's page, Invoices → Import invoice: enter the Ritzy One invoice number, invoice and due dates, amount and a description, and drop in the PDF. The Subscription period is optional and starts empty: fill both ends if the invoice covers a term, or leave it blank (the period then shows as - here and in the customer's Subscription & Billing). Company is typed in capitals and must be a valid Ritzy One company code; an invalid code is refused with a message rather than dropped, so the invoice never lands silently under the billing company. Tick Already paid in Ritzy One if it is settled.
3. The customer's administrator sees it under Tools → Subscription & Billing, opens the PDF, and can pay it with PayPal. Dunning treats it like any other invoice.

Importing records the invoice against the subscription only; it does not move the renewal date. To stop this server raising its own invoice at each renewal as well, edit the subscription and set Invoices to Imported from Ritzy One: renewals still extend the term and re-sign the licence, but raise nothing. A PDF can be attached or replaced later from the invoice row, and an open invoice raised in error can be Voided.

Several companies on one licence

When one licence is installed into several companies of an install, every company presents the same customer. Invoices show only in the subscription's billing company (each invoice can name a different one on import); the other companies' Subscription & Billing screens say where the invoices are. The first company to open that screen becomes the billing company; change it with Edit → Billing company, which lists the company codes the install has reported. The code is typed in capitals; one that is not a valid Ritzy One company code is refused with a message.

8 Online payments (PayPal)

Optional. Two flows, both run from the License Server: a hosted payment link per invoice, and off-session auto-charge of a saved PayPal method on renewal. Payers authenticate on PayPal's own pages — card and account details never reach Ritzy; only an order reference and, if the payer opts in, a saved-method token are stored.

1. Create a PayPal REST app — sign in at developer.paypal.com → Apps & Credentials. Choose Sandbox (testing) or Live, then Create App, and copy the Client ID and Secret.
2. Configure the License Server — in its .env set PAYMENT_GATEWAY=paypal, PAYPAL_ENV=sandbox (or live), PAYPAL_CLIENT_ID, PAYPAL_SECRET, and PUBLIC_BASE_URL (this server's public URL, reachable by PayPal — https in production). Keep secrets in .env only.
3. Add the webhook — in the PayPal app → Webhooks → Add Webhook, set the URL to https://<server>/api/webhooks/paypal and subscribe to Payment capture completed (PAYMENT.CAPTURE.COMPLETED). Copy the Webhook ID into PAYPAL_WEBHOOK_ID. Every event is signature-verified against this id; unverified events are rejected.
4. Restart & confirm — restart the server, then in the console → Settings → Payments it should read “PayPal is configured (sandbox/live)”.
5. Take a payment — open a customer → an open invoice → Payment link. Send the link to the customer; on payment the invoice flips to Paid automatically (captured on return and confirmed by the webhook), lifting any dunning suspension.
6. Customers pay from inside Ritzy — nothing to send. A customer administrator opens Tools → Subscription & Billing in their own Ritzy, sees the plan and invoices, and presses Pay with PayPal on an open one. PayPal opens in a new window; once it confirms, the screen updates by itself and pulls the renewed licence at once. The install uses its licence token to call /api/license/billing on this server, so your PayPal secret never leaves the License Server and each install can only see and pay its own invoices.
7. Enable auto-charge — the payment link asks the payer to save their PayPal method. Once saved (Saved payment method: on file), the daily sweep and the Charge saved button auto-charge future renewals with no customer action. Use Forget to remove it.
8. Go live — after sandbox testing, create Live credentials and a live webhook, set PAYPAL_ENV=live with the live values and an https PUBLIC_BASE_URL, and restart.

9 Enquiries

The Enquiries page is the sales inbox. Website quotation requests arrive here automatically once intake is set up (below), and you add phone and email leads by hand. A company created on an installation that holds no licence yet does not come here: it goes straight under Customers (see §1). Older enquiries with source install date from before that change. From an enquiry you go on to a proposal (§10) or link it to a customer.

The inbox

The detail drawer

Click Open (or double-click a row). The drawer shows every field in readable form (country and module names rather than codes, mail and phone links), and:

• Status — change it from the drop-down; it saves at once.
• Notes (internal) — calls, what they said, what to send next. Click Save notes.
• Create proposal — opens a new proposal pre-filled from the enquiry: seats, modules, billing, hosting and the contact; its message is what the AI cover letter answers.
• Link to customer — either Create from enquiry (a new customer, with a suggested Customer code, typed in capitals, and the name, contact and email taken from the enquiry) or Existing customer. Once linked the button reads Re-link.
• Proposals — every proposal raised from this enquiry, with its revision, monthly total and status.

Adding a lead by hand

New enquiry opens the phone / email lead form: Contact (type, name, company, email, phone — an email or a phone number is required), Requirement (industry, country, modules, users, hosting, billing, start, data migration, online demo and demo time) and Notes (Their words and Our notes). It is saved with source manual.

AI Paste

For when the website's automatic post did not arrive, or the lead came in by email or message. AI Paste sits in the title of the New enquiry form and on the Customer card of the proposal editor. Paste the text and click Read it.

• The website's own notification email (the one send.php sends to the enquiries mailbox, in either its quotation or question layout) is parsed exactly, without AI. No Anthropic key is needed for it.
• Anything else — a reply, a forwarded mail, a WhatsApp message — is read by Claude, using this server's ANTHROPIC_API_KEY. Check every value.
• Either way the result is checked against the same value lists as website intake, and it fills only empty fields: anything you had already typed keeps your value. The summary says how many fields were filled, how many of yours were kept, and which are still empty. Nothing is saved until you save.
• An enquiry saved after a paste is recorded with source email-paste, and the form shows a reminder to check every field.
• In the proposal editor, the contact fills the empty customer fields, while seats, modules, hosting and billing go straight into the calculator, which re-prices. The country only suggests the tax (Australia = GST, anywhere else = export); change it if wrong. “Not sure” answers and the customer's message come back as notes.

Website intake setup

The website's quotation form (send.php) still emails every enquiry; with intake set up it also posts the same fields to this server. The post runs after the email is sent, is capped at 5 seconds and ignores every failure, so a License Server that is down or misconfigured never blocks the visitor or stops the email.

1. Generate a shared key — e.g. openssl rand -hex 32.
2. License Server — set ENQUIRY_INTAKE_KEY to that key in .env, plus BEHIND_CLOUDFLARE=true when the server is proxied by Cloudflare (the live one is), and restart. install.cmd asks for all three intake settings (key, posts per minute, Cloudflare) and can generate the key. The endpoint POST /api/enquiries/intake needs the key in the X-Enquiry-Key header. While the key is unset it answers 404 and nothing is exposed. The Enquiries page then shows website intake on.
3. Website config — create ritzy-config.php one level above the site root (never in the web root, never in git), returning enquiry_intake_url (https://lic2.ritzy.net/api/enquiries/intake) and enquiry_intake_key (the same key). If the host does not allow files above the web root, use a private/ folder denied by .htaccess. With the file missing or empty, send.php simply skips the post.
4. send.php — paste the snippet from packages/license-server/website-intake.md straight after the mail() call. That file has the full snippet, the example config and the Cloudflare steps.
5. Cloudflare — add a WAF custom rule that skips managed rules, rate limiting and bot checks for POST /api/enquiries/intake: there is no browser to solve a challenge. Keep SSL/TLS on Full (strict).
6. Test — a curl POST with the key answers {"ok":true,"id":N}; a wrong key gives 401, and a server with no key 404.

10 Proposals & pricing

A proposal is what the customer receives: a cover letter written for them, the features of the modules it sells, an implementation & training timeline, and the investment. (Proposals were called quotations until October 2026; old /quotations links open the same proposal, and the numbers stay RQ-YYYY-NNNN.)

Proposals are priced from a versioned rate card by one shared pricing module that both the console and the server use. The breakdown you see while editing is computed in the browser; on save the server prices the same inputs again against the same rate card and stores its result, so a total can never be typed in.

Write a proposal

Proposals → New proposal, Create proposal on an enquiry, or New proposal on a customer's Proposals tab (each pre-fills what it knows). The tag at the top shows the rate card in use, e.g. Rate card v1 · from ….

Saving gives the proposal its number, RQ-YYYY-NNNN (drawn in sequence per year), as Rev 1.

The proposal page

• Summary — prepared for, linked customer and enquiry, subscription per period excl. GST, per month incl. GST, first invoice, valid until.
• Cover letter & timeline — the latest revision's letter and timeline. While the proposal is a draft, Edit changes them in place (wording only; prices stay as priced). Once sent or decided they are fixed: Revise to change them.
• Status actions — Mark sent, Mark accepted (with a confirm), Mark rejected and Back to draft.
• Revise — opens the editor pre-filled from the latest revision and saves Rev n+1. Every revision is stored unchanged, so an old one reprints exactly as sent. A revision is priced on the rate card in force today; if that differs from the previous revision's card, the editor says so. The letter and timeline carry over to edit. An accepted proposal cannot be revised; start a new one.
• Revisions — every revision with date, author, rate-card version, seats, modules, billing, totals, valid-until, status and a Print button.
• What changed — pick two revisions to compare field by field (seats, modules, billing, tax, hosting, discount, overrides, reason, party, totals, terms, cover letter, timeline); changed rows are highlighted.

Accepted → subscription

Once marked accepted, the page offers Create subscription. The dialog is pre-filled from the accepted revision: customer (existing, or a new one with a Customer code typed in capitals), plan, seats, modules, cycle, amount per period excl. GST, currency and start date. Create subscription + sign licence goes through the normal billing path (§7): it signs the licence and raises the first invoice. One-time charges are not part of the subscription; invoice them separately. If the customer already has a subscription, the dialog warns that saving updates it to these terms (with a prorated invoice when the amount goes up mid-term). The button is disabled until a signing key exists.

Print preview

Print preview (or Print on a revision row) opens the stored revision in its own window with a toolbar: Print / Save as PDF and Close. A superseded revision is marked so in the toolbar. For a PDF, pick Save as PDF as the printer; the file is named after the proposal number, revision and customer. On screen a dashed line marks each page break. The document, on A4:

1. Cover page (page 1, edge to edge) — logo, “Ritzy One for customer”, seats, modules, hosting, billing and the length of the implementation plan; prepared for, prepared by, number, revision, date and valid-until.
2. Cover letter, when there is one, from page 2, addressed to the customer.
3. Your Ritzy One solution — a card per module with its features: Accounts marked Included (the core of every seat), each selected add-on marked Add-on.
4. Implementation & training timeline — a week-by-week chart of the phases and what happens in each.
5. Investment — the subscription and one-time lines, any discount note, and the totals with GST and the first invoice.
6. Terms and an acceptance block for both parties.

The features and the investment each start a new page; tables, totals, the timeline chart and the signature block are never split across pages, and every page after the cover carries Page n of N.

Revisions written before proposals print without a letter or timeline. The module feature lists come from src/shared/proposal.ts in the License Server.

The proposal list

Proposals filters by status (All, Draft, Sent, Accepted, Rejected, Expired) and searches by number or customer. The same list, limited to one customer, is the Proposals tab on that customer's page, beside Licence & billing.

Settings → Pricing (the rate card)

The rate card the calculator prices with, before GST: platform seat (incl. Accounts), each module per seat, seat bands (each seat pays its band's share of the full rate), bundle discounts for 3–4 and 5+ modules, annual billing as 12 months for N, GST %, one-time implementation (set-up plus per module) and training per seat, and Ritzy Cloud hosting tiers with a cloud set-up fee. Version 1 is seeded with the draft AUD rates.

• Edit rates saves a new version with an Effective from date and a note; versions are never changed. Proposals already written keep the version they were priced on.
• A version dated in the future is held and takes over on its effective date.
• View shows any past version; Start a new version from this copies it into the editor.

11 On-prem vs SaaS

The same signed-token core serves both; only the delivery and the heartbeat differ by configuration. An offline install keeps working on its signed token plus the grace window until the next successful heartbeat.

12 What the customer sees

The customer installs the key you sent from Tools → DBA Console → Licensing. Thereafter, when a licence needs attention an app-wide subscription banner appears automatically (silent when the licence is healthy):

13 Settings reference

License Server (the vendor box)

Set in the License Server's .env. This is the only box that holds the signing key.

Customer install

Set in each customer's Ritzy One API .env. These carry only the public key — no signing capability.

14 AI Customer Support

The License Server is also the brain behind the Support button inside every customer's Ritzy. Customer installs do not answer support questions themselves — they forward them here over the licence token they already hold, and this box does the AI call, the search and the learning. That is deliberate: no customer needs an Anthropic key, you keep one bill and one prompt to improve, and every question from every site lands in one corpus.

Turning it on

A customer install needs nothing configured at all: if it has a valid licence and can reach this server, the Support button appears. If it cannot, the button hides itself.

The three console pages

How it gets better

Three corpora are searched together and ranked against each other — knowledge-base articles first, then manual sections, then past answers. Two things feed the last of those:

On a good conversation, Draft article in the thread drawer asks the assistant to turn it into a knowledge-base article. Read it before publishing — a published article is repeated to every customer who asks something similar, so a mistake there is expensive.

Live chat — taking a conversation over

Any customer can press Talk to a person in the Support panel (web app, every phone app, and the Ritzy Support app). The assistant then stops answering that conversation and it waits for you. You can also join a conversation nobody asked you into — for example one that is going badly.

Phone notifications. In the Ritzy Licensing app, turn them on from the Support tab or More. With the app closed you are told when a customer asks for a person, when the customer in a conversation you are handling writes, and when a ticket is escalated. Who is told follows the role: Support inbox & live chat for chats, Escalated tickets for tickets. Tapping one opens that conversation or ticket. There is nothing to configure: the server creates its own push keys in its data folder (push-vapid.json). If that file is lost, everyone turns notifications on again. On an iPhone the app must be installed to the home screen first. A question the assistant answers does not notify anyone.

Set SUPPORT_WHATSAPP in the server's .env to give customers a Call Ritzy on WhatsApp link in their chat. It stays off in Ritzy Dues, whose reader may be your customer's own customer.

Being signed in to this console is being available: while any page of it is open, customers who ask for a person are told someone will join shortly; when nobody has it open they are told honestly that their conversation is queued. Closing a conversation (status Closed) also ends the live chat.

15 Users & roles

Every person who uses the console gets their own login with a role, so the tool can be handed to Accounts, Sales and Support without giving everyone the signing key. Manage them in User Manager (Administrators only).

Built-in roles

A role is a set of permissions: View customers, Manage licences, Manage billing, Sales, Support inbox & live chat, Escalated tickets, Knowledge base, Server settings, Database backup & restore, Users & roles. Only Administrators have Database backup & restore until you give it to another role. Built-in roles other than Administrator can be edited, and New role makes your own (e.g. “Collections” = View customers + Manage billing). A change applies to everyone with that role on their next click.

Adding someone

1. User Manager → New user: username, display name (what customers see in live chat — “Sam from Ritzy Support”), email, role.
2. Leave the password blank and a temporary one is shown once. Give it to them by a separate channel.
3. At first sign-in they must choose their own password before anything else works. Ask them to turn on 2FA in Settings → My account.

When someone leaves, or loses their phone

Audit log

User Manager → Audit log records sign-ins, failed sign-ins, and every user and role change, with who did it and from which address. It cannot be edited from the console.

16 Database & backups

Everything the License Server knows — customers, subscriptions, invoices and their PDFs, licence keys, activation codes, support conversations, console users and the audit log — is in one Firebird database, data\LICENSE.FDB, on the Firebird server installed on the same machine (Firebird 3, 4 or 5). This is the vendor’s own server only: customer installs of Ritzy One run on PostgreSQL and need no Firebird. The License Server creates it, with all its tables, the first time it starts. Its connection is set by LICENSE_FB_* in .env (§13).

Upgrading a server that used SQLite

Servers installed before 30 October 2026 kept their data in a SQLite file, data\license.db. To upgrade:

1. Install the Firebird server on the machine, if it is not already there.
2. Deploy the new build as usual. The deploy adds the new settings to .env; if the SYSDBA password is not masterkey, set LICENSE_FB_PASSWORD.
3. Restart the service. On this first start the database is created and everything in license.db is copied into it, with the same customer codes, Company IDs and record numbers. The log shows each table and how many rows came across.

license.db itself is only read, never changed. Keep it until you are satisfied, then delete it.

Backups

Backups are made with Firebird's own tool, gbak, while the server keeps running. They are .fbk files in data\backups (LICENSE_BACKUP_DIR), and appear in the License Server under Settings → Database backup:

Each backup can be downloaded. Copy backups off the machine too: a backup on the same disk does not survive the disk.

Starting over on a test server

To wipe a test License Server and install again, run uninstall.cmd -Yes -PurgeData as Administrator from its folder: it removes the service and deletes .env and the whole data\ folder (database, backups and the signing key pair), then run install.cmd. Never on the live server — without the private key no licence ever issued can be verified. Full steps, for the customer install too, are in the installation runbook, §13.

Restoring

1. Settings → Database backup, choose the backup, Restore, and type RESTORE.
2. The backup is first restored into a scratch database to prove it is sound; a damaged backup stops here and nothing changes.
3. The current database is backed up (Before restore), then replaced. Customer installs and the console wait for the few seconds this takes; nobody is signed out.
4. If the replacement fails, the Before restore backup is put back automatically.

To undo a restore, restore its Before restore backup. A restore replaces everything, console users included, so a user created after the backup was taken no longer exists afterwards. Backups, uploads, deletions and restores are written to the audit log (§15).

17 Troubleshooting