The GSTR-9 form definition (GSTR 9 Config)

The GSTR-9 form definition is the set of GSTR 9 Config records that tells Compute GSTR9 which rows the annual return has and how to produce each figure. There is one record per row and lane. xMatix creates the records for a financial year the first time you compute a GSTR-9 for that year, and every later compute uses them. Most tenants never change them. This page is for the administrator or tax lead who needs to see how a figure on the annual return is built, or who has to adjust a row deliberately.

Overview

A financial year's definition has 122 records:

• 85 form rows for Tables 4 to 8 and 10 to 16, plus the total-turnover line after Part V (row code PTV-TURNOVER).
• 32 Table 9 rows: eight descriptions (IGST, CGST, SGST, Cess, Interest, Late fee, Penalty and Other), each with four rows: tax payable, paid in cash, paid through ITC, and the shortfall.
• 5 Books rows, for 4N, 6A, 6B, 7E and 8F. These supply the tax-ledger figure that the Δ (variance) column on the return compares with.

Each record names a row (Table Row Code), the lane it feeds (Lane), where it sits in the evaluation order (Execution Order), and how its figure is produced (Logic Type and Logic Definition). It also holds the heading and description the row shows on the return (Section and Line Item), and whether the government portal owns the row (Is System Locked).

When to use it

• To answer "where does this number come from?" Open the row's record and read its Logic Type and Logic Definition. For example, 4B reads Outward:4B, which comes from the B2B supplies on your filed GSTR-1 returns. 4N reads 4H + 4M.
• To take a row out of the compute, for example while you investigate a figure. Clear Is Active.
• To change how a row is produced, when you are certain the shipped definition does not fit your filing. Change the record and tick Is Customized.
• To undo your change and return to the shipped definition, delete the record.

You do not need this page to prepare or file GSTR-9. The annual returns page covers the return itself.

How xMatix handles it

Created on first compute, one set per year. When you run Compute GSTR9 (or the older Get Records), xMatix checks the return's financial year for a complete definition and adds any record that is missing. It identifies each record by financial year, row code and lane. Each financial year has its own 122 records, so changing a row for 2024-25 does not affect 2025-26. If two GSTINs are computed for the same year, they share that year's records. They are not created twice.

Evaluated in order. The compute takes the active records for the year in Execution Order. It works out the Books rows first and attaches each one to the row with the same code. It then evaluates the Computed rows one by one:

A selector that finds no data gives zero. For example, a business with no SEZ supplies gets a nil 4D. A source name the compute does not know stops the compute, so a mistyped definition never appears on the return as a nil.

What the return keeps. When a return is computed, the row's heading, description, logic type and Is System Locked setting are copied onto the return's row, along with a link back to the record. A figure you entered or overrode on the return keeps your figure when you compute again. A filed return can be neither recomputed nor edited, so changing the definition never alters a return you have already filed.

Two passes. The Computed lane always comes from the definition and your sources. The Final lane, which is what is filed, then repeats the same formulas over your entered and overridden figures. That is why an entry on 4F flows into 4H, 4N and 5N. A formula change therefore affects both lanes. The Final lane is also worked out again whenever someone enters or overrides a figure on the return.

Shipped corrections. The definition is versioned (Catalog Version). When xMatix ships a corrected definition, the next compute updates every record whose version is older, unless it is marked Is Customized. A row added to the form is created on the next compute whatever the version. A record you deleted is recreated from the shipped definition on the next compute.

Before the first compute. A return that has never been computed shows the shipped list of rows at zero, not your tenant's records.

Prerequisites

• Access to the GSTR 9 Config entity in your security profile. The four standard profiles (System Admin, Standard User, Sales Manager, Sales Executive) have full access. See Permissions.
• At least one GSTR-9 return computed for the financial year. Until then, that year has no records.
• To change records: a Create layout for GSTR 9 Config. None is shipped (see Step 3).

Procedure

Step 1 — Open the list

The entity is not in any app's menu. Open the Apps launcher, choose All Entities, and pick GSTR 9 Config. You can also type the name in the launcher's search.

The default view, Active Configs, lists the active records of every financial year in Execution Order. Its columns are Name, Financial Year, Execution Order, Section, Sub Section, Logic Type, Tax Type, Source Module, Is Active and Is System Locked. The view has no Table Row Code or Lane column, but both appear in the record's Name: GSTR9CFG-<year>-<row code>-<lane>, for example GSTR9CFG-2024-25-4N-Books. Use the search box with a row code, or filter on Financial Year, to narrow the list. Sub Section, Tax Type and Source Module are always blank.

Step 2 — Read how a row is produced

Open a record. No View layout is shipped for the entity, so the record opens as a read-only list of all its fields under the notice "No View layout is configured for GSTR 9 Config". Read Logic Type and Logic Definition together, using the Fields table to decode the definition. For a formula, open each row it names in turn to trace a figure down to its sources.

