(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

Parameter	Type	Field Validation	Description
source	String	enum: "USER", "GOVERNMENT"	Mandatory. "USER" for documents uploaded from your software. "GOVERNMENT" for documents downloaded from GSTN.
id	String	NA	Mandatory. Unique number across all fiscal years for the GSTIN.
serial_number	string	Maxlength: 16	Mandatory. Invoice number that is unique across the current fiscal year.
type	String	enum: "SALE", "PURCHASE"	Mandatory. "SALE" for outward documents. "PURCHASE" for inward documents.
transaction_date	String	format: YYYY-MM-DD	Mandatory. Supplier Invoice Date in case of Sales Invoice. Vendor Invoice date in the case of Purchase Invoice.
date_of_purchase	string	YYYY-MM-dd format	Optional. Transaction Date as per books in the case of Purchase Invoice.
place_of_supply	string	String(Max length:30)	Mandatory. Place of supply state code. Refer state master.
return_period	string	format: MMYYYY	Optional. If not provided, return period will be auto computed based on transaction date.
quarterly_return_period	string	format: MMYYYY	Optional. If not provided, quarterly return period will be auto computed based on transaction date. MM will be 13 for 1st Quarter. 14 for 2nd quarter, 15 for 3rd Quarter and 16 for 4th quarter.
reverse_charge_applicable	boolean	Default: False	Optional. Is reverse charge applicable?
total_val	number	NA	Optional. If not provided, invoice total value will be auto computed based on the line item total values.
total_val_foreign_currency	number	NA	Optional. If not provided, invoice total value in foreign currency will be auto computed based on line item total values in foreign currency.
line_items	array	NA	Mandatory. Array of line item objects explained below.
seller	object	NA	Mandatory. Instance of party object explained below.
receiver	object	NA	Mandatory. Instance of party object explained below.
consignee	object	NA	Optional. Instance of party object explained below.
bank_details	object	NA	Optional.
export	object	NA	Optional.
import	object	NA	Optional.
ecommerce	object	NA	Optional.
isd	object	NA	Optional.
advance_payments	array	NA	Optional. Array of advance payment objects.
custom_fields	array	NA	Optional. Array of custom field objects.
is_amendment	boolean	NA	Conditional. Required only if this is an amendment invoice.
is_amended	boolean	NA	Conditional. Required only if this is an amended invoice.
amendment_detail	string	Enum: "AMENDED", "AMENDMENT", "NOT_AMENDED"	Conditional. Required only if this is an amendment or amended invoice.
original_invoice_number	string	Alphanumeric (Max length:16)	Optional.Original invoice number
original_invoice_date	string	string (DD-MM-YYYY)	Optional.Original invoice date
original_invoice_gstin	string	Alphanumeric with 15 characters	Optional.GSTIN of Customer in Original Invoice
ref_doc_number	string	NA	Optional. Example: PO number
country_of_supply	string	NA	Optional.
customer_type	string	[COMPOSITION, UIN_REGISTERED]	Optional.If the customer is a Composition dealer or has a UIN registeration
supplier_type	string	[COMPOSITION]	Optional.If the supplier is composition dealer
supplier_claiming_refund	string	NA	Optional.
auto_populated_to_refunds	string	NA	Optional.
tcs_applicable	Boolean	TRUE/FALSE	Optional.if TCS on Sales is deducted by Govt. bodies as per GST rules
tds_applicable	Boolean	TRUE/FALSE	Optional.if TDS on Sales is deducted by Govt. bodies as per GST rules
flag_for_supply	Boolean	TRUE/FALSE	Optional.
rounding_factor	Number	NA	Optional. Value by which totalValue has been rounded
terms_and_conditions	string	NA	Optional.
notes	string	NA	Optional. Item notes
created_at	date	NA	Read only.
updated_at	date	NA	Read only.
is_canceled	boolean	NA	Read only.
classification	string	CT auto classifies based on other data points . Acceptable ENUMS = ['B2B', 'B2BUR', 'B2BA', 'B2CL', 'B2CS', 'EXPORT', 'IMPORT', 'ISD', 'COMPOSITE', 'B2B_EXPORT', 'NIL_BOS', 'B2C']	Read only.

Line item object

Parameter	Type	Field Validation	Description
zero_tax_category	String	ENUM: 'NILRATED', 'EXEMPTED', 'NONGSTSUPPLY', 'SUPPLYFROMCOMPOSITIONDEALER', 'UINHOLDER'	Optional.If the goods or services is Nil Rated, Exempted, or NonGST supply All tax rates and tax amounts should be zero if this is true
description	String	String (Max length:180)	Optional. Description of the item
quantity	Number	Decimal(15, 2)	Conditional mandatory in case of goods. Quantity of Item
serial_number	Number	NA	Optional. This value will be auto computed if not provided.
unit_price	number	Decimal(15, 2)	Conditional mandatory in case of goods. Item Price
unit_of_measurement	String	String (Max length:20)	Conditional mandatory in case of goods. Unit of Measurement Refer Unit master
total_val	Number	NA	Optional. This value will be auto computed if not provided.
taxable_val	Number	Decimal(15, 2)	Mandatory. Taxable value of Goods or Service as per invoice
sgst_rate	Number	Decimal(15, 2) Enter rate values without percentage % sign	Yes if applicable. Should be equal to cgst rate.
sgst_val	Number	Decimal(15, 2)	SGST Amount
cess_rate	Number	Decimal(15, 2) Enter rate values without percentage % sign	Yes if applicable. Cess tax rate.
cess_val	Number	Decimal(15, 2)	CESS Amount
cgst_rate	Number	Decimal(15, 2) Enter rate values without percentage % sign	Yes if applicable. Should be equal to sgst rate.
cgst_val	Number	Decimal(15, 2)	CGST Amount
igst_rate	Number	Decimal(15, 2) Enter rate values without percentage % sign	Yes if applicable. IGST tax rate
igst_val	Number	Decimal(15, 2)	IGST Amount
gst_type	String	ENUM: 'GOODS', 'SERVICES'	Optional. Identifier if Goods or Services
gst_code	String	Alphanumeric (Max length:8)	Optional.HSN or SAC of Goods or Services as per Invoice line items
discount	Number	Decimal(15, 2)	Optional.Total value of discount for an item
tcs	Object	NA	Optional.Tax Collected at Source (TCS) rates and values to be listed
tds	Object	NA	Optional.Tax Deducted at Source (TCS) rates and values to be listed
itc_details	Object	NA	Optional.Total or claimed Input Tax Credit (ITC) values to be listed

Party Object

Parameter	Type	Field Validation	Description
name	string	String (Max length:90)	Party Billing Name
gstin	string	Alphanumeric with 15 characters	Conditional. In case the invoice type is "SALE", gstin is mandatory for seller object. In case the invoice type is "PURCHASE", gstin is mandatory for receiver object. If receiver do not have GSTIN please provide 'NRP'(non registered person). Receiver GSTIN is mandatory for Deemed or SEZ export or B2B Sale from Bonded WH
address	string		Party address
city	string		Party city
state	string		Party state. Refer State Master
zip_code	string		Party zip code
country	string		Party Country
phone_number	string		Party phone number

Bank details object

Parameter	Type	Field Validation	Description
account_number	String		Bank account number
bank_name	String		Name of the Bank
branch_name	String		Name of the Branch of Bank
ifsc_code	String	Max character: 11 Have to be alpha-numeric	IFSC Code of the Branch
swift_code	String		Swift Code of the Bank

Export object

SGST and CGST rate should be Zero for export invoices

Parameter	Type	Field Validation	Description
export_type	String	ENUM ['DEEMED', 'SEZ_WITHOUT_IGST', 'SEZ_WITH_IGST', 'EXPORT_WITH_IGST', 'EXPORT_UNDER_BOND', 'SALE_FROM_BONDED_WH', 'REGULAR']	Mandatory in case of exports or supplies made to SEZ
shipping_bill_num	Integer	Numeric (Max length :7 )	Conditional. Not required for Service. Shipping Bill No. or Bill of Export No
shipping_port_num	String	Alphanumeric (Max length:6)	Conditional. Not required for Service. Shipping Port code - 6 digit .
shipping_bill_date	String	string (DD-MM-YYYY)	Mandatory. Shipping Bill Date. or Bill of Export Date

Import object

Parameter	Type	Field Validation	Description
bill_of_entry	String	min length = 7 max length = 7	Conditional. Not required for Service.
bill_of_entry_value	Number	NA	Optional
bill_of_entry_date	String	YYYY-MM-DD	Mandatory
import_invoice_type	String	ENUM ['GOODS', 'GOODS_FROM_SEZ', 'SERVICE_FROM_SEZ', 'SERVICES']	Mandatory
port_code	String	6 character	Conditional. Not required for Service.

E-commerce object

Parameter	Type	Field Validation	Description
ecommerce_operator	Object	NA	Optional. Refer Party Object for fields
merchant_id	String	NA	Optional

Advance payment object

Parameter	Type	Field Validation	Description
document_number	String	NA	Optional.
document_date	String	YYYY-MM-DD	Optional.
adjustment_val	Number	NA	Optional.

TCS and TDS object

Parameter	Type	Field Validation	Description
cgst_rate	Number	Decimal(15, 2) Enter rate values without percentage % sign	if applicable. CGST tax rate
cgst_val	Number	Decimal(15, 2)	CGST value
igst_rate	Number	Decimal(15, 2) Enter rate values without percentage % sign	if applicable. IGST tax rate
igst_val	Number	Decimal(15, 2)	IGST value
sgst_rate	Number	Decimal(15, 2) Enter rate values without percentage % sign	if applicable. SGST tax rate
sgst_val	Number	Decimal(15, 2)	SGST value

ITC details object

Parameter	Type	Field Validation	Description
itc_type	String	ENUM - ['NOT_SELECTED', 'INELIGIBLE', 'INPUT', 'CAPITAL_GOOD', 'INPUT_SERVICE', 'BLANK'],	if applicable. CGST tax rate
itc_claim_percentage	Number	Decimal(15, 2) Enter rate values without percentage % sign	ITC claim percentage
cgst_total_itc	Number	Decimal(15, 2)	CGST Total
sgst_total_itc	Number	Decimal(15, 2)	SGST Total
igst_total_itc	Number	Decimal(15, 2)	IGST Total
cess_total_itc	Number	Decimal(15, 2)	CESS Total
cgst_claimed_itc	Number	Decimal(15, 2)	CGST claimed
sgst_claimed_itc	Number	Decimal(15, 2)	SGST claimed
igst_claimed_itc	Number	Decimal(15, 2)	IGST claimed
cess_claimed_itc	Number	Decimal(15, 2)	CESS claimed

Learn more about ITC and its types here

Custom field object

Parameter	Type	Field Validation	Description
label	String	NA	Label of custom field
value	String	NA	Value of Custom field

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

Parameters	Parameters Type	Type	Description
X-Cleartax-Auth-Token	Header	String	Mandatory. The auth token generated from ClearTax user id and password.
taxable_entity_id	Path	String	Required. This is the unique ID associated with the GSTIN in your account.
invoice_id	Path	String	Required. Unique Transaction ID.
source	query	String	USER, GOVERNMENT

Sample Request

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

Sample Response

200

{
    "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
}

404

{
    "errors": {
        "err_1": {
            "code": "404",
            "message": "Invoice with id EX17_29AAFCD5862R1R_SALE_2019_NA does not exist",
            "error_group_code": 0,
            "error_id": 0
        }
    }
}

400

{
    "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.

Parameter	Type	Description
invoice_status	String	Invoice status can be ['DRAFT', 'CREATED', 'APPROVED', 'PAID'],
owner	String	Owner ID of the user Example: 249bf74-7392-4fa2-b3a0-685c6c7ad87e
gst_status	String	Transaction GST filing status, managed by CT ['STAGED', 'SYNCED', 'FILED']
gst_validation_errors	Array	Validation errors reported by govt on SAVE/SUBMIT
updated_at	String	Transaction updated date in YYYY-MM-dd format
user_updated_at	String	Transaction user updated date in YYYY-MM-dd format
created_at	String	Transaction created date in YYYY-MM-dd format

Error Detail

Parameter	Type	Description
error_code	String	Error Code
message	String	Error message
error_sources	String	Displays under which object and field the error is in.

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

Parameters	Parameters Type	Type	Description
X-Cleartax-Auth-Token	Header	String	Mandatory. The auth token generated from ClearTax user id and password.
taxable_entity_id	Path	String	Required. This is the unique ID associated with the GSTIN in your account.
source	Query	String	USER, GOVERNMENT
return_period	Query	String	Return period in the format MMYYYY
start_date	Query	String	Start date by which you need to filter
end_date	Query	String	End date by which you need to filter
seller_gstin	Query	Array	Seller GSTIN number
buyer_gstin	Query	Array	Buyer GSTIN number
invoice_direction	Query	ENUM	Mandatory. SALE, PURCHASE
id	Query	Array	Unique Transaction ID
is_ammended	Query	Boolean	TRUE, FALSE
invoice_type	Query	Array	B2B , B2BUR , B2BA , B2CL , B2CS , EXPORT , IMPORT , ISD , COMPOSITE , B2B_EXPORT
start	Query	String	Default: 0 /used for pagination
limit	Query	String	Default: 20 / number of invoices to limit in the response

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

200

[
    {
        "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
    }
]

400

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

Request Parameter

Parameters	Parameters Type	Type	Description
X-Cleartax-Auth-Token	Header	String	Mandatory. The auth token generated from ClearTax user id and password.
taxable_entity_id	Path	String	Required. This is the unique ID associated with the GSTIN in your account.
invoice_id	Path	String	Required. Unique Transaction ID.
source	Query	String	USER
invoice	Body	Object	Required. Invoice data in Invoice Object.

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
    },
    "advance_payments": [
        {
            "document_number": null,
            "document_date": null,
            "adjustment_val": null
        }
    ],
    "custom_fields": null,
    "is_amendment": false,
    "amendment_detail": null,
    "is_amended": false,
    "original_invoice_number": null,
    "original_invoice_date": null,
    "original_invoice_gstin": null,
    "ref_doc_number": "reference number",
    "date_of_purchase": "2021-09-30",
    "tcs_applicable": null,
    "tds_applicable": null,
    "country_of_supply": null,
    "customer_type": "UIN_REGISTERED",
    "supplier_type": null,
    "auto_populated_to_refunds": true,
    "supplier_claiming_refund": null,
    "rounding_factor": null,
    "flag_for_supply": null,
    "notes": "CUSTOMER NOTES",
    "terms_and_conditions": "Terms and conditions"
}

