Skip to content

System › Billing

Badger staff manage what shops pay for the platform under System › Billing (/system/billing). Only superadmins can open it. It has four parts: an overview, the subscriptions of every shop, and the plan and add-on catalogue. A Billing card on each tenant's page (System › Tenants › a shop) shows that shop's plan at a glance.

All amounts are ex VAT. How a plan turns into what a shop may use is described in Subscription Entitlements.

Overview

  • MRR (ex VAT): what paying shops (active or past due) bring in a month at list prices: the plan price, add-on prices and extra locations, with an annual price counted as a twelfth. Trials and shops on a plan with no price (comps) count nothing. Coupons aren't known here; Stripe's reports are the books.
  • In a trial, trial conversion (trials that ended and became paying, against those that ended without) and past due (a renewal failed and Stripe is retrying; the shop keeps its features meanwhile).
  • By plan: shops, paying, trialing, past due and MRR for each plan.
  • Recent System actions: every change made on these pages, with who made it.

Subscriptions

The list shows every shop with a platform subscription: plan, status, trial end, renewal date, MRR and how it came to be on its plan (self-serve, assigned by us, or moved from Badger Sett). Search by shop name, site id or business name; filter by plan, and by trialing, past due, active, paused (paused, cancelled or unpaid) or over limit (over at least one limit when it was last counted).

A shop's page shows its subscription, its limits against what it uses (once usage is counted), its allowances and its history: Stripe events, System actions and the changes the shop's own owner made in Plan & billing (shown as "Owner: ..."), newest first. From there:

