0020 — Product GST/HSN classification and beginner-friendly tax setup¶
Status: accepted (2026-10-07). Builds on ADR 0019 (automatic internal sales invoices) and accounting.product_tax_configs (migration 038). Touches no customer-facing surface, no checkout, no price and no invoice.
Context¶
ADR 0019 made every paid order generate an internal GST invoice — but only
for products that have an approved HSN/SAC + GST rate in
accounting.product_tax_configs. Anything else fails closed: the invoice is
held (pending_tax_review), never guessed. In production every product,
including the live "Hoodie", has no such configuration, so every paid order is
held and the invoice feature cannot be switched on.
The configuration could only be created through the accounting-role API
(POST /accounting/tax-configs, then submit, then approve). That API has no
screen in either portal, so a non-technical store admin — who is not expected to
know HSN codes — had no way to supply the data while adding or editing a
product.
Decision¶
Add a "GST & HSN Details" section to the existing Admin Product Add/Edit dialog, backed by the existing authoritative store, with a classification master that supplies recommendations only — and never a guess.
- Tax category is not store category.
shop_items.category_id(storefront navigation) is untouched. Tax classification is a separate, admin-only concept: Product Tax Category (e.g. Clothing & Apparel) → Product Type (e.g. Hoodie). - Classification master —
accounting.tax_classifications(migration 097). 17 tax categories / 94 product types, taxonomy only. Every seeded row isneeds_reviewand carries no HSN/SAC and no rate: the repository contains no authoritative HSN/GST dataset, and inventing one would put wrong statutory data on invoices. A category never implies a code (Clothing & Apparel is not "one clothing HSN"); the admin picks a specific product type. - The database enforces "no tax guessing", not just the UI.
ck_tax_classification_no_guessallows a recommended code/rate only on averifiedrow, andverifiedrequires a well-formed 4/6/8-digit code, a supported rate and a non-emptysource_reference(who/what verified it). Aneeds_reviewrow cannot hold a value. A migration test pins the seed to taxonomy-only columns. - Adding a verified mapping later is data-only (no deploy): update the row
to
verifiedwith the code, rate andsource_reference, e.g. an accountant's letter. A verified row is served only inside itseffective_from/towindow. attribute_prompts(JSON) lets a product type say "the right code can depend on fabric, knitted/woven, value per piece…". It is informational today (shown as "your accountant may ask about…") and leaves room for real attribute-driven rules later without a schema change.- One source of truth for invoices — unchanged. The section writes
accounting.product_tax_configs, the exact rowsservice.IssueInvoicealready resolves by the order's IST date. Nothing is written toorder_items, no order is touched, and no invoice code changed. Migration 097 adds provenance columns to the same table (tax_category,product_type,config_source, the recommendation shown,updated_by). - Source tracking, computed on the server.
config_sourceisRECOMMENDED(identical to a verified recommendation),MANUAL(no verified recommendation existed) orMANUAL_OVERRIDE(a verified recommendation existed and the admin saved something else). The client's claim is never trusted. A manual or overridden value requires an explicit confirmation that it was checked with the accountant/supplier. - Approval semantics are preserved, not bypassed. (Superseded on one point by
ADR 0025: since migration 104 a save NEVER approves — the person who enters the
values never approves them, whatever role they hold, and a different verified
person approves with a written basis. Every save from this screen is a proposal
awaiting approval at once (there is no draft step here), and only the person who
entered it changes it. The paragraph below describes the behaviour before that
change.) The table already has a
maker/checker workflow (
draft → pending_approval → approved) with approversaccounts_adminandgst_accountant. A save through the Product screen was approved in the same audited transaction only when the caller could approve — a Super Admin (the existingusers.is_super_adminauthority bit) or a user holding anaccounts_admin/gst_accountantrole grant. Any other admin's save becomespending_approval, and the screen says so ("Awaiting approval — invoices cannot use it yet"). Approvers get an Approve button in the same section. So nothing ever looks saved in Admin while remaining unusable without explanation. - An approval is bound to what the approver saw. Approve and Withdraw carry
the setting's id and the HSN/SAC, rate and effective date on screen (since
ADR 0025 also its end date,
effective_to: absent, empty or null for none); under the row lock the server refuses (409) if the row no longer holds exactly those values. Without this, another admin editing the same pending row between the approver's click and the request would get unreviewed values approved. The APPROVE audit row records the approved values, not just the status. - A missing rate is refused, never defaulted.
gst_rate_bpsis required; 0 is a real GST rate and an omitted/nullvalue must not become it. - Effective dates, never silent back-application. A new setting's form defaults "Effective from" to today (IST); a setting that is already saved shows its own saved date (see the amendment below). Invoices use the setting in effect on the order's date, so an order placed before the effective date does not use it. To cover orders already waiting, the admin picks an earlier date on purpose — the screen offers "use the earliest waiting order's date" (only while no approved setting exists — approved settings are never back-dated) and says how many paid orders are waiting. Approved rows are history: they are never edited; a change is a new row, and the previous window is closed the day before (audited). A window that would overlap a later approved one is refused. A mistake in a future date is recoverable: an approved setting that has not started yet can have affected no order, so an approver may withdraw it (audited; the window it had closed is re-opened from the audit trail). A setting already in force is never withdrawn. (ADR 0025: except a setting approved under the old rule — before a second verified person had to approve — which an approver may withdraw after it started, provided no issued invoice rests on it, so that its values are entered again at the original dates under the rule. Every withdrawal also withdraws any live verification of the setting, each recorded in the audit trail.) A pending proposal that carries its own end date (created through the accounting API) is only approved where it overlaps nothing — it is never treated as open-ended, and never splits or truncates an approved window.
- The status is not the whole story, so the screen also says how many orders
still hold.
TAX_READYis measured at today, but each order is resolved at its own date. The state therefore reportsuncovered_order_count— paid, invoice-eligible, not-yet-invoiced orders containing this product that no approved setting (and no order-item tax snapshot) covers — shown even when the badge reads Tax Ready. A test pins that this count agrees with whatIssueInvoicethen does. - Product-level readiness.
TAX_READY(an approved configuration covers today),AWAITING_APPROVAL, orTAX_SETUP_REQUIRED. The Products list shows it as a badge and filter. A product without a ready configuration is never blocked from saving or selling — if it is sold, invoice generation simply HOLDs as it already does. - Issued invoices are immune. Invoices and their snapshots are immutable (ADR 0019 / migration 096); changing a product's tax configuration later affects only orders resolved afterwards. Tested end to end.
API (all under the existing /admin group, AdminOnly)¶
| Route | Purpose |
|---|---|
GET /admin/tax-classifications |
the master (+ can_approve for the caller) |
GET /admin/products/tax-status |
{productId: status} for the list badge/filter |
GET /admin/products/:id/tax-config |
readiness, in-force / pending / latest setting, history, waiting-order count. (ADR 0025: each setting also says whether the person who entered it confirmed their number (maker_confirmed), whether its last change was made by a verified person (editor_confirmed), and whether this caller may approve it now (can_approve_this, never while either is unconfirmed), so the screen offers no approval the server would refuse) |
PUT /admin/products/:id/tax-config |
Confirm & Save |
POST /admin/products/:id/tax-config/approve |
approve a pending setting — body carries the reviewed values (approvers only). (ADR 0025: also the end date effective_to and the written basis approval_basis; the approver is a verified person who neither entered nor last changed the setting, and the person who entered it and the one who last changed it must have confirmed their numbers — 409 IDENTITY_NOT_VERIFIED with field: "maker" / "editor" otherwise; once they have, saving the same values again from that login stamps their verified person on the setting) |
POST /admin/products/:id/tax-config/withdraw |
withdraw a proposal, or an approved setting that has not started (approvers only; same body, without the basis). (ADR 0025: or a setting approved under the old rule that no issued invoice rests on; any live verification of it is withdrawn with it) |
Everything is validated server-side (HSN 4/6/8 digits after stripping spaces,
dots and hyphens; rate ∈ the supported basis-point set; dates real and within
bounds). Every mutation writes its accounting.audit_log row in the same
transaction — previous and new HSN/rate, source, the recommendation on screen,
actor, role, IP and request id — and a failed audit write fails the mutation. If
the accounting schema/migration is absent the API answers 503 and nothing else
is affected. The tax fields are deliberately not part of
pgrepository.Product or any public product endpoint; an isolation test pins
that, and that checkout/payment/order code never references the tax store.
Consequences¶
- Deploying this changes nothing in production by itself. It adds a table, six nullable columns, six admin routes and a UI section. The accounting API's approve route now takes the same per-product advisory lock as the Product screen, so the two cannot race into overlapping approved windows. It enables no issuance, creates no invoice series, writes no HSN/rate, and changes no order, price or checkout total.
- The existing Hoodie remains "Tax Setup Required" until an admin enters the accountant/supplier-confirmed HSN/SAC and GST rate: Admin → Products → Hoodie → Edit → GST & HSN Details → Clothing & Apparel → Hoodie → enter the confirmed values → tick the confirmation → Confirm & Save. There is no verified recommendation for Hoodie, so none is offered.
- The four existing orders are not touched. After the setting is saved and
approved, the read-only readiness probe shows whether they moved from
TAX_HOLDtoTAX_READY— which depends on the effective date chosen. - GST rate set. The supported rates are those already in the invoice engine and the table CHECK (0, 0.25, 3, 5, 12, 18, 28 %). The screen offers exactly those and does not extend them. Whether the set still matches current law is an accountant's question and a separate change.
- Not built, deliberately: a UI to maintain the master (verified rows are added by SQL/migration for now), attribute-driven rules, bulk import, and an HSN lookup. Each is a separate decision.
Amendment — reopening a saved setting (2026-10-07)¶
Defect (production, Evoque). A setting saved as Electronics → Smart Watch /
Fitness Band, 91029990, 18 %, from 2026-10-05 reopened in Edit Product with an
empty Product Type and Effective from = today, while the banner beside it still
said "In use today … since 2026-10-05". Nothing was written, and pressing Save from that
state did not write a tax change either (an untouched form never sent one) — but the form
was wrong and unsafe to edit from, and the server would have accepted an identical re-save
dated today (or any later day) as a duplicate-valued version. The API was never at fault
about what it returns: it persists and returns
tax_category, product_type, effective_from and config_source verbatim
(verified against the real route table on a real Postgres, including with the database
and server clocks set to other time zones; the response shape is pinned by golden files).
Root causes, all in the screen.
- Product Type cleared. Seeding the form sets category and type in one commit,
which also mounts that category's type options. Radix Select mirrors every select
into a hidden native
<select>and, when its controlled value changes, fires achangefrom it. The options are registered one render later, so the event carries""— and the handler took""for "the admin cleared the type". - Effective from = today. The seeding logic deliberately dated an in-force setting "today" ("edited as a change"), conflating viewing the setting with creating a new version of it.
- Latent, hidden by 1. A hydrated Manual setting was
invalid(confirmation not ticked), which would have blocked saving the product itself.
Decisions.
- The form is a view of one saved row (the "baseline"): the approved setting in
force; else the proposal awaiting approval; else the approved setting that starts
soonest. Never
latest(it can be a withdrawn row) and never a colleague's proposal in place of the setting in force — that proposal stays in "Not active yet" with its own Approve / Withdraw. After Approve / Withdraw the form is re-seeded from the new state, so withdrawn values can never be re-submitted. - "Effective from" is automatic until the admin types one. The saved date while the form equals the saved setting; today for a setting that does not exist yet; and, once a value of an approved setting is changed, the later of today and the day after the newest approved start — stepping past a day another admin's proposal occupies, so a change never silently replaces it.
- Nothing to save ⇒ nothing is written. The form has an explicit
unchangedphase: no confirmation asked, never blocks saving the product, "Tax Ready" stays clear. On the server, a save whose HSN/SAC, rate, tax category and product type equal those of the approved setting already covering its date answersunchanged: trueand writes no row and no audit entry — on that setting's own start day, and, for an open-ended setting, on any later day (the same values from a later day change nothing for any order). A setting that has an end date only stands for the days it covers: a later day inside it takes the normal path (a covering version if it has simply lapsed; the existing refusal if a later approved setting exists). Previously it created a duplicate-valued version and closed the in-force window; and a different classification on the same day was silently dropped underunchanged: true. It is now a real change, refused like any other change to an approved row. (ADR 0025:) never for a setting approved under the old rule (before a second verified person had to approve): invoices cannot use it, so "unchanged" would be false. Its values saved at its own start day are refused (409) with the way out - an approver withdraws it, then the values are saved again at that day; at a later day they are an ordinary new proposal. - A change is never dated automatically while an approved setting has not started yet. The automatic date would start the new row the day after that setting and the server would close it the day before — leaving it live for exactly one day. The admin must either withdraw the scheduled setting or choose a date after it, and the screen names what the chosen date does to it ("The setting scheduled from … will then apply only until …"). The automatic date also steps past any day another row occupies (a colleague's proposal, a draft, a withdrawn row) so it never overwrites or resurrects one.
- Approved settings are never back-dated (the existing window rule: a new row must start after every approved one). The screen now says so before sending, and no longer offers "Also cover those orders" once an approved setting exists — it could only fail.
- A date-only change with identical values is a no-op, not a new version. This is the one reading of "changes … date and confirms" that avoids the duplicate version the owner also asked to prevent; the screen explains it.
- Radix's empty echo is not a choice. A value that is not one of the options on offer is ignored by all three selects. A saved category / type the master no longer lists is still shown, under its own key, rather than blanked.
- The Store category select in the same dialog gets the same guard (and nothing else
about it changes). It had the same latent echo: opening Edit before the page's category
list had loaded, or editing a product whose category is not in the list, made Radix report
"", which the handler read as "No category" — so an unrelated Save wrotecategory_id: ""and silently un-categorised the product. Tests:tests/product-store-category.test.tsx. - "Today" for a setting that does not exist yet is the day of the opening, not of the page load (the page keeps one dialog mounted for as long as the tab is open).
Tests that pin this. Real-Postgres: producttax_reload_db_test.go,
product_tax_reload_http_test.go (through the real route table, with golden JSON files
under internal/handler/testdata/), producttax_noop_save_db_test.go (the invoice
resolver and issued snapshots). Admin: lib/product-tax.test.ts, a contract test that
feeds the golden files through the screen's logic (lib/product-tax.contract.test.ts),
and DOM tests (vitest + jsdom, tests/product-tax-reload.test.tsx) that drive the real
dialog and Radix selects end to end, in both load orders and under React.StrictMode.
Known, deliberately left alone. A save by a non-approver on a day another admin's
proposal occupies still replaces that proposal (the screen now warns); Save has no
staleness check like Approve / Withdraw do. (The first point is closed by ADR 0025:
only the person who entered a proposal changes it in place; another account's save
that would change it is refused (409) and recorded as a denied audit row. A
withdrawn proposal is nobody's: whoever saves its date next reclaims it as its new
maker, and inherits nothing they did not enter — not its earlier end date (the
reclaimed entry is open-ended, or ends the day before an approved setting that already
starts later). The approval, not the save, carries the staleness check: Approve is
bound to the values the approver saw, the end date included.)