Links

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