Step 3 — Give administrators a form (only if you will change rows)

Records cannot be edited from the list or the read-only record page. Selecting New shows "No form is set up for GSTR 9 Config". To change records, an administrator with metadata access creates a layout in Setup → Metadata → GSTR 9 Config → Layouts. The notice on the record page links there. Include at least Table Row Code, Lane, Execution Order, Logic Type, Logic Definition, Section, Line Item, Is Active, Is System Locked and Is Customized. Restrict the layout to the people who own your GST filing.

Step 4 — Change a row

On the record, change the field you need. For example, edit Line Item, correct a Logic Definition, or move Execution Order. In the same save, tick Is Customized: xMatix does not tick it for you. Without it, the next shipped correction overwrites your change.

To take a row out of the compute instead, clear Is Active. Check first that no active formula refers to the row (see Business rules).

Step 5 — Recompute and check

Open a return for the same financial year that is not yet filed and choose Compute GSTR9. If the definition has a problem, the compute stops with a message naming the row, its lane and its execution order, and the return is not changed. Fix the record and compute again. When the compute succeeds, check the row and every sub-total above it in the Annual Summary, then run the pre-file checklist again.

Step 6 — Undo a change

Delete the record. On the next compute, xMatix recreates it from the shipped definition, with Is Customized cleared and the current Catalog Version. Clearing Is Customized alone does not undo anything: the record keeps your change until xMatix ships a newer version of the definition.

Fields

Logic Definition grammar

• Rollup Filed Returns: <source>:<selector>. The sources are Outward (the Table 4 and 5 buckets built from filed GSTR-1, for example Outward:4B), Section31 (a GSTR-3B Table 3.1 row, for example Section31:3.1d), ItcAvailable (GSTR-3B Table 4A sub-rows, comma-separated and added together, for example ItcAvailable:1,2,3,4,5), ItcIneligible (GSTR-3B Table 4D sub-rows, for example ItcIneligible:1) and ItcReversed (a Table 7 reason, for example ItcReversed:7E). Table 9 uses Payment:<description>:<column>, for example Payment:IGST:PAYABLE, where the column is PAYABLE, CASH, ITC or DIFF.
• Books Ledger: Output, Input:Eligible, Input:Blocked or Input:Ineligible.
• Formula: row codes joined by + or -, with a space on each side of every sign, for example 5N + 10 - 11. Only addition and subtraction are supported. The spaces matter because Table 9 codes contain hyphens.
• Rollup GSTR-2B, Manual, Spillover: leave blank.

Business rules

• One record per row and lane. Two active Computed records with the same row code in a year, or two Books records, stop the compute. So does a Books record with no Computed record of the same code.
• Order is dependency. A formula that names a row with a later Execution Order, an inactive row, or a row that does not exist stops the compute with "…references row '…', which has not been evaluated yet."
• Deactivating removes the row from the return. On the next compute, a row whose record is inactive is no longer created on the return. A row you had overridden on that return is kept.
• Locks on the return. The pre-file checklist locks 6A, 8A and every Table 9 row on the return by their row codes, whatever Is System Locked says on the definition.
• Errors leave the return unchanged. Any definition error is reported as a validation message naming the row, and nothing on the return is saved.
• Rows added by hand compute and appear on the return under their Section heading. They are not included in the GSTN request unless the row is one xMatix maps; see the annual returns troubleshooting.

Example

A tax lead at a trading company traces 6J on the 2024-25 return. It shows a difference that the lead expected to be nil.

1. In Apps → All Entities → GSTR 9 Config, the lead searches for 6J and opens GSTR9CFG-2024-25-6J-Computed. Logic Type is Formula and Logic Definition is 6I - 6A2.
2. Opening GSTR9CFG-2024-25-6A2-Computed shows 6A - 6A1. 6A1 is Manual, so it is a figure the taxpayer enters: credit of an earlier year that was availed in 2024-25.
3. The lead enters that carried-in credit on row 6A1 of the return, with a reason. The Final lane of 6A2 and 6J moves at once, and 6J becomes nil.

No definition record was changed. That is the usual outcome: the definition explains the figure, and the fix is an entry on the return.

Training

Practice exercise

In a sandbox with a computed 2024-25 GSTR-9:

1. Find the record for row 4N in the Books lane and write down its Logic Definition. Expected: Output.
2. Find the records for 8A and 9-CESS-DIFF and note which logic types they use and whether they are system-locked. Expected: Rollup GSTR-2B and Rollup Filed Returns (Payment:CESS:DIFF); both are locked.
3. Without changing anything, trace 5N back to rows that read your sources. Expected: 4N + 5M - 4G - 4G1. From there, through 4H, 4M, 5G and 5L, you reach rows such as 4A (Outward:4A) and 4G (Section31:3.1d).