201

{
    "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",
            "voucher_number": "v245",
            "voucher_date": "2023-06-19",
            "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
}

400

{
    "errors": {
        "err_1": {
            "code": "BAD_REQUEST_GLOBAL",
            "message": "Total taxable value should be 100.00 instead of 10.0",
            "error_group_code": 0,
            "error_id": 0,
            "severity": "ERROR"
        }
    },
    "error_sources": {
        "total_taxable_val": {
            "error_refs": [
                "err_1"
            ]
        }
    }
}

Add Invoices

You can add multiple invoices by submitting a PUT request to the GST API:

URL Query String

{{HOST}}/gst/api/v0.1/taxable_entities/{{taxable_entity_id}}/invoicesv2

Request Parameter

Parameters	Parameters Type	Type	Description
taxable_entity_id	Path	String	Required. This is the unique ID associated with the GSTIN in your account.
X-Cleartax-Auth-Token	Header	String	Mandatory. The auth token generated from ClearTax user id and password.

Sample Request

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

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
        },
        "advance_payments": [
            {
                "document_number": null,
                "document_date": null,
                "adjustment_val": null
            }
        ],
        "custom_fields": null,
        "is_amendment": false,
        "amendment_detail": null,
        "is_amended": false,
        "original_invoice_number": null,
        "original_invoice_date": null,
        "original_invoice_gstin": null,
        "ref_doc_number": "reference number",
        "date_of_purchase": "2021-09-30",
        "tcs_applicable": null,
        "tds_applicable": null,
        "country_of_supply": null,
        "customer_type": "UIN_REGISTERED",
        "supplier_type": null,
        "auto_populated_to_refunds": true,
        "supplier_claiming_refund": null,
        "rounding_factor": null,
        "flag_for_supply": null,
        "notes": "CUSTOMER NOTES",
        "terms_and_conditions": "Terms and conditions"
    }
]

