Place of Supply

The place_of_supply field on every GST document (invoice, bill, estimate, credit/debit note, sales/purchase order) drives whether the tax routes as CGST+SGST (intra-state) or IGST (inter-state). Get this wrong and your GSTR-1 shows tax in the wrong column.

Canonical format: `IN-XX`

Send the canonical Indian state code with the IN- prefix, e.g. IN-KA for Karnataka, IN-MH for Maharashtra, IN-UK for Uttarakhand.

For convenience the API also accepts these four shapes and normalises them before persistence:

"IN-KA"          → IN-KA   (preferred — canonical)
"29"             → IN-KA   (2-digit GST state code from GSTIN)
"Karnataka"      → IN-KA   (full state name)
"29-Karnataka"   → IN-KA   (GSTN tool format)
"Goa"            → IN-GA
"IN-UT"          → IN-UK   (pre-2010 Uttarakhand code, kept as alias)

Validation errors

Anything that doesn't resolve to a known state — including the string "IN-IN", garbage like "India", or a typo like "Karnatka" — returns 422 with a hint at exactly which field is bad:

HTTP/1.1 422 Unprocessable Entity

{
  "code":    "validation.invalid_value",
  "message": "Unrecognised place_of_supply 'India'. Accepted formats: 'IN-KA' (preferred), '29', 'Karnataka', or '29-Karnataka'.",
  "field":   "place_of_supply"
}

Why it matters

The intra-vs-inter-state classification is a raw string compare between the invoice's place_of_supplyand the supplier branch's state. If two records carry the same logical state in different shapes — one as "IN-KA", the other as "Karnataka"— the compare fails. Downstream the tax gets split across CGST+SGST when it should have been IGST (or vice versa) and the error is invisible until GSTR-1 filing time.

The DTO validator catches this at the API boundary so it never reaches storage.

Reading it back

Every response returns place_of_supply in the canonical IN-XX form. You can rely on that — no need to re-parse free-form state names on your side.

Where it's required