(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
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": 

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.

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