PRD: Tax identity & groups
| Module | Tax & Invoice | PRD ID | PRD-TAX-001 |
| Status | Ready to dev | FEAT | TAX |
| Epic | — | Plane | BANA-1522 |
| Date | 2026-05-31 | Version | v1.0 |
| Packages | @nx/taxation | URD | TAX |
| Surface | Client · Owner/Mgr | ||
| Owner | Phát Nguyễn | ||
TL;DR
The tax foundation every issued e-invoice stands on: a merchant registers a valid Vietnamese tax identity (MST), reusable tax groups classify which tax applies to which products, and an invoice profile links it to a provider. Tax flows onto matching products automatically and stays reconciled as the catalog changes - so the merchant is tax-correct before the first invoice is ever issued.
1. Context & Problem
Selling in Vietnam takes three things before any invoice can issue: a valid MST printed on every invoice, the correct tax rule on every product, and a provider-backed invoice profile to issue against. None of it exists today as a coherent layer - tax data lives in ad-hoc fields, products carry no tax classification, and there is no invoice profile to connect a provider. So the issuance lifecycle has nothing to stand on: no seller to print, no per-product tax to compute, no profile to issue against.
This increment builds that foundation. Taxation owns the seller tax identity, Vietnamese administrative reference data, and the reusable tax groups that provision tax onto matching products. Invoicing owns the merchant invoice profile and provider configuration, kept in sync with the seller tax identity via change-data-capture (CDC).
2. Goals & Non-Goals
Goals
- Register the seller tax identity (MST, business name, address) and make it the seller printed on issued invoices.
- Expose Vietnamese administrative reference data (provinces, wards, units) for address entry, plus tax-code resolution and format validation.
- Define reusable tax-group rule templates that classify which tax applies to which products, and provision that tax onto matching products.
- Reconcile applied tax automatically when a product is created, updated, or removed (event-driven CDC seam between taxation and commerce).
- Create the merchant invoice profile linked to the seller tax identity, with provider configuration, kept in sync via merchant CDC.
Non-Goals
- The authoritative tax-code registry (owned by the tax authority).
- Tax-rate calculation at sale time (owned by pricing).
- The full invoice issuance lifecycle, retries, tax-authority (CQT) submission, and audit trail - owned by Invoice Lifecycle (
INV). - Invoice request / buyer self-service claim and issuance modes (
REQ/MODfeatures). - The later
CFGrequirements (per-type serial / policy, channel routing, retry policy, profile sharing, onboarding wizard).
3. Success Metrics
| Metric | Target / signal |
|---|---|
| Tax-identity coverage | 100% of merchants that issue invoices have a registered tax code + business name + address |
| Address validity | Province / ward / unit selections resolve against VN reference data; tax codes pass format validation before save |
| Provisioning correctness | Products matched by a tax group carry the correct applied tax; zero matched products left unprovisioned |
| Reconciliation lag | Applied tax reconciles within the CDC seam window after a product create / update / remove |
| Profile readiness | Merchants with a tax identity also have an invoice profile in sync before issuance is attempted |
4. Personas & Use Cases
| Persona | Goal |
|---|---|
| Owner | Register the merchant's tax identity, define tax groups, connect the invoice profile/provider |
| Manager | Maintain tax groups and review which products carry which tax |
| Product staff | Create / edit products and trust that the correct tax is applied automatically |
Core scenario: register the seller tax identity (with VN address lookups) → define a tax group → it provisions tax onto matching products → product changes reconcile the applied tax automatically → the invoice profile, linked to the tax identity, connects to a provider and stays in sync.
5. User Stories
- As an owner, I want to register the merchant's tax identity (MST, name, address), so it prints as the seller on every issued invoice.
- As an owner, I want VN province / ward / unit lookups when entering an address, so the tax identity carries valid administrative data.
- As an owner, I want a tax code validated for correct Vietnamese format before it is accepted, so a malformed tax code never reaches an invoice.
- As a manager, I want to define a reusable tax-group template, so the correct tax is classified and applied to the right products.
- As product staff, I want tax provisioned automatically when I create or update a product, so I don't set tax by hand on every item.
- As a manager, I want applied tax to reconcile when a product changes or is removed, so tax never drifts out of sync with the catalog.
- As an owner, I want a merchant invoice profile linked to my tax identity and a provider, so the merchant is ready to issue invoices.
6. Functional Requirements
| # | Requirement | URD ref |
|---|---|---|
| FR-1 | Register the seller tax identity (MST, business name, address) used as the seller on issued invoices | URD-TAX-001 |
| FR-2 | Look up Vietnamese provinces, wards, and administrative units when entering addresses | URD-TAX-002 |
| FR-3 | Validate the tax code for correct Vietnamese format before it is accepted; resolve VN address and sync tax info | URD-TAX-003 |
| FR-4 | Define a tax-group rule template that classifies which tax applies to which products | URD-GRP-001 |
| FR-5 | Applying a tax group provisions the correct tax onto its matching products | URD-GRP-002 |
| FR-6 | Changing or removing a product reconciles its applied tax automatically (CDC seam, taxation ⇄ commerce) | URD-GRP-003 |
| FR-7 | A tax group is usable only when compatible with the merchant's tax method | URD-GRP-004 |
| FR-8 | Create a merchant invoice profile linked to the seller tax identity | URD-CFG-001 |
| FR-9 | Connect a provider (VNPAY) with credentials stored encrypted; keep the profile in sync with tax info via merchant CDC | URD-CFG-002 |
Full requirement text and acceptance criteria live in the Tax & Invoice URD. This PRD references them rather than restating them.
7. Non-Functional Requirements
| Area | Requirement |
|---|---|
| Data integrity | The merchant tax identity is authoritative; the invoice profile is kept consistent with it via merchant CDC - no divergence between the seller printed and the registered tax code |
| Tenancy & authz | All operations confined to the user's own merchant; tax-identity and provider setup are owner-gated |
| Consistency | Tax provisioning and reconciliation are CDC-driven and idempotent - replays converge on the same applied tax |
| Security | Provider credentials on the invoice profile are stored encrypted |
| Performance | VN administrative reference data resolves fast enough for live address entry |
| i18n | User-facing labels are bilingual (English / Vietnamese); administrative data follows VN naming |
8. UX & Flows
Key screens (management app): the tax-identity setup with VN address pickers, the tax-group editor, the per-product tax view, and the invoice-profile / provider connection form.
9. Data & Domain
| Entity | Role |
|---|---|
| Seller tax identity | The seller tax identity (MST, business name, address) - related from the merchant, authoritative |
| Tax group | A reusable rule template classifying which tax applies to which products |
| Applied-tax row | The applied-tax entry linking a tax group to its matching products |
| Merchant tax method | The merchant's tax method that a tax group must be compatible with |
| Product tax group | The tax group provisioned onto a product |
| Merchant invoice profile | The merchant's invoicing setup linking the tax identity to a provider |
| Provider configuration | The connected provider (VNPAY) with encrypted credentials |
Conceptual only - full schema and invariants in the taxation domain model and invoice domain model.
10. Dependencies & Assumptions
Depends on
- Commerce / Merchant - the merchant record carries the tax identity entered by the owner.
- Products (Products) - tax groups provision tax onto products; product changes drive reconciliation.
- CDC seam - the event-driven seam that propagates product and merchant changes into taxation and invoice.
- Invoicing capability - for the merchant invoice profile and provider configuration.
Assumptions
- The merchant has entered a tax identity before issuance is attempted.
- A tax method is set on the merchant so tax-group compatibility can be evaluated.
- A supported provider (VNPAY) is available to connect.
11. Risks & Open Questions
| Risk / question | Mitigation / status |
|---|---|
| Tax identity and invoice profile could diverge | Profile kept in sync with the merchant tax identity via merchant CDC |
| Applied tax drifts as the catalog changes | CDC seam reconciles tax on every product create / update / remove; idempotent so replays converge |
| Tax group incompatible with the merchant's tax method | Compatibility is enforced before a group is usable |
| Malformed tax code reaching an invoice | The tax code is format-validated before it is accepted |
| Provider credential exposure | Credentials stored encrypted on the profile |
12. Release Plan & Launch Criteria
| Aspect | Plan |
|---|---|
| Phase | P1 (foundation) - see URD feature catalog |
| Rollout | All merchants; no feature flag |
| Migration | Tax group / item migrated into the tax schema; taxation runs as a dependent service |
| Launch criteria | Tax identity registers with VN address + validation; tax group provisions tax onto matching products; product change reconciles applied tax; invoice profile created and in sync with the tax identity |
| Monitoring | Provisioning / reconciliation success rate, CDC lag, tax-identity coverage, profile-sync consistency |
13. FAQ
Where does the merchant's tax identity come from? The owner enters it on the merchant; it is the authoritative seller printed on issued invoices and is mirrored into the invoice profile via merchant CDC.
Do I set tax on each product by hand? No - a tax group provisions the correct tax onto its matching products automatically, and reconciles when a product changes or is removed.
What happens when I edit or delete a product? The CDC seam reconciles the applied tax automatically; you don't re-apply tax manually.
Can any tax group apply to any merchant? No - a tax group is usable only when compatible with the merchant's tax method.
Does this issue invoices? No - this is the tax-identity, tax-group, and invoice-profile foundation. The issuance lifecycle (queue, retries, CQT submission, audit trail) is owned by Invoice Lifecycle.
References
- URD: Tax & Invoice - Tax Identity · Tax Groups · Invoice Configuration
- Related PRD: Invoice Lifecycle & Issuance · E-invoice Provider Integration
- Module: Tax & Invoice - URD
- Developer: @nx/taxation · domain model · @nx/invoice