Save GSTR-1 Return as a Draft
PUT
https://apisandbox.whitebooks.in/gstr1/retsaveUsed to save entire GSTR1 invoices.
Bulk Ingestion Engine
Explore FeatureBulk Invoice Upload & Auto-Drafting for GSTR-1
Ingest thousands of outward invoices from Excel, Tally, or custom ERPs, auto-validate GSTIN checksums, and push draft payloads directly to GSTN.
Parameters
query parameters
emailstringrequiredUser Email
header parameters
gstinstringrequiredGST Number
ret_periodstringrequiredReturn Period (MMYYYY)
gst_usernamestringrequiredGST UserName
state_cdstringrequiredState Code
ip_addressstringrequiredIP Address
txnstringrequiredTransaction
client_idstringrequiredClient ID
client_secretstringrequiredClient Secret
Request Body
application/jsonrequired
gstinstringoptionalGSTIN number
Example: "27AHQPA7588L1ZJ"
fpstringoptionalFp Type
Example: "122016"
gtnumberoptionalgt Type
Example: 3782969.01
cur_gtnumberoptionalDocument Number (Alphanumeric with / and - are allowed)
Example: 3782969.01
b2barray<object>optionalArray items:
ctinstringoptionalChallan Temporary Identification Number
Example: "01AABCE2207R1Z5"
invarray<object>optionalArray items:
inumstringoptionalInvoice Number
Example: "S008400"
idtstringoptionalInvoice Date
Example: "24-11-2016"
valnumberoptionalInvoice Value
Example: 729248.16
posstringoptionalPlace of Supply
Example: "06"
rchrgstringoptionalReverse Charge
Example: "N"
etinstringoptionaletin Number
Example: "01AABCE5507R1C4"
inv_typstringoptionalInvoice Type
Example: "R"
diff_percentnumberoptionalDifferencial Percentage
Example: 0.65
itmsarray<object>optionalb2baarray<object>optionalArray items:
ctinstringoptionalChallan Temporary Identification Number
Example: "01AABCE2207R1Z5"
invarray<object>optionalArray items:
oinumstringoptionalOriginal Invoice Number
Example: "S008400"
oidtstringoptionalOriginal Invoice Date
Example: "24-11-2016"
inumstringoptionalInvoice Number
Example: "S008400"
idtstringoptionalInvoice Date
Example: "24-11-2016"
valnumberoptionalInvoice Amount
Example: 729248.16
posstringoptionalPlace Of Supply
Example: "06"
rchrgstringoptionalReverse Charge
Example: "N"
etinstringoptionaletin number
Example: "01AABCE5507R1C4"
inv_typstringoptionalInvoice Type
Example: "R"
diff_percentnumberoptionalDifferencial Percentage
Example: 0.65
itmsarray<object>optionalb2clarray<object>optionalArray items:
posstringoptionalPlace Of Supply
Example: "05"
invarray<object>optionalArray items:
inumstringoptionalInvoice Number
Example: "92661"
idtstringoptionalInvoice Date
Example: "10-01-2016"
valnumberoptionalInvoice Value
Example: 784586.33
inv_typstringoptionalInvoice Type
Example: "CBW"
etinstringoptionaletin
Example: "27AHQPA8875L1CU"
diff_percentnumberoptionalDifferencial Percentage
Example: 0.65
itmsarray<object>optionalb2claarray<object>optionalArray items:
posstringoptionalPlace of Supply
Example: "06"
invarray<object>optionalArray items:
oinumstringoptionalOriginal Invoice Number
Example: "9266"
oidtstringoptionalOriginal Invoice Date
Example: "10-02-2016"
inv_typstringoptionalInvoice Type
Example: "CBW"
diff_percentnumberoptionalDifferencial percentage
Example: 0.65
inumstringoptionalInvoice Number
Example: "92661"
idtstringoptionalInvoice Date
Example: "10-01-2016"
valnumberoptionalInvoice Value
Example: 784586.33
etinstringoptionaletin number
Example: "01AABCE5507R1C4"
itmsarray<object>optionalcdnrarray<object>optionalArray items:
ctinstringoptionalctin Number
Example: "01AAAAP1208Q1ZS"
ntarray<object>optionalArray items:
nttystringoptionalNote Type
Example: "C"
nt_numstringoptionalNote Number
Example: "533515"
nt_dtstringoptionalNote Date
Example: "23-09-2016"
p_gststringoptionalPre GST
Example: "N"
posstringoptionalPlace of Supply
Example: "01"
rchrgstringoptionalReverse Charge
Example: "N"
inv_typstringoptionalInvoice Type
Example: "R"
valnumberoptionalInvoice Value
Example: 123123
diff_percentnumberoptionalDifferencial Percentage
Example: 0.65
itmsarray<object>optionalcdnraarray<object>optionalArray items:
ctinstringoptionalctin number
Example: "01AAAAP1208Q1ZS"
ntarray<object>optionalArray items:
nttystringoptionalNote Type
Example: "C"
ont_numstringoptionalOriginal Note Number
Example: "533515"
ont_dtstringoptionalOriginal Note Date
Example: "23-09-2016"
nt_numstringoptionalNote Number
Example: "533515"
nt_dtstringoptionalNote Date
Example: "23-09-2016"
p_gststringoptionalPre GST
Example: "N"
posstringoptionalPlace of Supply
Example: "01"
rchrgstringoptionalReverse Charge
Example: "N"
inv_typstringoptionalInvoice Type
Example: "R"
diff_percentnumberoptionalDifferencial Percentage
Example: 0.65
valnumberoptionalInvoice Value
Example: 123123
itmsarray<object>optionalb2csarray<object>optionalArray items:
sply_tystringoptionalSupply Type
Example: "INTER"
diff_percentnumberoptionalDifferencial Percentage
Example: 0.65
rtnumberoptionalRate
Example: 5
typstringoptionalType
Example: "E"
etinstringoptionaletin
Example: "01AABCE5507R1C4"
posstringoptionalPlace Of Supply
Example: "05"
txvalnumberoptionalTaxable Value
Example: 110
iamtnumberoptionaligst Amount
Example: 10
csamtnumberoptionalCess Amount
Example: 10
b2csaarray<object>optionalArray items:
omonstringoptionalOriginal Month Of Invoice
Example: "122016"
sply_tystringoptionalSupply Type
Example: "INTER"
diff_percentnumberoptionalDifferencial Percentage
Example: 0.65
typstringoptionalType
Example: "E"
etinstringoptionaletin number
Example: "01AABCE5507R1C4"
posstringoptionalPlace Of Supply
Example: "05"
itmsarray<object>optionalArray items:
rtnumberoptionalProduct / Item Rate
Example: 5
txvalnumberoptionalTaxable Value
Example: 110
iamtnumberoptionalIgst Amount
Example: 10
camtnumberoptionalCGST Amount
Example: 0
samtnumberoptionalSGST Amount
Example: 0
csamtnumberoptionalCess Amount
Example: 10
exparray<object>optionalArray items:
exp_typstringoptionalExport Type
Example: "WPAY"
invarray<object>optionalArray items:
inumstringoptionalInvoice Number
Example: "81542"
idtstringoptionalInvoice Date
Example: "12-02-2016"
valnumberoptionalInvoice Value
Example: 995048.36
diff_percentnumberoptionalDifferencial Percentage
Example: 0.65
sbpcodestringoptionalprort Code
Example: "ASB991"
sbnumstringoptionalShipping Bill Number
Example: "7896542"
sbdtstringoptionalShipping Bill Date
Example: "04-10-2016"
itmsarray<object>optionalexpaarray<object>optionalArray items:
exp_typstringoptionalExport Type
Example: "WPAY"
invarray<object>optionalArray items:
oinumstringoptionalOriginal Invoice Number
Example: "81542"
oidtstringoptionalOriginal Invoice Date
Example: "12-02-2016"
inumstringoptionalInvoice Number
Example: "81542"
idtstringoptionalInvoice Date
Example: "12-02-2016"
diff_percentnumberoptionalDifferencial Percentage
Example: 0.65
valnumberoptionalInvoice Value
Example: 995048.36
sbpcodestringoptionalprort Code
Example: "ASB995"
sbnumstringoptionalShipping Bill Number
Example: "1234567"
sbdtstringoptionalShipping Bill Date
Example: "04-10-2016"
itmsarray<object>optionalhsnobjectoptionaldataarray<object>optionalArray items:
numnumberoptionalProduct / Item number
Example: 1
hsn_scstringoptionalHSN/SAC CODE
Example: "1009"
descstringoptionalGoods Description
Example: "Goods Description"
uqcstringoptionaluqc
Example: "kg"
qtynumberoptionalQuantity
Example: 2.05
rtnumberoptionalInvoice Value
Example: 0.1
txvalnumberoptionalTaxable Value
Example: 10.23
iamtnumberoptionalIgst Amount
Example: 14.52
csamtnumberoptionalCess Amount
Example: 500
nilobjectoptionalinvarray<object>optionalArray items:
sply_tystringoptionalSupply Type
Example: "INTRB2B"
expt_amtnumberoptionalExempted Amount
Example: 123.45
nil_amtnumberoptionalTotal Nil rated outward supplies
Example: 1470.85
ngsup_amtnumberoptionalTotal Non GST outward supplies
Example: 1258.5
txpdarray<object>optionalArray items:
posstringoptionalPlace Of Supply
Example: "05"
sply_tystringoptionalSupply Type
Example: "INTER"
diff_percentnumberoptionalDifferencial Percentage
Example: 0.65
itmsarray<object>optionalArray items:
rtnumberoptionalProduct / Item Rate
Example: 5
ad_amtnumberoptionalAdvance to be adjusted
Example: 100
iamtnumberoptionalIgst Amount
Example: 9400
csamtnumberoptionalCess Amount
Example: 500
txpdaarray<object>optionalArray items:
omonstringoptionalOriginal Month
Example: "122016"
posstringoptionalPlace Of Supply
Example: "05"
sply_tystringoptionalSupply Type
Example: "INTER"
diff_percentnumberoptionalDifferencial Percentage
Example: 0.65
itmsarray<object>optionalArray items:
rtnumberoptionalProduct / Item Rate
Example: 5
ad_amtnumberoptionalAdvance to be adjusted
Example: 100
iamtnumberoptionalIgst Amount
Example: 9400
csamtnumberoptionalCess Amount
Example: 500
atarray<object>optionalArray items:
posstringoptionalPlace Of Supply
Example: "05"
sply_tystringoptionalSupply Type
Example: "INTER"
diff_percentnumberoptionalDifferencial Percentage
Example: 0.65
itmsarray<object>optionalArray items:
rtnumberoptionalProduct / Item Rate
Example: 5
ad_amtnumberoptionalAdvance to be adjusted
Example: 100
iamtnumberoptionalIgst Amount
Example: 9400
csamtnumberoptionalCess Amount
Example: 500
ataarray<object>optionalArray items:
omonstringoptionalOriginal Month
Example: "022017"
posstringoptionalPlace Of Supply
Example: "05"
sply_tystringoptionalSupply Type
Example: "INTER"
diff_percentnumberoptionalDifferencial Percentage
Example: 0.65
itmsarray<object>optionalArray items:
rtnumberoptionalProduct / Item Rate
Example: 5
ad_amtnumberoptionalAdvance to be adjusted
Example: 100
iamtnumberoptionalIgst Amount
Example: 9400
csamtnumberoptionalCess Amount
Example: 500
doc_issueobjectoptionaldoc_detarray<object>optionalArray items:
doc_numnumberoptionalDocument Number
Example: 1
docsarray<object>optionalcdnurarray<object>optionalArray items:
typstringoptionalEXPWP/ EXPWOP/ B2CL
Example: "B2CL"
nttystringoptionalCredit/debit note type/ Refund Voucher
Example: "C"
nt_numstringoptionalCredit note/debit note / Refund Voucher Number
Example: "533515"
nt_dtstringoptionalCredit Note/Debit Note/ Refund Voucher date
Example: "23-09-2016"
p_gststringoptionalPre GST Regime Dr./ Cr. Notes
Example: "N"
posstringoptionalPlace Of Supply
Example: "05"
valnumberoptionalInvoice Value
Example: 64646
diff_percentnumberoptionalDifferencial Percentage
Example: 0.65
itmsarray<object>optionalArray items:
numnumberoptionalProduct / Item number
Example: 1
itm_detobjectoptionalcdnuraarray<object>optionalArray items:
ont_numstringoptionalOriginal Credit note/debit note / Refund Voucher Number
Example: "533515"
ont_dtstringoptionalOriginal Credit Note/Debit Note/ Refund Voucher date
Example: "23-09-2016"
nt_numstringoptionalCredit note/debit note / Refund Voucher Number
Example: "533515"
nt_dtstringoptionalCredit Note/Debit Note/ Refund Voucher date
Example: "23-09-2016"
nttystringoptionalCredit/debit note type/ Refund Voucher
Example: "C"
typstringoptionalEXPWP/ EXPWOP/ B2CL
Example: "B2CL"
p_gststringoptionalPre GST Regime Dr./ Cr. Notes
Example: "N"
inumstringoptionalInvoice Number
Example: "915914"
valnumberoptionalInvoice Value
Example: 123123
idtstringoptionalInvoice Date
Example: "23-09-2016"
diff_percentnumberoptionalDifferencial Percentage
Example: 0.65
itmsarray<object>optionalArray items:
numnumberoptionalProduct / Item number
Example: 1
itm_detobjectoptionalResponse
Not Found. If requested entity is not found or if requested API is not found.
Frequently Asked Questions
Mandatory headers include:
Authorization: Bearer <access_token>, x-api-key, gstin (taxpayer GSTIN), ret_period (return period in MMYYYY format, e.g. 092026), gst_username, state_cd, ip_address, and txn (transaction reference from the active taxpayer GST portal OTP session).The request body accepts invoice tables including
b2b (regular B2B supplies), b2cl (large consumer invoices), b2cs (small consumer supplies), cdnr (credit/debit notes for registered recipients), exp (exports), hsn (HSN summary), nil (nil rated/exempt), and doc_issue (document summary).Yes. Saving returns data to GSTN initiates an asynchronous processing job. The response returns a reference ID (
ref_id) which should be polled via the GSTR-1 return tracking endpoint to confirm that all records processed without errors.Yes. You can bundle multiple tables (such as B2B invoices and HSN summaries) into a single payload, provided the total request payload stays within maximum size limits.
No example available.