Quick reference

• One record per row and lane, and one set of 122 records per financial year.
• Open it from Apps → All Entities → GSTR 9 Config. It is read-only unless you add a layout.
• Row code and lane are in the record name.
• Formulas use + and - with spaces, and the rows they name must have a lower Execution Order.
• Tick Is Customized whenever you change a record.
• Delete a record to restore the shipped definition on the next compute.
• Filed returns never change when the definition does.

Permissions

Access is controlled by the GSTR 9 Config entity permission in the security profile. The four standard profiles (System Admin, Standard User, Sales Manager and Sales Executive) have full access: view, create, edit and delete. Because a changed record alters every unfiled GSTR-9 for that year, consider creating a custom profile that removes edit and delete for everyone except the people who own GST filing.

Running the compute that creates and reads the records needs the Compute GSTR9 action on the GSTR 9 Return, described in Annual returns → Permissions. A user who cannot see GSTR 9 Config can still compute; the records are created regardless.

Configuration

• Layouts. No View or Create layout is shipped. Setup → Metadata → GSTR 9 Config → Layouts is where you add one if your team needs to change rows. Without a layout, records are read-only.
• List views. Active Configs is the default view (active records, by Execution Order). Add a view in the same metadata area if you want Table Row Code, Lane and Logic Definition as columns, or an inactive-records view.
• Numbering. None. Names are set by xMatix when the record is created.
• Is Customized. Your record-by-record switch between "follow xMatix's corrections" and "keep my change".
• Not configurable. The list of sources, the Logic Type behaviours and the grammar are fixed. You cannot add a new data source through this entity.

Common problems

Compute GSTR9 stops with "GSTR-9 catalog row '…' (… lane, order …): …"

A definition record cannot be evaluated. The message names the row, its lane and its execution order, then the reason: for example an empty definition, an unknown source, a selector that is not a number, an operator other than + or -, or a row named before it is evaluated. Open that row's record, correct it, and compute again. If you did not change the record, delete it so the shipped definition is restored on the next compute.

"…references row '…', which has not been evaluated yet. A Formula row's ExecutionOrder must sort after every row it references."

The formula names a row that is inactive, does not exist for this year, or has a higher Execution Order. Reactivate the row, correct the code, or give the formula a higher Execution Order than its operands.

"…uses operator '…'; only '+' and '-' are supported. Operators must be surrounded by whitespace."

The formula has a sign written without spaces (for example 4H+4M) or uses another operator. Rewrite it as 4H + 4M.

"…declares LogicType 'SQL', which the GSTR-9 engine does not implement."

SQL and Rule are listed values that the compute does not support. Choose one of the supported logic types.

"…declares lane 'Override'…" or "…lane 'Final'…"

Only Computed and Books are valid lanes in the definition. Override and Final are produced on the return itself. Set the lane to Computed or Books.

"The GSTR-9 catalog has more than one Computed-lane row for '…'."

Two active records in the year share a row code and lane. Deactivate or delete one.

My change disappeared after an update

The record was not marked Is Customized, and xMatix shipped a newer definition. Make the change again and tick Is Customized this time.

I changed a row but the return did not move

The return has not been computed since the change, the return is filed, or you changed a different year's record. Check Financial Year on the record and compute the return again.

I cannot edit a record or create a new one

No layout is shipped for the entity. See Step 3.

Common questions

Will changing a row change returns I have already filed?

No. A filed GSTR-9 cannot be recomputed and its rows cannot be edited, so it keeps the figures it was filed with. A change affects only returns for the same financial year that you compute after the change. The return's rows also keep a copy of the heading, description and logic type they were computed with. Each financial year has its own records, so a change to 2024-25 never reaches 2025-26 or any other year.

How do I get back to the standard definition?

Delete the record you changed. The next time a return for that year is computed, xMatix recreates the record from the shipped definition at the current version, with Is Customized cleared. Clearing Is Customized on its own is not enough: the record keeps your change until xMatix ships a newer version of the definition, and only then is it refreshed.

Why do some rows always start at zero?

They are Manual rows: figures that no monthly return carries, such as advances (4F), transitional credit (6K and 6L), refunds and demands (Table 15) and the next-year amendments (Tables 10 to 14). The compute creates them at zero so the form is complete and the sub-totals above them are correct. You then enter the real figures on the return with a reason. Rows marked Spillover behave the same way.

Should I deactivate a row the portal does not need from me?

Usually not. A nil row is harmless, and a deactivated row breaks every formula that names it, which stops the compute. Leave Manual rows you have nothing to declare at zero.

Related topics

• Annual returns: preparing and filing GSTR-9
• GSTR-1 and GSTR-3B, the returns the rollups read
• GSTR-2B, the source of 8A
• GSTR 9 Config entity reference
• Security profiles