Runbook — activating automatic GST invoice issuance¶
Status: prepared, not performed. Automatic issuance (ADR 0022, extended by ADR 0024) is deployed with
ACCOUNTING_INVOICE_ISSUANCE_ENABLED=false, the settings gate invoice_issuance_enabled=false
and ACCOUNTING_JOURNAL_ENGINE_ENABLED=false. Nothing in this runbook happens by deploying the
code. Activation is a separate, deliberate operation, done only after the owner and the company's
CA have settled the items in §1 and the readiness screen shows nothing blocking but the two switches (§3). Never enable issuance,
and never run a historical backfill, "to see what happens": issued invoices are immutable and
their numbers permanent.
Roles in this runbook: owner (business owner / super admin), accounts admin (a super admin holds every accounts-admin step too, ADR 0023 - it cannot, though, switch issuance on from the portal, nor run a backfill under an approval it gave itself), GST accountant, CA (the company's chartered accountant, outside the system), engineering.
The release that brought scalable numbering, tax verification and recorded GST decisions has its own runbook:
scalable-invoice-numbering-release.md (deploy, read-only verification, rollback, and the owner/CA steps in order).
0. What a normal deploy does (and does not do)¶
Deploying the backend applies the pending migrations (098–103, and 104 and 105 with the verified-identity release of ADR 0025) after a
database dump, and deploying the Account Admin portal and the admin app adds the screens. All are additive. For the release that
brings migrations 104 and 105, deploy the backend, then the Account Admin portal, then the admin app, back to back: until each front end is
deployed, its tax approvals are refused (it does not yet send the written basis and the values the approver saw), so are the
portal's verifications (they now name the values the verifier saw), and nobody can confirm a mobile number from it - nothing is
approved or verified by mistake, it waits. Application deploys are manual dispatches (a merge to main publishes only the documentation site). After the deploy, verify read-only (dispatch production-accounting-verify with expected = enabled — the accounting module's flag, which is on — and release = privileged-recovery (the default) for the release that brings migrations 104 and 105, verified-identity for one that has 104 but not 105, scalable-numbering for a production that predates 104 or was rolled back below it (§7); optionally expected_commit = the commit you deployed, which the running API image tag must match; and production-issuance-readiness):
- the gate ends with two separate lines: TECHNICAL VERIFICATION: PASS|FAIL (schema, protections, flags, health, fail-closed behaviour, and the running image) and BUSINESS READINESS FOR INVOICE ISSUANCE: NOT ASSESSED HERE - a passing technical verification says the deployment is sound, never that invoices may be issued (use production-issuance-readiness for that). It also prints the number of active invoice series and issued sales invoices;
- the connection to the VPS is retried (up to five tries over about five minutes,
deploy/ci-ssh-run.sh), keeps the same authentication and host-key checking, and prints a masked failure class if it cannot connect ("Nothing ran on the host"). A run that fails there did not read production at all; - the three switches above are still
false(no deploy touches them; this verification is what checks it); - with release = verified-identity: migration 104 is tracked, its identity tables and columns exist, and its protection triggers exist and are enabled. The readiness probe then also counts the verified people and the configurations the invoice engine may use (none until settings are approved and verified under the new rule);
- the read-only owner blocks printed by the dry-run and sample-preview tools built from this release read migration 104's tables and columns, so run them only against a database that has 104 applied: before the deploy they stop with a "relation does not exist" or "column does not exist" error and print nothing (they fail closed);
- the number of invoices and invoice series is unchanged (still zero on a fresh book). Migration 098 refuses to apply if a financial year already has two active series and adds a check on the financial-year label; the production readiness probe shows the series count (zero), so neither can trigger - confirm it before the deploy;
- the portal's Sales Invoices → Readiness tab loads and lists the two gate checks as failed by design, together with every other open prerequisite.
No invoice is generated, no number is taken, no historical order is touched, and customers see nothing new (there is no customer-facing invoice route).
1. Decisions and facts that must exist first¶
| # | Item | Who | Where it ends up |
|---|---|---|---|
| 0 | Every person who enters, approves, verifies or runs anything confirms their mobile number on every login they use (ADR 0025): the owner, at least one other accounting person (Accounts Admin or GST Accountant) and the staff who enter GST values. A binding is per login — the accounting portal and the admin app each bind their own — and the same number on both makes them one person. Until two different people have done so, nothing can be run, approved or verified (a backfill approval can be given by one verified person) and readiness blocks (Verified identities). A store login (the admin app's, or a store login used in the accounting portal) confirms the number it signs in with — its phone on file, when that is an Indian mobile number: any other number is refused, and if that phone is no longer the person's, a Super Admin corrects the number on file first. No two store accounts share a phone, so one person's two store logins are one person only if one of them has no Indian mobile number on file. The SMS reads like a login code ("… is the OTP to log in to your Aim Store Account"); type it on the identity card. A number bound to the wrong portal login is withdrawn by a Super Admin, never their own, from Users & permissions; the holder then confirms the right number. A store login is moved to another number by changing the phone number on file (admin app: Users → this account; the list shows the newest 200 accounts, so an older one is opened as /users/<its Firebase uid, URL-encoded>): that ends its binding and the holder confirms the new number. Withdrawing a store login's binding alone does not move it, because the login can then prove only the number still on file. Redis holds the six-digit challenges as short hashes, so it must be reachable only by the API. A Super Admin's password reset or reassignment of a portal login, and a change of a store login's phone on file, also end its binding: its holder confirms again. |
each person, for each of their own logins | accounting portal → Settings → Your identity; admin app → Configuration page → the Confirm your mobile number card |
| 0a | Who recovers a privileged login (ADR 0025, migration 105). The phone of an admin, Super Admin, support or accounting-role login can no longer be changed by the profile edit, by anyone. A business with one Super Admin is fully supported (owner decision): the Super Admin's own lost handset is recovered ONLY by the owner's emergency VPS/database procedure, which starts with a verified database backup; nothing in the app lets one person move a Super Admin's phone. (If more than one Super Admin ever exists, a recovery needs two different verified ones: one requests, the other approves.) No second Super Admin is needed for normal operation. Never share a Super Admin login between people. After a recovery the holder signs in with a code sent to the new number and confirms it again | owner | docs/runbooks/privileged-phone-recovery.md |
| 1 | HSN/SAC and GST rate for each sold product, confirmed by the CA (the sample "6109 at 5 %" is not an approved configuration). One authorized, verified person enters the value, checks it against the supplier's GST invoice and approves it with a written basis in one step (Save & approve now on the Product screen; ADR 0026) (what they checked it against). An entry saved from a login before its holder confirmed a number is never adopted by saving it again: an approver withdraws it and the person who checked the values enters them again. The two sample rows must first be withdrawn by an approver (a setting that already started re-opens no earlier window) and entered again at their original dates | CA → staff enter, accountant approves | set on the Product screen of the admin app and approved there. The accounting portal approves only a setting whose dates overlap no approved one (a first setting, or a sample row entered again at its dates); a new rate that replaces an approved setting is approved on the Product screen, which ends the earlier setting the day before, so whoever approves it needs a store login that may approve there (a store Super Admin, or a store admin holding an Accounts Admin or GST Accountant grant). Readiness flags self-approvals |
| 2 | Record the CA's letter (optional since ADR 0026): the approval by a verified person on a written basis is what the engine uses; a verification record (owner / chartered accountant / tax adviser) adds the letter. A configuration approved before migration 104 is never usable: until it is withdrawn and approved again the engine holds every order for that product | owner or GST accountant | Settings → Tax verification and GST decisions |
| 3 | The ten GST decisions, each with its written basis: reverse charge, invoice date and timing, credit/debit notes, part-refunds, e-invoicing (IRN and QR) - whether it applies, signature, business/consumer, CGST-SGST/IGST, delivery and platform fees, rounding. An answer the system cannot carry out (for example "e-invoicing applies") may be recorded; it keeps invoicing stopped until the step exists | owner or GST accountant, on the CA's advice | Settings → Tax verification and GST decisions |
| 4 | Whether the document may ever be sent to a customer (it needs a signature or an e-invoice reference first?) | CA | none: customer access stays off |
| 5 | Seller legal name, registered address, GSTIN, SAVED; optional PAN (must match the GSTIN), phone, e-mail | accounts admin | Settings → Company profile (pre-filled from the verified company record: check it, then Save) |
| 6 | An active invoice series for the current financial year; the standard format is always exactly 16 characters | accounts admin | Settings → Invoice series |
| 7 | Exclusions for test orders that must never be invoiced - including any paid in the last 72 hours. An owner-funded pre-launch order that real gateway money paid for is first labelled and its financial treatment recorded on the CA's advice (see The pre-launch orders below); only then can it be marked never-invoice | owner | Sales Invoices → Needs attention → Historical orders (Check orders before marking them, Pre-launch test orders, then mark) |
B2C only, and the printed invoice in the parcel (owner decision)¶
- Consumers only. AIM STORE sells its own products directly to consumers, so every sale is B2C. No customer screen has a GSTIN field; the order, checkout-intent and profile APIs refuse a request that carries one (400
BUYER_GSTIN_NOT_SUPPORTED); the database refuses to record a buyer GSTIN on an order (migration 113); and the issuer holds any order that somehow carries one, with the reason, instead of issuing a business invoice. Existing orders and issued invoices are not rewritten. - Decision 7 ("Business and consumer sales") now offers All AIM STORE customer sales are B2C; buyer GSTIN billing is not supported. It is recorded by the owner or the GST accountant with a written basis, like the other nine - nothing records it for them. The older answer stays on file for history but no longer lets invoices issue.
- Prices include GST. The invoice engine already treats the price paid as GST-inclusive and takes each line's HSN and rate from its approved, verified product setting; an order whose product has no usable setting is held, never issued on a guessed rate. CGST+SGST versus IGST follows the recorded place of supply.
- Invoice before dispatch. While issuance is ON, an order the issuer will invoice (paid, inside the 72-hour window, not excluded, not on a compliance hold) cannot be set to shipped or delivered, or given a tracking number, until its GST invoice is issued and its document is stored (409
INVOICE_REQUIRED_BEFORE_DISPATCH); if that cannot be checked the move is refused (503), never allowed. With issuance OFF nothing changes. Orders outside the automatic window and orders on a compliance hold are not blocked (they are never invoiced automatically, so waiting would deadlock them). A different, legally compliant exception needs the accountant's written ruling and is not built. - Printing. Authorised accounting staff open the invoice on Sales Invoices -> the invoice and use View, Print (prints the stored PDF) or Download; each is written to the audit log. Match the printout to the parcel by the order number shown on the invoice. The system never records an invoice as "printed": nobody can confirm that from a database.
- Customers see no invoice in the app, the website, any customer API or any message; customer invoice access stays OFF.
The pre-launch orders (compliance hold)¶
The owner's internal real-payment orders (migration 111) are labelled owner-funded pre-launch test in Pre-launch test orders. A live label is a compliance hold: the order leaves the awaiting queues and no path invoices it - the automatic trigger, the recovery sweep, a retry, a manual issue, an approved backfill - until an authorised person revokes the label. The hold is scoped to the labelled order ids only; a genuine customer order, present or future, is never affected. A label is not a never-invoice exclusion and is not proof of any GST treatment: the order keeps its payment, its status and its history. What happens to each order is the CA's decision, recorded once in the same panel (the financial treatment); only after that can an order with a gateway payment be marked never-invoice (owner / Super Admin), or its label revoked so it can be considered like any other historical order (which still needs a backfill approval). Nothing is refunded, cancelled, reversed or deleted by any of this.
Choosing the series. Create the standard format: AIM/26A/00000001 - prefix AIM, the year's last two digits and the
series letter A, then eight digits (every digit that fits in the 16 characters). One series holds 99,999,999 numbers and a
financial year can hold 26 of them (2,599,999,974 in all for a three-letter prefix; a one-letter prefix gives 259,999,999,974).
With automatic rollover on (the default), the moment a series issues its last number the next letter opens and takes over in the
same transaction, and the first invoice dated in a new financial year opens its own series: nobody has to create anything on
1 April. The capacity is finite and the screen says so: if the last letter ever fills, orders are held with the reason, readiness
blocks and nothing is reused or squeezed in. The legacy format (AIM/2026-27/0001: 4 digits, 9,999 a year, one series a year,
no rollover) is still creatable for a prefix that already uses it; do not choose it for a new series.
2. Configure, in this order¶
- Company profile / GST (accounts admin). Check the pre-filled legal name, registered address and GSTIN against the GST registration and Save. Optional: PAN, phone, e-mail - they print only if saved. Saving refuses a malformed GSTIN, a PAN that is not the one inside the GSTIN, a malformed contact, or a state that contradicts the GSTIN. Readiness blocks until the identity is saved, not merely pre-filled.
- Tax configuration (CA's values). A staff member who has confirmed their mobile number enters them on the Product screen (with the supplier invoice number and date, if they have it); the entry waits for approval at once - there is no draft step there - and only the person who entered it can change it. A different verified person approves each one with a written basis: the GST accountant or an Accounts Admin, in the portal when no approved setting overlaps its dates (§1, row 1) or on the Product screen with a store login that may approve there; the owner can approve only from a store Super Admin login on the Product screen (the portal's owner role has no Approve). Nobody approves their own entry, the Super Admin included, and an entry last changed by a login whose holder has not confirmed their number cannot be approved, and saving it again does not fix that: an approver withdraws it and the person who checked the values enters them again (the Product screen offers no Approve until then). The two sample rows (Hoodie, Evoque) are withdrawn by an approver first (on the Product screen; any verification on them goes with them) and entered again at the same dates. One approved record per sold product, effective from a date on or before the earliest order you want invoiced.
- Tax verification (owner or GST accountant — not the person who approved it). Verify each approved configuration, choosing who verified it and giving the written basis. A verification belongs to the approval it confirms: a setting withdrawn and approved again is verified again.
- GST decisions (owner or GST accountant). Record all ten, with the basis - and read what the system does for each before choosing.
- Invoice series (accounts admin). Create the current year's standard series with rollover on; read the first number and the capacity before confirming.
- Exclusions (owner or super admin only). Paste the test orders' numbers into Check orders before marking them, read each finding (status, amount, any gateway payment, any invoice), then mark the ones that are test orders never invoice with a reason. Do this for recent ones too: when issuance is switched on, the recovery sweep invoices every paid order created in the previous 72 hours that is not excluded. It disappears from every "awaiting invoice" queue and count and can never be invoiced; lifting it later leaves history.
3. Readiness must show nothing blocking but the switches¶
Open Sales Invoices → Readiness. Every check reads PASS, WARNING or BLOCKING, and What has to happen next lists each open item by who has to do it. Every BLOCKING check must be resolved except the two switches
(Deployment switch, Issuance switch in accounting settings), which are the activation itself. Warnings
(PAN, contact, self-verified configurations, paid orders older than the automatic window, a legacy series, rollover off) are read and either fixed
or consciously accepted by the owner. The journal engine reads off and customerAccessEnabled reads Off.
Also confirm, read-only: the invoice-number reconciliation report shows no series issued from (nothing issued yet), and the payment-to-invoice reconciliation report lists the only exceptions you expect (historical paid orders with no invoice — never invoiced automatically).
4. Enable (owner authorises; engineering runs it)¶
- The owner records the go-ahead in writing (CA confirmations from §1 attached).
- The owner creates the readiness marker the enable workflow demands on the server (
.step8b-approved). - Dispatch production-issuance-flag with action = enable and the exact phrase
ENABLE STATUTORY INVOICE ISSUANCE. It moves the deployment flag and the settings gate together, leavesACCOUNTING_ENABLEDuntouched, recreates the API, and reports both gates. The journal engine stays off. - Do not dispatch
production-accounting-smoke(it writes to production) and do not create "test" orders.
5. Watch the first real invoice¶
From the first paid order after the switch:
- Sales Invoices → Issued shows it within seconds with number
AIM/26A/00000001, status issued, PDF stored, reconciliation matched. - Open the detail: the A4 PDF, its SHA-256 and checksum verified, and the audit trail (
CREATEby System (Auto)). - Settings → Invoice series shows series A with
1issued and the next numberAIM/26A/00000002. - Invoice-number reconciliation: status ok, 1 issued, next number 2.
- Payment-to-invoice reconciliation: no exception for that order.
- Needs attention is empty; the
InvoiceSweepBacklogalert (paid orders older than 30 minutes with no invoice) is silent.
Repeat the check after the first ten invoices and at the end of the first day. The owner compares one invoice's figures with the order and the payment by hand.
6. Daily operation¶
| Check | Healthy | If not |
|---|---|---|
| Needs attention queue | empty, or only orders inside the 72-hour sweep window | read the reason; fix the cause (series, verification, GST decision, seller details); Retry (writers, reason required) |
| Invoice series (Settings) | active series with room; rollover On | a series near capacity with no automatic successor, a series on its last letter (Z), or rollover off are warnings to act on before the series fills; a full series with no successor holds every order |
| Invoice-number reconciliation | every series ok | status gaps, duplicates or counter_behind is an incident: switch issuance off (§7), do not edit anything, call engineering |
| Payment-to-invoice reconciliation | no exceptions | amount_mismatch / payment_not_confirmed: investigate the order; an issued invoice is never edited |
| Document integrity | no missing, no checksum mismatch | a missing document: open the invoice and Write missing document; a checksum mismatch is an incident |
| Readiness | nothing BLOCKING (switches on); record protection all Protected | any BLOCKING line, or a protection that reads Not protected, stops invoicing: act on it before anything else |
| Reconciliation list | no payment_amount_mismatch |
investigate |
Each financial year (before 1 April): read the GST decisions again - the e-invoicing decision is to be re-confirmed every year, on the turnover figure and threshold in force. A sale placed in March and issued after midnight on 1 April is not moved silently into the new year: it is held with the reason, and what such a sale is dated is a decision for the CA.
CA exports (invoice register, HSN summary, GST summary, GSTR-1 draft, number and payment reconciliation) are CSV, or XLSX from the portal; every download is audited. They are drafts for the CA: nothing is filed from the system.
7. Rollback and recovery¶
Stop issuing (any time, takes effect within one request). Dispatch production-issuance-flag with action = disable. The settings gate closes first (read on every request), then the deployment flag is aligned. Invoices already issued stay (they are immutable); paid orders that arrive while it is off wait in the queue and are issued by the recovery sweep after re-enabling if they are less than 72 hours old, otherwise only by an approved backfill.
A wrong tax rate or amount on an issued invoice. Never edit it. Issue a credit note for the order (its number is allocated at issue from the year's credit-note series). A replacement invoice for the same order is outside this change (one sales invoice per order); agree the procedure with the CA first.
A rate that turns out to be wrong before it is used. Withdraw its verification (Settings → Tax verification and GST decisions, with a reason): the orders for that product are held for tax review again, with no number used.
A GST decision that changes. Record the new answer (the old one stays as history). If the new answer is one the system cannot carry out, invoicing stops by itself until it is corrected or the step is built.
A gap or repeat in the numbers. Switch issuance off, take a database snapshot, and treat it as an incident: numbers are never re-used and never back-filled by hand.
A series that filled and could not hand over (rollover off, or the last letter). Orders wait without an invoice, nothing is mis-numbered, and the missed-invoice alarm fires. If the full series is still active with rollover off, switch rollover on: the next issue closes it and opens the next letter. If every letter is used, deactivate the full series and create a series with a different prefix for the rest of the year (a full series that was switched off is never reopened, and its prefix gets no further letter that year). Orders from the last 72 hours then complete with the sweep's next pass; older ones are invoiced only by an owner-approved backfill.
A sale from an earlier financial year. A paid order placed before 1 April that has no invoice after midnight is held, not dated into the new year: the queue shows it as a financial-year hold and readiness counts it. Nothing in the system invoices it today; ask the company's chartered accountant how it is to be invoiced (mark it never-invoice only if it is not a real sale).
A stored document that fails its checksum. The portal refuses to serve it (500, audited as Critical). Restore the row from the
latest backup; EnsureInvoiceDocument only ever adds a missing document, it never replaces one.
Historical orders (only on the owner's explicit decision). 1. The owner marks test orders as excluded (§2.6). 2. The owner creates a backfill approval (Needs attention → Historical orders): an order-date range, a maximum number of orders, an expiry of at most 30 days, a reason. 3. A GST accountant or accounts admin — not the person who approved, by verified mobile number, whatever login they use — previews, then runs the backfill with that approval (the list shows which approvals are usable by you). Invoicing a single old order by hand (Retry, or the manual issue action) is the same thing and needs the same approval. An approval given before identity verification existed cannot be used; ask for a new one. The run touches only orders inside the scope, never more than the remaining cap, never an excluded order. 4. The owner can revoke the approval at any time.
Rolling the schema back. scripts/postgres/rollback/rollback_105.sql, rollback_104.sql, rollback_103.sql, rollback_102.sql, rollback_101.sql,
rollback_100.sql, rollback_099.sql and rollback_098.sql are compensating scripts (apply them newest first), never applied automatically; each says what it
destroys. rollback_104 is a weakening back to the account-only rules (ADR 0025), and it is paired only with redeploying the
previous backend image - redeploy that image first, then run the script: a backend built with migration 104 reads its tables and
columns on every portal page (/auth/me), the tax list, readiness and the Product screen, and fails without them. Export first, whole:
accounting.principals and accounting.principal_bindings (the record of who proved which number) and
accounting.product_tax_configs, accounting.invoice_backfill_approvals and accounting.product_tax_verifications (the maker,
approver and verifier principals, the written approval bases and the supplier-invoice context that the script drops; nothing re-links
them). Applying 104 again later does not bring any of it back: every approved configuration returns as approved under the old rule
(unusable until it is withdrawn, entered again, approved and verified), every verification and backfill approval without its verified
person (neither counts any more; the owner gives new approvals), and every login unbound (everyone confirms their number again). After rollback_104, verify with production-accounting-verify and release = scalable-numbering: the default, verified-identity, fails once migration 104 is no longer tracked (the script deletes its tracking row), and its message says so. Once invoices, credit notes, exclusions, approvals, verifications or GST decisions exist, export them first. rollback_101
refuses while any standard-format series has issued numbers. Do not roll the application back below migration 101 once a standard series exists: the previous backend would
number from a standard series' counter in the old PREFIX/FY/serial format. Switch issuance off and roll forward, or restore from backup.
rollback_105 drops accounting.privileged_phone_recoveries (the audit evidence of who moved a privileged login's phone): export it first and run it before rollback_104. Redeploy the previous backend image first; that image has the open phone edit migration 105's backend closed, so after it any admin can again change another admin's phone. Do not stay on it longer than needed. See docs/runbooks/privileged-phone-recovery.md.
8. What must never be done¶
- Switch on
ACCOUNTING_JOURNAL_ENGINE_ENABLEDas part of this activation (GST journals are a separate, later decision). - Enable any customer-facing invoice link, e-mail or download.
- Delete or update rows in
invoices,invoice_snapshots,invoice_documents,invoice_series,note_series,product_tax_verificationsorgst_policy_decisionsby hand (the database refuses; the replica-role bypass exists for test fixtures only). - Edit a series counter, rename a series or "fix" a gap by creating a number by hand.
- Record a GST decision, or verify a rate, without the written advice it rests on - or on a guess, to get the readiness page green.
- Run a backfill without an approval, or with an approval you gave yourself — from any login; the system refuses the same verified person and records the attempt.
- Bind someone else's mobile number to your login, or confirm a code that was sent to a number that is not yours: the number IS the person the system sees.
- Insert, withdraw or edit a principal or an identity binding (
accounting.principals,accounting.principal_bindings) by hand: a binding is made only by its holder's own confirmed code, and ends only by a Super Admin's withdrawal from the screens or when the login changes hands (a password reset or reassignment, a change of a store login's phone on file, its deletion), each recorded. - Put an order number, an amount, a customer detail or a PDF into this repository or this documentation.