GST Ledgers API
GST ledgers are electronic records on the GST portal that track a taxpayer’s cash deposits, input tax credit (ITC), and return-related tax liabilities for a GSTIN. Use this API to fetch cash ledger, ITC ledger, and liability ledger data to reconcile payments and plan set-off.Key capabilities
Cash and ITC balance snapshot
Retrieves current cash and ITC balances for a GSTIN as of a specific month, including blocked ITC fields.
Cash ledger transactions
Fetches detailed cash ledger entries for a date range to reconcile deposits, payments, and debits against internal records.
ITC credit and utilisation
Accesses ITC ledger entries with transaction descriptions and reference numbers to track credit accruals and offsets.
Return liability breakdown
Views return-related liabilities and adjustments for a filing period to understand pending obligations before filing.
How it works
Generate OTP for taxpayer
Initiate OTP authentication for the GSTIN to begin the session.
Obtain taxpayer access token
Create an authenticated session to obtain a Taxpayer access token for the
Authorization header.Retrieve balance snapshot
Fetch current cash and ITC balances for the period.
Fetch cash ledger transactions
Pull cash ledger entries for a date range to reconcile deposits and debits.
Fetch ITC ledger transactions
Retrieve ITC ledger entries for a date range to track credits and utilisation.
Retrieve return liability ledger
Fetch return-related liabilities for the selected return period.
Recipes
Generate taxpayer session
Authenticate and obtain a Taxpayer access token for ledger API calls.
File GSTR-3B
Use ledger insights to prepare and file your GSTR-3B return.
Check return status
Verify return filing status and errors after submission.
Error handling
Handle API errors and validation failures gracefully.
API categories
Balance snapshot
Gets cash and ITC balances as on a specific month.
Electronic cash ledger
Detailed cash ledger transactions for a date range.
Electronic credit ledger
ITC credit and debit entries with reference details.
Return liability ledger
Return-related liabilities and adjustments by period.
API reference
All ledger APIs require:Authorizationheader with Taxpayer access tokenx-api-keyheader with your API key
Balance snapshot
| API | Path | Description |
|---|---|---|
| Cash + ITC Balance | GET /gst/compliance/tax-payer/ledgers/bal/{year}/{month} | Returns cash balance and ITC balance for the specified year and month. Includes blocked ITC fields if applicable. |
Electronic cash ledger
| API | Path | Description |
|---|---|---|
| Cash Ledger | GET /gst/compliance/tax-payer/ledgers/cash?from={DD/MM/YYYY}&to={DD/MM/YYYY} | Returns cash ledger entries for the date range. to date cannot be beyond the current date. |
Electronic credit ledger (ITC)
| API | Path | Description |
|---|---|---|
| ITC Ledger | GET /gst/compliance/tax-payer/ledgers/itc?from={DD/MM/YYYY}&to={DD/MM/YYYY} | Returns ITC credits and debits with descriptions and reference numbers. Both from and to are required. |
Return liability ledger
| API | Path | Description |
|---|---|---|
| Return Liability Ledger | GET /gst/compliance/tax-payer/ledgers/tax/{year}/{month}?from={DD/MM/YYYY}&to={DD/MM/YYYY} | Returns liabilities and adjustments for the return period. Combine with date range filters. |
Common use cases
Use GST Ledgers API when you need to:- Build a GST payment readiness dashboard that shows available cash and ITC balances against expected GSTR-3B liability before filing.
- Reconcile challan deposits with cash ledger debits against internal payment records for month-end closing and audits.
- Investigate balance discrepancies by pulling transaction-level ledger entries with descriptions and reference numbers.
- Validate payments posted on the GST portal before proceeding to file returns or when filing fails due to insufficient balance.
- Automate statutory audit evidence collection with ledger extracts for finance teams and monthly compliance reviews.
- Plan ITC utilisation strategy by analyzing available credit across CGST, SGST, and IGST heads before set-off.
FAQs
What is the GST Ledgers API?
What is the GST Ledgers API?
GST Ledgers API provides programmatic access to the electronic ledgers maintained on the GST portal for a GSTIN. The API returns cash ledger, ITC credit ledger, and return liability ledger data—the same information available on the GST portal under the “Electronic Ledger” section. Developers use this API to build dashboards, reconciliation tools, and filing-readiness checks.
What is the difference between Cash Ledger, ITC Ledger, and Return Liability Ledger?
What is the difference between Cash Ledger, ITC Ledger, and Return Liability Ledger?
Each ledger has a different purpose. Cash Ledger tracks cash deposits via challans and debits for tax payments. ITC Ledger records input tax credits claimed from purchases and their use against output liability. Return Liability Ledger shows liabilities for each filing period. Together, these ledgers determine the net payable or refundable amount during return filing.
When should I use Cash + ITC Balance vs the detailed ledgers?
When should I use Cash + ITC Balance vs the detailed ledgers?
Cash + ITC Balance API returns a snapshot of current balances for a specific month, ideal for quick checks before filing or dashboard summaries. Detailed ledger APIs return individual transactions with descriptions and reference numbers. Use these for reconciliation, audit trails, and investigating discrepancies.
What date format do the from and to parameters use?
What date format do the from and to parameters use?
Ledger APIs use
DD/MM/YYYY format for from and to query parameters (for example, 01/04/2025 for April 1, 2025). Common validation errors include: to date beyond current date, from date after to date, and invalid date format. Ensure both dates fall within the authenticated GSTIN’s registration period.What authentication is required for ledger APIs?
What authentication is required for ledger APIs?
GST Ledgers APIs require a Taxpayer access token obtained through the taxpayer authentication flow with OTP verification. Include this token in the
Authorization header along with your x-api-key. Taxpayer tokens expire after 30 minutes of inactivity. Refresh the session if you receive an authentication error.Can I use ledger data to prepare for GSTR-3B set-off and payment?
Can I use ledger data to prepare for GSTR-3B set-off and payment?
Yes. Use GST Ledgers API for GSTR-3B preparation. Fetch cash and ITC balances to determine available funds, compare against your computed liability, and identify any shortfall requiring additional challan payment. The return liability ledger shows pending liabilities from previous periods that may affect your filing.
What should I do if ledger values don't match my internal books?
What should I do if ledger values don't match my internal books?
Ledger discrepancies typically arise from timing differences, rejected transactions, or portal sync delays. Pull transaction-level entries with reference numbers using the detailed ledger APIs, then match each entry against your internal records. Common causes include unposted challans, reversed ITC claims, and pending return processing. Review the error handling guide for troubleshooting, or contact GST support if discrepancies persist.
How do I handle session expiry during ledger API calls?
How do I handle session expiry during ledger API calls?
Taxpayer sessions expire after approximately 30 minutes of inactivity. If you receive an authentication error (HTTP 401 or specific error code), re-initiate the taxpayer authentication flow to obtain a fresh access token. Design your integration to detect session expiry and automatically trigger re-authentication before retrying the failed request.