Skip to content

Get Preference#

Get Preference API fetches public information on preferences sets for a particular GSTIN. You need to provide the financial year (FY) along with the GSTIN to fetch the results for that FY.

Route

/basic/gstn/{flynn-version}/commonapi/{gstn-api-version}/returns?gstin={gstin}&fy={fy}&action={action}

  • active ‘flynn-version’: v1.0
  • method: GET

URL Parameters#

Name Description Type
flynn-version version of the API
for example, v1.0		 string
gstn-api-version as per the version of the GST API Documentation
for example, v0.3		 string

Query Parameters#

Name Description Type Mandatory
gstin GSTIN of the taxpayer
for example, 33GSPTN0791G1Z5		 string Yes
fy Financial Year of filing date, to filter the results 

 format = YYYY-YY 
 min-value = 2017-18
string Yes
action Api action
for example, GETPREF		 string Yes

Headers#

All required headers to make an authenticated API call.

Response#

200#

Successful response will be the same payload as per the ‘GST API Documentation’ for the “View and Track Returns” API.

Example

{
  "status": "1",
  "data": {
    "response": [
      {
        "quarter": "Q1",
        "preference": "M"
      },
      {
        "quarter": "Q2",
        "preference": "M"
      },
      {
        "quarter": "Q3",
        "preference": "M"
      },
      {
        "quarter": "Q4",
        "preference": "M"
      }
    ]
  },
  "error": null,
  "info": null,
  "additionalInfo": null,
  "alert": null
}
Errors#

Invalid GSTIN Format

{
  "status": "0",
  "data": null,
  "error": {
    "message": "err-invalid-gstin-format",
    "type": "ClientRequest",
    "args": {
      "parameter-name": "gstin"
    }
  },
  "info": null,
  "additionalInfo": null,
  "alert": null
}

Invalid GSTN API Version

{
  "status": "0",
  "data": null,
  "error": {
    "message": "err-invalid-gst-returns-api-version",
    "type": "ClientRequest",
    "args": {
      "version": "v8.0"
    }
  },
  "info": null,
  "additionalInfo": null,
  "alert": null
}

GSTN Error

{
  "status": "0",
  "data": null,
  "error": {
    "message": "err-gstn-returned-error",
    "type": "Gstn",
    "args": {
      "gstn-err": {
        "status-code": "0",
        "error-code": "RET11402",
        "message": "Unauthorized User"
      }
    }
  },
  "info": null,
  "additionalInfo": null,
  "alert": null
}
Response Status Description
400 Invalid GSTIN format in the request
400 Invalid GSTN API Version
404 Invalid GSTIN
502 Error at GSTN end

Common Errors

check here for other common errors.