(Deprecated) Invoices
IMPORTANT NOTICE
GST 1.0 APIs are deprecated and will not be supported after 30-11-2022. If you want to integrate with ClearTax GST, please use GST 2.0 APIs instead.
ClearTax Invoices APIs provide you the ability to get invoices from the ClearTax account or add a new invoice to your ClearTax account.
Resource Objects
Invoice Object
Line item object
Party Object
Bank details object
Export object
SGST and CGST rate should be Zero for export invoices
Import object
E-commerce object
Advance payment object
TCS and TDS object
ITC details object
Learn more about ITC and its types here
Custom field object
Get an Invoice
You can get an invoice by submitting a GET request to the GST API:
URL Query String
{{HOST}}/gst/api/v0.1/taxable_entities/{{taxable_entity_id}}/invoices/{{invoice_id}}?source=USERRequest Parameter
Sample Request
https://api.clear.in/gst/api/v0.1/taxable_entities/249baf74-7392-4fa2-b3a0-685c6c7ad87e/invoices/123abc?source=USERSample Response
{
"ref_doc_number": "reference number",
"due_date": "2021-09-30",
"paid_on": null,
"shipping_charge": null,
"invoice_status": "CREATED",
"payment_terms": null,
"notes": "CUSTOMER NOTES",
"advance_payments": [
{
"document_number": null,
"document_date": null,
"adjustment_val": null
}
],
"isd": {
"original_supplier": null,
"isd": null
},
"export_currency": null,
"provisional_itc_claimed": null,
"conversion_rate": null,
"total_val_foreign_currency": null,
"due_balance": 118.00,
"transaction_payment_status": "UNPAID",
"cgst_itc_claim_amount": null,
"sgst_itc_claim_amount": null,
"igst_itc_claim_amount": null,
"cess_itc_claim_amount": null,
"ignored_warnings": null,
"owner": "1984bd22-2a81-414a-9186-e0fea43659df",
"id": "NEWTEST001",
"transaction_date": "2021-09-30",
"return_period": "092021",
"quarterly_return_period": "152021",
"total_taxable_val": 100.00,
"total_cgst_val": 9.00,
"total_sgst_val": 9.00,
"total_igst_val": 0.00,
"total_cess_val": 0.00,
"total_val": 118.00,
"place_of_supply": "KARNATAKA",
"updated_at": "2021-09-30",
"is_amendment": false,
"amendment_detail": null,
"created_at": "2021-09-30",
"section_name": "B2B",
"fiscal_year": "2021",
"fiscal_month": "SEPTEMBER",
"fiscal_quarter": "Q2",
"total_tax_value": 18.00,
"source": "USER",
"discount_type": null,
"gst_status": "STAGED",
"gst_validation_errors": null,
"user_updated_at": "2021-09-30",
"uploaded_once": false,
"is_canceled": false,
"is_rate_inclusive_of_tax": false,
"rounding_factor": null,
"date_of_purchase": "2021-09-30",
"validate_warnings": false,
"seller_contact_id": null,
"consignee_contact_id": "eb0e179d-32f9-469d-ae80-dae5cda90dd7",
"receiver_contact_id": "eb0e179d-32f9-469d-ae80-dae5cda90dd7",
"customer_type": "UIN_REGISTERED",
"supplier_type": null,
"entity_channel_type": null,
"is_party_export": null,
"is_party_sez": null,
"is_party_consumer": null,
"is_party_unregistered": null,
"is_party_cash_ledger": null,
"is_taxable_value_overridden": null,
"total_kerala_flood_cess": null,
"differential_tax": null,
"terms_and_conditions": "Terms and conditions",
"serial_number": "NEWTEST001",
"type": "SALE",
"original_invoice_number": null,
"original_invoice_date": null,
"original_invoice_gstin": null,
"classification": "B2B",
"line_items": [
{
"tcs": {
"cgst_rate": null,
"cgst_val": null,
"sgst_rate": null,
"sgst_val": null,
"igst_rate": null,
"igst_val": null,
"cess_rate": null,
"cess_val": null
},
"tds": {
"cgst_rate": null,
"cgst_val": null,
"sgst_rate": null,
"sgst_val": null,
"igst_rate": null,
"igst_val": null,
"cess_rate": null,
"cess_val": null
},
"total_val_foreign_currency": null,
"zero_tax_category": null,
"item_code": null,
"gst_code": "8466",
"gst_type": "GOODS",
"description": "ITEM1",
"notes": null,
"unit_price": 100.00,
"unit_price_including_tax": null,
"unit_of_measurement": "BGS",
"item_id": null,
"serial_number": 1,
"quantity": 1.0,
"discount_rate": null,
"discount": null,
"taxable_val": 100.00,
"cgst_rate": 9.00,
"cgst_val": 9.00,
"sgst_rate": 9.00,
"sgst_val": 9.00,
"igst_rate": 0.00,
"igst_val": 0.00,
"cess_rate": 0.00,
"cess_val": 0.00,
"total_val": 118.00,
"customer_billing_gstin": null,
"export_type": null,
"import_type": null,
"reverse_charge": null,
"is_gst_applicable": null,
"itc_details": {
"itc_type": null,
"itc_claim_percentage": null,
"cgst_total_itc": null,
"sgst_total_itc": null,
"igst_total_itc": null,
"cess_total_itc": null,
"cgst_claimed_itc": null,
"sgst_claimed_itc": null,
"igst_claimed_itc": null,
"cess_claimed_itc": null
},
"tax_details": {
"sgst": 9.00,
"cgst": 9.00,
"igst": 0.00,
"cess": 0.00,
"total": 18.00,
"taxableVal": 100.00
}
}
],
"seller": {
"name": "GSTIN1",
"gstin": "29AAACJ0988P1ZT",
"address": "",
"city": "",
"state": "KARNATAKA",
"zip_code": "560027",
"country": "",
"trade_name": null,
"legal_name": null,
"gstin_filing_frequency": null,
"gstin_status": null,
"taxpayer_type": null,
"phone_number": "",
"is_regular_gst_registration": null
},
"receiver": {
"name": "customer name",
"gstin": "29AAFCD5862R1ZR",
"address": "",
"city": "",
"state": "KARNATAKA",
"zip_code": "560027",
"country": "",
"trade_name": null,
"legal_name": null,
"gstin_filing_frequency": null,
"gstin_status": null,
"taxpayer_type": null,
"phone_number": "",
"is_regular_gst_registration": null
},
"consignee": {
"name": "customer name",
"gstin": "",
"address": "",
"city": "",
"state": null,
"zip_code": "",
"country": "",
"trade_name": null,
"legal_name": null,
"gstin_filing_frequency": null,
"gstin_status": null,
"taxpayer_type": null,
"phone_number": "",
"is_regular_gst_registration": null
},
"reverse_charge_applicable": false,
"tcs_applicable": null,
"tds_applicable": null,
"country_of_supply": null,
"recon_status": null,
"flag_for_supply": null,
"auto_populated_to_refunds": true,
"supplier_claiming_refund": null,
"return_period_from_transcation_date": null,
"doc_number": "NEWTEST001",
"document_number": "NEWTEST001",
"sub_type": "REGULAR",
"original_doc_num": null,
"doc_date": 1632960000000,
"place_of_supply_display_name": "Karnataka",
"is_amended": false,
"bank_details": {
"account_number": "123",
"bank_name": "BANK NAME",
"branch_name": "BRANCHNAME",
"ifsc_code": "IFSCCODE",
"swift_code": null
},
"custom_fields": null,
"export": {
"export_type": null,
"shipping_bill_num": null,
"shipping_port_num": "",
"shipping_bill_date": null
},
"import": {
"bill_of_entry": null,
"bill_of_entry_value": null,
"bill_of_entry_date": null,
"import_invoice_type": null,
"port_code": null
},
"ecommerce": {
"ecommerce_operator": null,
"merchant_id": null
},
"version_num": 1
}{
"errors": {
"err_1": {
"code": "404",
"message": "Invoice with id EX17_29AAFCD5862R1R_SALE_2019_NA does not exist",
"error_group_code": 0,
"error_id": 0
}
}
}{
"errors": {
"err_1": {
"code": "400",
"message": "Must be either GOODS or SERVICES",
"error_group_code": 0,
"error_id": 0
}
},
"error_sources": {
"line_items": {
"0": {
"gst_type": {
"error_refs": [
"err_1"
]
}
}
}
}
}Response Parameters
The response for this API will be a complete Invoice Object. In addition to the keys specified in the Invoice Object, you may receive the below additional keys which may be relevant for you.
Error Detail
Get Invoices
You can get multiple invoices by submitting a GET request to the GST API:
URL Query String
{{HOST}}/gst/api/v0.1/taxable_entities/{{taxable_entity_id}}/invoices?return_period=XXXXXX{{HOST}}/api/v0.1/taxable_entities/{{taxable_entity_id}}/invoices?invoice_direction=sale&return_period=XXXXXXRequest Parameter
If you receive an empty array [] in the response with HTTP status code 200, it means there are no invoices in ClearTax matching the filters specified in the query parameters.
Sample Request
https://api.clear.in/gst/api/v0.1/taxable_entities/249baf74-7392-4fa2-b3a0-685c6c7ad87e/invoices?fiscal_year=2019&invoice_direction=SALE&start=0[
{
"ref_doc_number": "reference number",
"due_date": "2021-09-30",
"paid_on": null,
"shipping_charge": null,
"invoice_status": "CREATED",
"payment_terms": null,
"notes": "CUSTOMER NOTES",
"advance_payments": [
{
"document_number": null,
"document_date": null,
"adjustment_val": null
}
],
"isd": {
"original_supplier": null,
"isd": null
},
"export_currency": null,
"provisional_itc_claimed": null,
"conversion_rate": null,
"total_val_foreign_currency": null,
"due_balance": 118.00,
"transaction_payment_status": "UNPAID",
"cgst_itc_claim_amount": 0.00,
"sgst_itc_claim_amount": 0.00,
"igst_itc_claim_amount": 0.00,
"cess_itc_claim_amount": 0.00,
"ignored_warnings": null,
"owner": "1984bd22-2a81-414a-9186-e0fea43659df",
"id": "NEWTEST001",
"transaction_date": "2021-09-30",
"return_period": "092021",
"quarterly_return_period": "152021",
"total_taxable_val": 100.00,
"total_cgst_val": 9.00,
"total_sgst_val": 9.00,
"total_igst_val": 0.00,
"total_cess_val": 0.00,
"total_val": 118.00,
"place_of_supply": "KARNATAKA",
"updated_at": "2021-09-30",
"is_amendment": false,
"amendment_detail": null,
"created_at": "2021-09-30",
"section_name": "B2B",
"fiscal_year": "2021",
"fiscal_month": "SEPTEMBER",
"fiscal_quarter": "Q2",
"total_tax_value": 18.00,
"source": "USER",
"discount_type": null,
"gst_status": "STAGED",
"gst_validation_errors": null,
"user_updated_at": "2021-09-30",
"uploaded_once": false,
"is_canceled": false,
"is_rate_inclusive_of_tax": false,
"rounding_factor": null,
"date_of_purchase": "2021-09-30",
"validate_warnings": false,
"seller_contact_id": null,
"consignee_contact_id": "eb0e179d-32f9-469d-ae80-dae5cda90dd7",
"receiver_contact_id": "eb0e179d-32f9-469d-ae80-dae5cda90dd7",
"customer_type": "UIN_REGISTERED",
"supplier_type": null,
"entity_channel_type": null,
"is_party_export": null,
"is_party_sez": null,
"is_party_consumer": null,
"is_party_unregistered": null,
"is_party_cash_ledger": null,
"is_taxable_value_overridden": null,
"total_kerala_flood_cess": null,
"differential_tax": null,
"terms_and_conditions": "Terms and conditions",
"serial_number": "NEWTEST001",
"type": "SALE",
"original_invoice_number": null,
"original_invoice_date": null,
"original_invoice_gstin": null,
"classification": "B2B",
"line_items": [
{
"tcs": {
"cgst_rate": null,
"cgst_val": null,
"sgst_rate": null,
"sgst_val": null,
"igst_rate": null,
"igst_val": null,
"cess_rate": null,
"cess_val": null
},
"tds": {
"cgst_rate": null,
"cgst_val": null,
"sgst_rate": null,
"sgst_val": null,
"igst_rate": null,
"igst_val": null,
"cess_rate": null,
"cess_val": null
},
"total_val_foreign_currency": null,
"zero_tax_category": null,
"item_code": null,
"gst_code": "8466",
"gst_type": "GOODS",
"description": "ITEM1",
"notes": null,
"unit_price": 100.00,
"unit_price_including_tax": null,
"unit_of_measurement": "BGS",
"item_id": null,
"serial_number": 1,
"quantity": 1.0,
"discount_rate": null,
"discount": null,
"taxable_val": 100.00,
"cgst_rate": 9.00,
"cgst_val": 9.00,
"sgst_rate": 9.00,
"sgst_val": 9.00,
"igst_rate": 0.00,
"igst_val": 0.00,
"cess_rate": 0.00,
"cess_val": 0.00,
"total_val": 118.00,
"customer_billing_gstin": null,
"export_type": null,
"import_type": null,
"reverse_charge": null,
"is_gst_applicable": null,
"itc_details": {
"itc_type": null,
"itc_claim_percentage": null,
"cgst_total_itc": null,
"sgst_total_itc": null,
"igst_total_itc": null,
"cess_total_itc": null,
"cgst_claimed_itc": null,
"sgst_claimed_itc": null,
"igst_claimed_itc": null,
"cess_claimed_itc": null
},
"tax_details": {
"sgst": 9.00,
"cgst": 9.00,
"igst": 0.00,
"cess": 0.00,
"total": 18.00,
"taxableVal": 100.00
}
}
],
"seller": {
"name": "GSTIN1",
"gstin": "29AAACJ0988P1ZT",
"address": "",
"city": "",
"state": "KARNATAKA",
"zip_code": "560027",
"country": "",
"trade_name": null,
"legal_name": null,
"gstin_filing_frequency": null,
"gstin_status": null,
"taxpayer_type": null,
"phone_number": "",
"is_regular_gst_registration": null
},
"receiver": {
"name": "customer name",
"gstin": "29AAFCD5862R1ZR",
"address": "",
"city": "",
"state": "KARNATAKA",
"zip_code": "560027",
"country": "",
"trade_name": null,
"legal_name": null,
"gstin_filing_frequency": null,
"gstin_status": null,
"taxpayer_type": null,
"phone_number": "",
"is_regular_gst_registration": null
},
"consignee": {
"name": "customer name",
"gstin": "",
"address": "",
"city": "",
"state": null,
"zip_code": "",
"country": "",
"trade_name": null,
"legal_name": null,
"gstin_filing_frequency": null,
"gstin_status": null,
"taxpayer_type": null,
"phone_number": "",
"is_regular_gst_registration": null
},
"reverse_charge_applicable": false,
"tcs_applicable": null,
"tds_applicable": null,
"country_of_supply": null,
"recon_status": null,
"flag_for_supply": null,
"auto_populated_to_refunds": true,
"supplier_claiming_refund": null,
"return_period_from_transcation_date": "092021",
"doc_number": "NEWTEST001",
"document_number": "NEWTEST001",
"sub_type": "REGULAR",
"original_doc_num": null,
"doc_date": 1632960000000,
"place_of_supply_display_name": "Karnataka",
"is_amended": false,
"bank_details": {
"account_number": "123",
"bank_name": "BANK NAME",
"branch_name": "BRANCHNAME",
"ifsc_code": "IFSCCODE",
"swift_code": null
},
"custom_fields": null,
"export": {
"export_type": null,
"shipping_bill_num": null,
"shipping_port_num": "",
"shipping_bill_date": null
},
"import": {
"bill_of_entry": null,
"bill_of_entry_value": null,
"bill_of_entry_date": null,
"import_invoice_type": null,
"port_code": null
},
"ecommerce": {
"ecommerce_operator": null,
"merchant_id": null
},
"version_num": 1
}
]{
"code": 400,
"message": "query param invoice_direction must be one of [SALE, PURCHASE]"
} Add an Invoice
You can add an invoice by submitting a PUT request to the GST API:
You can cancel an invoice by using the same Add invoice API except changing the request method to DELETE instead if PUT.
Max 5000 line items per invoice and max 100 invoices per request
URL Query String
{{HOST}}/gst/api/v0.1/taxable_entities/{{taxable_entity_id}}/invoices/{{invoice_id}}?source=USERRequest Parameter
Sample Request
https://api.clear.in/gst/api/v0.1/taxable_entities/249baf74-7392-4fa2-b3a0-685c6c7ad87e/invoices/NEWTEST001Sample Payload
{
"source": "USER",
"id": "NEWTEST001",
"serial_number": "NEWTEST001",
"type": "SALE",
"due_date": "2021-09-30",
"transaction_date": "2021-09-30",
"place_of_supply": "KARNATAKA",
"return_period": "092021",
"quarterly_return_period": "152021",
"reverse_charge_applicable": false,
"total_taxable_val": 100.00,
"total_cgst_val": 9,
"total_sgst_val": 9,
"total_igst_val": 0,
"total_cess_val": 0.00,
"total_val": 118.00,
"total_val_foreign_currency": null,
"line_items": [
{
"serial_number": 1,
"zero_tax_category": null,
"description": "ITEM1",
"voucher_number": "v245",
"voucher_date": "2023-06-19",
"quantity": 1.0,
"unit_price": 100.00,
"unit_of_measurement": "BGS",
"taxable_val": 100.00,
"cgst_rate": 9,
"cgst_val": 9,
"sgst_rate": 9,
"sgst_val": 9,
"igst_rate": 0,
"igst_val": 0,
"cess_rate": 0.00,
"cess_val": 0.00,
"total_val": 118.00,
"gst_code": "8466",
"gst_type": "GOODS",
"discount": null,
"tcs": {
"cgst_rate": null,
"cgst_val": null,
"sgst_rate": null,
"sgst_val": null,
"igst_rate": null,
"igst_val": null,
"cess_rate": null,
"cess_val": null
},
"tds": {
"cgst_rate": null,
"cgst_val": null,
"sgst_rate": null,
"sgst_val": null,
"igst_rate": null,
"igst_val": null,
"cess_rate": null,
"cess_val": null
},
"itc_details": {
"itc_type": null,
"itc_claim_percentage": null,
"cgst_total_itc": null,
"sgst_total_itc": null,
"igst_total_itc": null,
"cess_total_itc": null,
"cgst_claimed_itc": null,
"sgst_claimed_itc": null,
"igst_claimed_itc": null,
"cess_claimed_itc": null
}
}
],
"seller": {
"name": "GSTIN1",
"gstin": "29AAACJ0988P1ZT",
"address": "",
"city": "",
"state": "KARNATAKA",
"zip_code": "560027",
"country": "",
"phone_number": ""
},
"receiver": {
"name": "customer name",
"gstin": "29AAFCD5862R1ZR",
"address": "",
"city": "",
"state": "KARNATAKA",
"zip_code": "560027",
"country": "",
"phone_number": ""
},
"consignee": {
"name": "customer name",
"gstin": "",
"address": "",
"city": "",
"state": null,
"zip_code": "",
"country": "",
"trade_name": null,
"legal_name": null,
"phone_number": ""
},
"bank_details": {
"account_number": "123",
"bank_name": "BANK NAME",
"branch_name": "BRANCHNAME",
"ifsc_code": "IFSCCODE",
"swift_code": null
},
"export": {
"export_type": null,
"shipping_bill_num": null,
"shipping_port_num": "",
"shipping_bill_date": null
},
"import": {
"bill_of_entry": null,
"bill_of_entry_value": null,
"bill_of_entry_date": null,
"import_invoice_type": null,
"port_code": null
},
"ecommerce": {
"ecommerce_operator": null,
"merchant_id": null
},
"isd": {
"original_supplier": null,
"isd": null