(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.
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)
| |
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. |
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
|
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 |
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 | | |
zip_code | string | | Party zip code |
country | string | | Party Country |
phone_number | string | | Party phone number |
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 |
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
|
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. |
Parameter | Type | Field Validation | Description |
ecommerce_operator | Object | NA | |
merchant_id | String | NA | Optional |
Parameter | Type | Field Validation | Description |
document_number | String | NA | Optional. |
document_date | String | YYYY-MM-DD | Optional. |
adjustment_val | Number | NA | Optional. |
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 |
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 |
Parameter | Type | Field Validation | Description |
label | String | NA | Label of custom field |
value | String | NA | Value of Custom field |
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=USER
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 |
https://api.clear.in/gst/api/v0.1/taxable_entities/249baf74-7392-4fa2-b3a0-685c6c7ad87e/invoices/123abc?source=USER
200
404
400
{
"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":