Sample Response

This endpoint will send error details inside 'errorResponse' object with status code 200.

200

[
    {
        "id": "NEWTEST001",
        "status": true,
        "data": {
            "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": null,
            "is_amendment": false,
            "amendment_detail": null,
            "created_at": null,
            "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": null,
            "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": null,
            "receiver_contact_id": null,
            "customer_type": null,
            "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",
                    "voucher_number": "v245",
                    "voucher_date": "2023-06-19",
                    "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": 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": 0
        },
        "errorResponse": null,
        "warningResponse": null
    }
]

200(error response)

...

"errorResponse": {
            "errors": {
                "err_1": {
                    "code": "BAD_REQUEST_ATTR",
                    "message": "60000 must be between 0.0  and 100.0.",
                    "error_group_code": 0,
                    "error_id": 0,
                    "severity": "ERROR"
                },
                "err_2": {
                    "code": "BAD_REQUEST_ATTR",
                    "message": "Please use a GST compliant tax rate - [0, 0.05, 0.125, 0.5, 0.75, 1.5, 2.5, 3.75, 6, 9, 14]",
                    "error_group_code": 12,
                    "error_id": 12,
                    "severity": "ERROR"
                }
            },
            "error_sources": {
                "line_items": {
                    "0": {
                        "sgst_rate": {
                            "error_refs": [
                                "err_1",
                                "err_2"
                            ]
                        }
                    }
                }
            }
        },
        
...

Canceling or Deleting an Invoice

Canceling an Invoice

You can cancel a sales invoice by submitting a DELETE request to the GST API where the request URL and headers remain the same as in Add an Invoice section.

Note: The status of the invoice will be "cancelled" when this action is performed.

You can cancel ONLY a sales invoice. A purchase invoice cannot be canceled but only be deleted.

Deleting an Invoice

You can delete a purchase invoice by submitting a DELETE request to the GST API where the request URL and headers remain same as in Add an Invoice section. In addition to the following request parameter.

Request Parameter

Parameters	Parameters Type	Type	Description
delete	query	Boolean	Mandatory, if you want to delete a document. Value: true