Action What it does
Assign a plan Puts the shop on a plan here, with no Stripe charge: a sales-led deal, a charity, a comp. Pick one of the plan's prices, or none for a comp. Works for a shop with no subscription, which then gets one. A shop holding an add-on the new plan can't take is refused until the add-on is removed
Grant an allowance A one-off raise of one limit: add a number, or lift it altogether, until a date or until removed. A reason is required (no names or contact details). It is added to the shop's total, even for a per-location limit. Remove it from the same card
Move the trial end Sets a new trial end (the end of the day picked, in the shop's time zone); a shop not in a trial starts one, and a paused shop stays paused. For a shop paying through Stripe the change is made in Stripe
Pause / Unpause A paused shop keeps its data but loses its plan's features. Only for a plan assigned here: a shop paying through Stripe is cancelled instead, so Stripe stops charging it. A cancelled or unpaid subscription can't be paused; assign a plan to start it again. Unpausing returns it to its trial (if that is still running) or to active
Cancel At the end of the current period, or now (type CANCEL to confirm). A plan assigned here with no period ends now. The shop is paused when it ends, never deleted
Re-sync from Stripe Re-reads a Stripe-backed subscription and saves what Stripe says
Invite to choose a plan For a shop that pays Badger by invoice (no subscription, or a plan assigned here with no Stripe subscription). Pick the plans to show it (a family with public, self-serve plans) and the date it has paid up to. The shop then sees Choose your plan in its own Plan & billing, pays for one by card in Stripe Checkout and keeps its site; see Moving from invoices to a plan. Inviting again updates the family and date; Withdraw invite takes it back. Not offered for a shop already paying through Stripe

Every action is recorded in the shop's billing history with the superadmin who did it. Actions that change Stripe (moving a trial, cancelling or re-syncing a Stripe-backed subscription) are refused with a message until Stripe billing is deployed; plans assigned here work without it.

Moving from invoices to a plan

Shops that pay Badger by direct invoice can move onto a self-serve plan without a new sign-up:

  1. On the shop's page, Invite to choose a plan with the plans to show and the paid up to date: the last day of the period the shop has already paid by invoice (blank to charge as soon as it pays). Recorded as "Choose plan invited".
  2. The shop's owner or an administrator sees Choose your plan in Plan & billing: the family's public plans as cards, with any limit the shop is already over listed and that plan not choosable.
  3. Choosing one opens Stripe Checkout for the existing site: the plan's base price, monthly or yearly, with no setup fee, no free trial and no founding price. The card is first charged at the end of the paid-up-to day (Stripe's trial_end; Stripe wants it at least 48 hours ahead, so a nearer date becomes 49 hours from checkout). Recorded as "Owner: plan checkout".
  4. When Checkout completes (the billing webhook or the owner's return, whichever is first), the Stripe subscription is attached to the shop's subscription, created if it had none: plan, price, status and dates from Stripe, source self-serve, setup fee none, the entitlement re-projected. No site is created. Recorded as "Owner: plan chosen", and posted to Slack.

From then on the shop is an ordinary self-serve shop: plan changes, add-ons, card and invoices and cancelling work from its own Plan & billing, and enforcement follows self-serve rules. Add-ons and extra locations assigned by hand, a booked change and a founding lock are cleared; allowances stay. Until the paid-up date the subscription is trialling in Stripe, but the shop is shown as paid up, not on a free trial, and gets no trial banner. Moving the trial end here afterwards makes it an ordinary trial.

A shop that already has a Stripe subscription can't start one. Only one Checkout can be paid at a time: choosing a plan again expires the payment page opened before (and is refused if that one was already paid). Only the Checkout the shop's open invite last opened is applied. A migration Checkout paid any other way (the invite withdrawn or re-issued meanwhile, a plan assigned here and the invite used, the shop gone) is not applied: its Stripe subscription is cancelled at once and Slack is told to refund any payment taken. The webhook and the owner's return page can't both apply the same Checkout: the first to claim the shop's subscription record applies it and records it, once.

Plans

The plans list shows each plan in pricing-page order with its family, who can take it, status, monthly price, trial and whether it has been synced to Stripe.

A plan has:

  • Name (can change at any time) and slug (its stable identity, never changes).
  • Family (retail, hospitality, charity, enterprise or custom), edition (Lite or Enterprise: the capabilities it starts from), who can take it (anyone from the pricing page, anyone with the link, or only when we assign it), status and order.
  • Free trial, in days or calendar months. A card is always taken; a change applies to new sign-ups only.
  • Limits: products, admins, locations, bookable people, online table bookings a month, staff and monthly active customers. Blank is unlimited. Staff and monthly active customers are per location. Monthly active customers only ever warns; it never stops a shop trading.
  • Fees: the application fee per paid order or booking (a percentage plus a fixed amount) and a one-off setup fee, optionally waived on annual plans or founding places.
  • Capabilities: each one left at the edition's default, or switched on or off.
  • Add-ons offered with the plan, and the message keys for its pricing-card highlights.
  • "Talk to us" link, for a plan sold through a conversation such as Enterprise: an https:// address or a path on the marketing site (/enterprise). The pricing card then says Talk to us and links there instead of offering a free trial. Leave it blank for a self-serve plan. The plan's sign-up link (/start?plan=) still works for anyone who has it.

A plan anyone can take must limit products, admins and locations, and have a current monthly base price, before it can go on sale. Only a custom plan, made for one sales-led deal and assigned by us, may be unlimited; a custom plan is always "only when we assign it".

Saving a plan updates only the fields on the form and re-projects every shop on it in the background. It never overwrites the founding places taken or the Stripe ids. Publish puts a draft on sale; a plan anyone can take needs a monthly base price already synced to Stripe, so Sync to Stripe comes first. Retire stops new sign-ups (shops on it keep it, at the price they pay), and a draft nobody is on can be deleted.

Prices

Stripe prices can't change, so a new amount is a new price. A new current price replaces the current price of the same kind and interval for new sign-ups; shops on the old one keep it. Each price shows how many shops are on it. The kinds are the base price, the founding price, and the price of each extra location. A yearly price is filled in as ten times the monthly one, and can be changed.

Founding offer

A cheaper price for the first new shops, locked for a number of months from sign-up (trial included), then the base price. Set the number of places, the lock and, optionally, when it opens and closes. Saving never changes the places already taken. Close now stops new founding places while founding shops keep their price until their lock ends; an offer nobody has taken can be removed.

Sync to Stripe

Sync to Stripe creates or updates the plan's Stripe product and creates a Stripe price for each price that has none. It is switched off until Stripe billing is deployed.

Add-ons

Add-ons are edited the same way: name, slug, who can take them, status, the plans that may take them, the limits they add, the capabilities they switch, and their prices. An add-on's limits are added to the plan's: blank leaves the plan's limit alone, and a limit ticked as unlimited is lifted altogether. A price can apply to one plan, which then beats the add-on's general price on that plan.

Fee invoices

System › Billing › Fee invoices (the Fee invoices card on the Billing overview, and the subnav) is where Badger's monthly VAT invoices to shops for their Badger fees are watched and, when needed, run by hand (how they work). It replaces the manual invoice agent's screens:

  • Overview: all-time fees invoiced and the VAT in them; the fee trend (fees this year to date, the last 12 months and the fee transactions in them, each against the period before; monthly fees over three years with a rolling average; cumulative fees year on year), fees by shop with their share, Badger's own payouts from Stripe (newest first, with how many invoices each has), what each of the last payouts invoiced by shop, and recent runs. The trend is worked out from the issued invoices (FeeTrend), by the month their fees belong to, together with the fees of earlier payouts of shops that have since gone, which have no shop to show an invoice to: those are kept as HISTORIC records, loaded from Stripe's history by dev-scripts/migrations/historic-fee-invoices, which count in the trend but are not invoices, aren't in "Invoiced, all time" and are never shown to a shop. Fees from a Stripe account no shop is connected to count in the trend too, as "No shop (acct_…)": they are Badger's fees although nobody was sent an invoice. They are read from each payout's latest finished run, not stored, so when a shop is connected to the account and the payout is run again its invoice takes their place. A payout with only such fees issues nothing, but Run stays available once, to record them. For shops that still have a site, the same scripts load the earlier invoices as invoices: those raised in Xero by hand from October 2018 to January 2025 under their Xero numbers, and those raised from a spreadsheet before that, whose numbers are lost, under generated ones (HIST-DMRT-001). The by-payout chart names only the shops in the payouts it shows. A run takes its mode from the payout itself, as Stripe has it, not from the mode the page was opened in: on a stack whose platform key is a test key, the "live" view lists test payouts, and they are still treated as test ones (the shops they invoice, where they may be posted). The whole page is one mode at a time, live unless Show test mode is pressed: totals, trend, payouts and runs are never live and test added together, and a banner says when it is showing test mode. The Fee invoices card on the Billing overview is live only.
  • A payout (/payouts/{id}) is a dry run: the fees in it by shop, what each would be invoiced, where the email would go, and why a shop would be skipped. Nothing is issued from this page until Run: issue and email is pressed. A payout that has already been run says so per shop, with the invoice number. What's in this payout checks the payout against the deposit before anything goes to the accounts: Badger's fees, plus the payments taken on Badger's own Stripe account, less what Stripe charged, should be what reached the bank. The payments are listed one by one under "The n payments in this payout", closed while the payout adds up and open when it doesn't. A payment is a shop's plan payment (it paid a Stripe Billing invoice; named by its billing account) or is already in the accounts (anything else, such as an invoice raised in Xero and paid by card: match its own invoice there; Stripe's charge on it is in the bill for Stripe's charges). The card says "Adds up to the deposit", or that it doesn't: the deposit differs from what was read, or the payout holds something else (a dispute, an adjustment), which is listed. Nothing from a payout that doesn't add up should be entered until it is understood.
  • A run (/runs/{id}): what was issued and emailed, shop by shop, with each invoice to open, and Re-send (or Send, for an invoice that had no address).
  • For Xero, on both the payout and the run: the one sales invoice the payout puts in Badger's Xero, exactly as it would be sent (FeeInvoiceService.payoutInvoice, PayoutInvoice). It is to the contact in xero-payouts-contact (default "Badger Commerce payouts"), dated the payout's arrival with 30 days to pay, tax inclusive, referenced "Badger payout · ", with a line per shop: "Badger fees, , , ", the account in xero-fees-account-code (default 201), the tax rate in xero-fees-tax-type (default OUTPUT2), and the VAT from the shop's own fee invoice as the line's tax amount, so the two agree to the penny. The card says "Ready to post", or what is in the way: the invoices not issued yet (a dry run has no numbers to quote), a shop's invoice that failed, a payout that doesn't add up to its deposit, or fees the accounts already have (invoices from before Badger issued its own, INV-…, are left out and named), or a payout whose mode doesn't suit the organisation connected. A test-mode payout is posted only to Xero's demo company, and a live one never is (XeroConnectionService.modeProblem): Badger asks Xero whether the organisation is the demo company when it is connected and whenever the connection is checked, and the Xero page says which it is and which payouts it takes. So a demo or staging stack, whose payouts are all test mode, can be connected to the demo company and exercise the whole flow, while the real books only ever get live payouts.
  • Post to Xero, on that card once it is ready and Xero is connected, sends the invoice (PayoutPostingService, XeroInvoicePayload): an authorised, tax-inclusive sales invoice whose contact is given by name, so Xero uses the contact of that name or makes it the first time and no shop becomes a contact. Either contact setting may hold a Xero contact ID instead of a name (a UUID is sent as the contact's id); the contact must then exist in the connected organisation. The payout is read from Stripe again at that moment, not taken from a stored run. It is posted once: the record of the post is kept by payout (accountingPostings, payout-invoice:<payout id>), Xero is first asked for a sales invoice with the same reference (a post whose reply was lost, or one entered by hand, is adopted, not raised again), and the call carries an idempotency key. Afterwards the card says "In Xero as INV-…" with a link, and warns if the total or VAT Xero holds isn't what Badger sent. A failed post says why (Xero's own validation message when it refused the invoice) and can be tried again.
  • Payouts from before Badger posted to Xero were entered and reconciled there by hand (everything up to and including November 2026). The global setting xero-posting-from ("Xero: post payouts from", default 2026-12-01) is the first day whose live payouts are posted: an earlier one says why on its card and has no button, and automatic posting leaves it alone. Test payouts aren't held back, so the demo company can be tried with any of them.
  • A payout with nothing to invoice (no fees and no plan payment, only payments already in the accounts) can still have had Stripe's charges taken from it. Its bill is then posted on its own, from the bill's own button; otherwise the bill only ever follows the invoice.
  • The bill's reference (which names the payout) is what Badger looks for before raising another, so a post that reached Xero but wasn't recorded isn't raised twice. Xero keeps a bill's reference as the bill's own number, and that is where Badger puts it.
  • Fees with nobody to invoice still go to the accounts, since they are in the deposit: fees from a Stripe account no shop is connected to are a line "Badger fees, Stripe account acct_… (no shop to invoice)", and a shop whose refunds outweigh its fees is a negative line. The card says how much of the invoice that is; "By shop" shows which accounts.
  • Plan payments are lines on the same invoice (since November 2026): one for each payment of a Stripe Billing invoice in the payout, "<what Stripe's invoice was for>, , Stripe invoice ", at what the shop paid, with the VAT on Stripe's own invoice as the tax amount (PlatformFeeReader reads the invoice). The account is xero-plans-account-code (default 201); the tax rate is xero-plans-tax-type (default OUTPUT2) when the payment carries VAT and xero-plans-no-vat-tax-type (default NONE) when Stripe invoiced none. Money given back on a plan is a negative line with its share of the VAT. A payment for an invoice raised in the accounts themselves is never a line.
  • The bill for Stripe's charges is a second card, shown when Stripe took anything out of the payout (its charge on each card payment, and for its own services): a bill from the contact in xero-stripe-contact (default "Stripe"), dated and due the day the payout arrived, one line for the total, its VAT left to the tax rate. Its account and tax rate are xero-stripe-bill-account-code and xero-stripe-bill-tax-type, which have no default: until both are set, from a Stripe bill already in Xero, the bill is shown and not posted. It is posted after the invoice, by the same button, kept as stripe-bill:<payout id>, and gets a button of its own only if the invoice went in and it didn't. The invoice, plus any payment already in the accounts, less the bill, is the deposit.
  • Automatic posting is the global setting xero-posting-enabled ("Xero: post payouts automatically"), off by default; the Xero page says which way it is set. When on, a run that issues a payout's fee invoices (the webhook, the nightly catch-up or Run) hands the payout's invoice, and then its bill for Stripe's charges, to Xero straight away (PayoutAutoPoster). Anything that stops it is said in Slack, in the default admin channel and #badger-fees: Xero not connected, Xero refusing the invoice, or a payout that needs a look (a shop's invoice that failed, a payout that doesn't add up). It never fails the run. The nightly catch-up tries again any payout whose automatic post failed. It affects payouts from when it is switched on: one that was never tried is not reached back for (a payout typed into Xero by hand under another reference would be raised twice), and stays for the button. Go-live: connect Xero, post the first payout with the button and check it in Xero, then switch the setting on.
  • An invoice (/invoices/BF-DMRT-…): the printable invoice as the shop sees it.

Badger's own details on the invoices come from the platform-* settings in Global Config, group Platform billing.

Xero

System › Billing › Xero (/system/billing/xero, superadmins only) connects Badger's own Xero organisation, where the Badger fees in each payout are to be posted. It is one connection for the platform: no shop is connected to Xero by it, and there is no per-shop version of this page. So far it connects and stays connected; posting is the next step (docs/implementation-plan/badger-fee-invoices.md, "Phase 3 as planned on 2026-11-18").

Setting up, once:

  1. In the Xero developer portal, on Badger's app, add the Redirect URI the page shows (https://<system host>/system/billing/xero/callback).
  2. In Global Config, group Platform billing, set Xero: app client id and Xero: app client secret (xero-client-id, xero-client-secret).
  3. Press Connect Xero and sign in to Xero as someone who can post invoices in Badger's organisation. If that sign-in reaches more than one organisation, the page asks which one.

What the page shows: the organisation (marked "Demo company" when it is Xero's sandbox, with which payouts it takes: test-mode ones only for the demo company, live ones only otherwise), when it was connected, when the sign-in was last renewed and the date it lapses if nothing renews it, and when Xero last answered. Check the connection asks Xero for the organisation there and then. Connect again replaces the sign-in (the fix when Xero has dropped it). Disconnect removes Badger's access in Xero and forgets the tokens.

How it stays connected. Xero's sign-in is an OAuth 2 authorisation-code grant (XeroConnectionService, XeroClient, package accounting): a 30-minute access token and a refresh token that Xero replaces on every use and drops after 60 days unused. Badger refreshes the access token when it is about to lapse, and the worker's XeroKeepAliveJob (04:40 daily, badger.xero.keep-alive-*) renews the sign-in once it is a week old, so a quiet month can't disconnect it. If Xero refuses the saved sign-in, the connection is marked disconnected, the page says why, and Badger's admins are told in Slack (the default admin channel and #badger-fees), again each day until someone reconnects.

Where things are kept. The connection is one document in accountingConnections (PlatformAccountingConnection), with the tokens encrypted under accounting-token-encryption-key, a global secret created the first time Xero is connected (PlatformTokenCipher; clearing it disconnects Xero). Tokens, codes and Xero's response bodies are never logged. What Badger asks Xero for is badger.xero.scopes: invoices and bills, contacts, reading the chart of accounts and tax rates, and offline_access. If the host the page is opened on isn't the one Xero should send people back to (a proxy that hides it), set badger.xero.redirect-uri.

The Billing card on a tenant

System › Tenants › a shop shows its plan, status, trial end, how it came to be on its plan, its limits against usage and its allowances, with a link to manage it. A shop with no platform subscription says so: it has no plan limits.

See also