Product Requirements Document (PRD): VAT/Tax Management Feature
(If you done reading click on read book icon whenever you see it)
Objective
Implement a VAT/Tax Management feature within the workspace settings, enabling Super admins and Admins to configure and manage various tax types applicable to their operations. This functionality aims to ensure accurate tax application across different countries and regions, enhancing compliance and financial accuracy.
Problem Statement
Currently, there is no centralized system within the workspace to manage and apply various taxes such as VAT, GST, or sales tax. This absence can lead to manual errors, non-compliance with regional tax laws, and inefficiencies in financial operations.
Are you align with problem statement then please click on. Done reading?
Solution: VAT/Tax Management Feature
Centralized configuration interface for managing multiple tax types. Support for different tax structures like VAT, GST, and custom tax types. Country-specific and region-specific (state-level) tax rates. Inclusive or exclusive tax application. Tax ID registration and visibility control. Location verification during purchase. Business verification for mismatched locations. Tax ID display on invoices. Exact tax title display on invoices. Goals & Objectives
Business Goals
Improve workflow efficiency by automating tax calculations. Ensure tax compliance across international and regional laws. Reduce dependency on manual tax configuration. User Goals
Easily define multiple tax types and manage regional variations. Enable automatic tax application based on country or state selection. Maintain accuracy in billing and invoicing processes. Are you enjoying reading?
User Stories
As a Superadmin/Admin, I want to create and manage taxes (like VAT or GST) from my workspace settings so I can apply them during billing. As a Superadmin/Admin, I want to set different tax rates for different countries (and even states) to make sure I'm charging the correct amount. As a Superadmin/Admin, I want to choose whether a tax is inclusive (included in the price) or exclusive (added on top) so I can match my pricing model. As a Superadmin/Admin, I want to assign multiple taxes to services or invoices for more accurate tax handling. As a Superadmin/Admin, I want any changes or deletions I make to tax settings to reflect in all future transactions automatically. As a customer, I want the system to verify my location during purchase to ensure accurate tax application. As a customer, if my location and billing address don't match, I want to confirm that I have a business at the billing address. As a customer, I want the invoices to display the tax ID if provided. As a customer, I want the invoice to display the tax title exactly as the admin created it. Done reading?
1. Workspace Tax Settings
A new VAT/Tax tab under Workspace Settings. By default, no tax entries exist. Delete a tax (with confirmation) 2. Adding a New Tax
When adding a tax, users can enter: Title (e.g. "Standard VAT", "Sales Tax", "Federal Tax") Home Country Tax % (optional — used when buyers are from the same country) Tax ID (optional, for compliance) Country-Specific Rates (Buyer country) Option to set tax % per country For countries with regional/state tax rules (e.g., US, Canada): State/Province Text Box: Users enter the state or province name as text. Zip/Postal Code Text Box: Users enter the zip or postal code as text. State/Province Tax %: Users enter the tax rate for the specified state/province. Each tax can be edited and deleted An option of active/Inactive inactive vat will not apply for new purchases. Validation Rules:
Maximum length enforced (e.g., 255 characters). Should not contain special characters that could cause system errors. Must be a valid country from a predefined list. Must be a valid numerical value. Must be within a reasonable range (e.g., 0 to 100). Must accept up to 4 decimal points. Maximum length enforced.(20 characters) Country: Required. Must be a valid country. Required for countries that have state/province taxes. an option for all other states Zip/Postal Code Text Box: Required for countries that have state/province taxes. Format validation based on the selected country (e.g., zip code format for the US, postal code format for Canada). Required for countries that have state/province taxes. Must be a valid numerical value. Must be within a reasonable range (e.g., 0 to 100). Must accept up to 4 decimal points. When applying taxes to services or invoices, the system should validate that the selected tax exists. When applying an exclusive tax, the system should validate that the base price is a valid numerical value. When applying an inclusive tax, the system should validate that the total price is a valid numerical value. Tax will be applicable based the buyer location. When deleting a tax, the system should provide a confirmation dialog to prevent accidental deletion. When updating a tax, the system should log the changes and the user who made them. When a state/province tax is updated, the system should log the changes and the user who made them. 3. Linking Taxes to Services
A default option stating "applying all taxes". When creating or editing a service, Superadmins/Admins must be able to link one or more created taxes to that service. A service can have multiple taxes linked to it. A list of created taxes will be available to select from during service creation/editing. Taxes are selected via a multiselect dropdown or similar UI element. 4. Applying Taxes
Once a tax is created and linked to a service, it will be applied automatically during the purchase of that service. Taxes can also be added manually to any Manual Invoice (Invoice). Each tax added includes a toggle for: Formula: Total = Base Price × (1 + Tax Rate) Example: $100 × (1 + 0.10) = $110 Formula: Base Price = Total / (1 + Tax Rate) Example: $100 / (1 + 0.10) = $90.91 (Tax = $9.09) Manual invoices support multiple taxes with mixed inclusive/exclusive types. 5. Tax Behavior Over Time
It won’t apply to future new purchases. Running subscriptions won’t be affected The new rate will apply to all future new purchases. While updating, show a prompt that existing subscriptions will not be impacted. 6. Location Verification During Purchase
When a user purchases from the catalog or is signed in, the system should attempt to determine their location using: User will provide the address by selecting the country if that country has state tax show those state name in dropdown have an option other upon selecting open a textbox For stripe account in india country, state, zip all fields are manadatory. The system should compare the user's determined location with the billing address provided during checkout. 7. Business Verification Checkbox
If the user's location and billing address do not match, a checkbox should be displayed: "I confirm that I have a business at the billing address." This checkbox must be selected for the purchase to proceed. 8. Invoice Tax Display
Invoices must display the Tax ID if it was provided during tax creation. Invoices must display the Tax Title exactly as it was entered by the admin 1. for coupon application once the coupon is applied tax will be counted on the discounted amount
2. for inclusive exclusive option in service
a. for applying all taxes/ multiple amount of taxes only one option for inclusive/exclusive
3. tax will be applicable in setup fee and add ons.
tax will be applied on the total amount When a tax is deleted it will be removed from ongoing subscription as well for manual invoice user will just select the tax name (select from all list) for manual tax rates it will be always exclusive For signed in users while trying to purchase user have to give the country/tax information if user/client has country/state etc on their profile show them prefilled and allow change if no info is on profile allow entry this entry will not update client profile Adding Tax in manual invoice:
While creating a manual invoice when client, order, is selected if client has country automatically filled based on the country and state automatically add the tax rates if manually any tax rates are added if country and states are not match value would be 0 when country/state is changed add the applicable tax rates if a tax rate is manually added/edited it needs to be manually removed, it will not change automatically Done reading?
Acceptance Criteria
Admins can create, edit, and delete taxes in workspace settings. System validates required fields: title, country, and (if needed) % rate. Country- and state-specific taxes can be added. Multiple taxes can be added to a service or invoice. Inclusive taxes don’t increase price; exclusive taxes do. Invoices clearly show tax breakdowns (name, %, amount, Tax ID if available). Deleted/updated taxes update automatically in future orders and renewals. Zero % tax can be applicable. Done reading?
Metrics & Event Tracking
1. Usage Metrics:
Number of tax entries created: (Feature adoption) Number of purchases/invoices with applied taxes: (Feature usage) 2. Error Metrics:
Number of invalid or failed tax configurations: (Configuration issues) Inconsistent tax rate applications: (Calculation errors) 3. Tracking in Datadog (or similar):
Tax creation success/failure: (Configuration health) Tax applied per transaction (amount): (Calculation verification)
Here is the list of countries along with specific states/provinces where additional VAT/GST/tax rules apply:
Countries with VAT/GST/Tax
Europe (EU & Non-EU)
AgencyHandy
