(Deprecated) Invoices
Last updated
Last updated
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.
SGST and CGST rate should be Zero for export invoices
Learn more about ITC and its types here
You can get an invoice by submitting a GET request to the GST API:
{{HOST}}/gst/api/v0.1/taxable_entities/{{taxable_entity_id}}/invoices/{{invoice_id}}?source=USERhttps://api.clear.in/gst/api/v0.1/taxable_entities/249baf74-7392-4fa2-b3a0-685c6c7ad87e/invoices/123abc?source=USER{
"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"
]
}
}
}
}
}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.
You can get multiple invoices by submitting a GET request to the GST API:
{{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=XXXXXXIf 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.
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]"
} 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
{{HOST}}/gst/api/v0.1/taxable_entities/{{taxable_entity_id}}/invoices/{{invoice_id}}?source=USERhttps://api.clear.in/gst/api/v0.1/taxable_entities/249baf74-7392-4fa2-b3a0-685c6c7ad87e/invoices/NEWTEST001{