(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
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
Sample Response
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
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
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
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
Sample Payload
Add Invoices
You can add multiple invoices by submitting a PUT request to the GST API:
URL Query String
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
Sample Payload
Sample Response
This endpoint will send error details inside 'errorResponse' object with status code 200.
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 |
Last updated