🧾 Money & Accounts

TDS / TCS

TDS/TCS Management handles Indian Tax Deducted at Source obligations that arise from your purchases and expenses — recording deductions, issuing Form 16A-style certificates to parties, filing quarterly returns, and configuring the section rates you deduct at.

📍 Menu path: Money & Accounts → TDS / TCS

👤 Who uses it: Managers/Owners with GST/tax access (India only)

🏷️ Plan tier: advanced+

Overview

This single page has four tabs reachable from the sidebar as separate sub-items (TDS Entries, Certificates, Quarterly Returns, TDS Types) which are really just query-string views of the same component: /tds-management?tab=transactions|certificates|returns|sections.

TDS transactions themselves are not created manually here — they are automatically recorded when you create purchases or expenses that fall under a configured TDS section; this page is for reviewing, certifying, and filing what has already been deducted.

The page is India-specific: if your store's configured country is not India, the entire page is replaced with a "Not available for your region" notice and none of the tabs load.

Before You Start

Requires the GST feature enabled at the Advanced plan tier or above.
Your store's country/region must be set to India (storeFmt.isIndia) — TDS/TCS is Indian tax law only.
TDS transactions only appear once purchases/expenses have been recorded against a configured TDS section — an empty store shows no data on the Transactions tab.

Step-by-Step Guide

1 Review and filter TDS transactions (TDS Entries tab)

Open the Transactions tab (menu item "TDS Entries", ?tab=transactions).
Filter by Status (Pending, Deposited, Filed, Completed) and/or a From/To date range.
Click Clear to reset all filters, or Refresh to re-fetch with the current filters.
Each row shows Transaction (number + date), Party (name + PAN), Section badge, Gross Amount, TDS Amount, Status badge, and an action to issue a certificate.
Use the Export button above the table to download the full filtered list (transaction type, number, date, financial year, quarter, party name/PAN/category, TDS section, gross amount, rate, TDS amount, net payable, status, certificate number/issued flag, challan number, deposited flag).

2 Issue and share a TDS certificate

On the Transactions tab, find a transaction with no certificate yet and click Issue Certificate.
The certificate is generated server-side and the row updates to show View and Download links instead.
Switch to the Certificates tab (menu item "Certificates", ?tab=certificates) to see every certificate issued so far, with summary tiles for Total Certificates, Total TDS Deducted, and Gross Amount.
Select one or more certificates using the row checkboxes (or the header checkbox to select all), then use Download Selected to save each one, or Email Selected to send them in bulk to the parties on file.
For a single certificate, use the row-level View, Download, or Send (email) actions instead of the bulk toolbar.

💡 Bulk download fetches each certificate file sequentially with a short delay between downloads to avoid overwhelming the browser.

3 Generate and file a quarterly TDS return

Open the Quarterly Returns tab (menu item "Quarterly Returns", ?tab=returns).
Choose the Financial Year from the dropdown (2023-24 through 2026-27).
For a quarter with no return yet, click Generate — this creates a draft return (Form 24Q) summarising TDS Deducted, Deductees and Transactions for that quarter.
For a DRAFT return, click File Return, then enter the Acknowledgment Number and, optionally, a Token in the prompts — the return status changes to Filed and records the filed date and acknowledgment number.
To discard a draft you generated by mistake, click Delete and confirm.
Click View Transactions on any quarter with transactions to jump straight to the filtered Transactions tab for that data.

4 Review TDS section rates (TDS Types tab)

Open the TDS Types tab (menu item "TDS Types", ?tab=sections).
Each card shows a TDS section code, its deduction rate percentage, a description, its threshold amount, category, and whether it is Active or Inactive.
This tab is read-only in this view — it is where you confirm which section a transaction was categorised under.

Every Field & Button, Explained

Field / Button	What it does
`Transactions tab / TDS Entries`	Filterable, exportable list of every TDS deduction recorded from purchases/expenses.
`Status filter`	Pending, Deposited, Filed, or Completed — narrows the transactions list.
`From / To date filters`	Restrict transactions to a transaction-date range.
`Issue Certificate`	Generates a certificate for a transaction that does not have one yet.
`Certificates tab`	Register of every issued certificate with bulk select, bulk download, and bulk email.
`Download Selected / Email Selected`	Bulk actions on the certificates tab, active only when at least one certificate checkbox is selected.
`View / Download / Send (row actions)`	Per-certificate actions: open in a new tab, save the file, or email it to the party.
`Quarterly Returns tab`	Per-quarter (Q1–Q4) cards showing TDS Deducted, Deductees, Transactions, due date, and filing status for the selected Financial Year.
`Generate (return)`	Creates a DRAFT Form 24Q return for a quarter that has no return yet.
`File Return`	Marks a DRAFT return as FILED after you supply the government Acknowledgment Number (required) and Token (optional).
`Delete (return)`	Removes a DRAFT return only — filed returns cannot be deleted from this screen.
`View Transactions (return card)`	Jumps to the Transactions tab pre-scoped to that quarter's data.
`TDS Types tab / TDS Sections`	Reference cards of each configured TDS section: rate %, description, threshold, category, active/inactive.

Tips & Best Practices

Issue certificates in a batch just before quarter-end so parties receive them promptly, then use Email Selected to send them all at once rather than one at a time.
Generate each quarter's return as soon as the quarter closes so any data issues surface early, well before the government filing deadline shown as the Due date.
Cross-check the TDS Types tab whenever a new kind of vendor payment starts attracting TDS, to confirm the section and rate being applied is correct.

Troubleshooting & FAQ

The whole page shows "Not available for your region".

TDS/TCS is India-specific tax law. This message appears whenever the store's configured country is not India — it is expected behaviour for non-Indian stores, not an error.

No TDS transactions appear even though I have made purchases.

TDS transactions are only created automatically when a purchase/expense matches a configured TDS section and crosses its threshold. Check the TDS Types tab to confirm the relevant section exists and is Active.

I cannot delete a return.

Only returns in DRAFT status can be deleted from this page. A FILED return has already been submitted to the government and cannot be deleted here.

Certificate download opens a blank or broken file.

Certificates are served from the backend at a stored file path; if the backend origin differs from the app's configured API base URL (e.g. local dev on a different port), the file link can 404. Confirm the backend is reachable at the same origin the app is using.

🧑‍💻 Developer Notes

Source component(s):

frontend-app/packages/pos-react-lib/src/pages/TDSManagement.jsx

Backend endpoints used:

GET /tds/tds/transactions
GET /tds/sections/tds
GET /tds/returns/summary
POST /tds/tds/transactions/:id/issue-certificate
POST /tds/tds/transactions/:id/send-certificate
POST /tds/tds/certificates/bulk-send
POST /tds/returns/generate
POST /tds/returns/:id/file
DELETE /tds/returns/:id

Related tables (db-core repositories):

TDSTransaction
TDSSection
TDSReturn

Redux slices:

react-router useSearchParams (tab= query param drives the active tab, no Redux slice)

Feature flag key: gst (requires advanced plan tier or above)

The four sidebar sub-items (TDS Entries, Certificates, Quarterly Returns, TDS Types) all route to the same /tds-management component with a different ?tab= value, synced via useSearchParams so the URL and active tab always match, including on browser back/forward. Certificate downloads fetch the file client-side as a Blob and trigger a synthetic <a download> click rather than navigating away. "File Return" and "Delete Return" reuse window.prompt/window.confirm instead of a modal.