(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=USER

Request Parameter

Sample Request

https://api.clear.in/gst/api/v0.1/taxable_entities/249baf74-7392-4fa2-b3a0-685c6c7ad87e/invoices/123abc?source=USER

Sample 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
}

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=XXXXXX

Request 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
    }
]

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=USER

Request Parameter

Sample Request

https://api.clear.in/gst/api/v0.1/taxable_entities/249baf74-7392-4fa2-b3a0-685c6c7ad87e/invoices/NEWTEST001

Sample 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