(Deprecated) Bills of Supply
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.
A bill of supply is a document of transaction that is different from a normal tax invoice. These bills do not contain any tax amount, as input tax cannot be charged in these cases.
Parameter | Type | Field Validation | Description |
supply_num | String | | Mandatory. Document Number |
You can get a bill of supply by submitting a GET request to the GST API:
{{HOST}}/gst/api/v0.1/taxable_entities/{{taxable_entity_id}}/billofsupply/{{bill_of_supply_id}}
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. |
bill_of_supply_id | Path | String | Required. Unique bill of supply ID. |
https://api.clear.in/gst/api/v0.1/taxable_entities/249baf74-7392-4fa2-b3a0-685c6c7ad87e/billofsupply/NEWTESTBOS001
200
404
{
"supply_num": "NEWTESTBOS001",
"type": "SALE",
"ref_doc_number": "reference number",
"due_date": "2021-09-30",
"seller": {
"name": "GSTIN1",
"gstin": "29AAACJ0988P1ZT",
"address": "",
"city": "",
"state": "KARNATAKA",
"zip_code": "560027",
"country": null,
"trade_name": null,
"legal_name": null,
"gstin_filing_frequency": null,
"gstin_status": null,
"taxpayer_type": null,
"phone_number": null,
"is_regular_gst_registration": null
},
"receiver": {
"name": "customer name",
"gstin": "29AAFCD5862R1ZR",
"address": "",
"city": "",
"state": "KARNATAKA",
"zip_code": "560027",
"country": null,
"trade_name": null,
"legal_name": null,
"gstin_filing_frequency": null,
"gstin_status": null,
"taxpayer_type": null,
"phone_number": null,
"is_regular_gst_registration": null
},
"consignee": {
"name": "customer name",
"gstin": "",
"address": "",
"city": "",
"state": null,
"zip_code": "",
"country": null,
"trade_name": null,
"legal_name": null,
"gstin_filing_frequency": null,
"gstin_status": null,
"taxpayer_type": null,
"phone_number": null,
"is_regular_gst_registration": null
},
"nil_rated_val": 100.00,
"exempted_val": null,
"non_gst_supply_val": null,
"supply_from_composition_dealer_val": null,
"notes": "CUSTOMER NOTES",
"due_balance": null,
"transaction_payment_status": null,
"line_items": [
{
"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": 0.00,
"cgst_val": 0.00,
"sgst_rate": 0.00,
"sgst_val": 0.00,
"igst_rate": 0.00,
"igst_val": 0.00,
"cess_rate": 0.00,
"cess_val": 0.00,
"total_val": 100.00,
"customer_billing_gstin": null,
"export_type": null,
"import_type": null,
"reverse_charge": null,
"is_gst_applicable": null,
"zero_tax_category": "NILRATED",
"tax_details": {
"sgst": 0.00,
"cgst": 0.00,
"igst": 0.00,
"cess": 0.00,
"total": 0.00,
"taxableVal": 100.00
}
}
],
"ignored_warnings": null,
"owner": "1984bd22-2a81-414a-9186-e0fea43659df",
"id": "NEWTESTBOS001",
"transaction_date": "2021-09-30",
"return_period": "092021",
"quarterly_return_period": "152021",
"total_taxable_val": 100.00,
"total_cgst_val": 0.00,
"total_sgst_val": 0.00,
"total_igst_val": 0.00,
"total_cess_val": 0.00,
"total_val": 100.00,
"place_of_supply": "KARNATAKA",
"updated_at": "2021-10-01",
"is_amendment": false,
"amendment_detail": null,
"created_at": "2021-10-01",
"section_name": "NIL",
"fiscal_year": "2021",
"fiscal_month": "SEPTEMBER",
"fiscal_quarter": "Q2",
"total_tax_value": 0.00,
"source": "USER",
"discount_type": null,
"gst_status": "NA",
"gst_validation_errors": null,
"user_updated_at": "2021-10-01",
"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",
"document_number": "NEWTESTBOS001",
"original_doc_num": null,
"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,
"version_num": 1
}
{
"errors": {
"err_1": {
"code": "404",
"message": "Bill of supply with id INV-tes does not exist.",
"error_group_code": 0,
"error_id": 0
}
}
}
You can get multiple bill of supply's by submitting a GET request to the GST API:
{{HOST}}/gst/api/v0.1/taxable_entities/{{taxable_entity_id}}/billofsupply?fiscal_year=2020&invoice_direction=SALE
Parameters | Parameters Type | Type | Description |
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 | SALE, PURCHASE |
id | Query | Array | Unique Transaction ID |
is_ammended | Query | Boolean | TRUE, FALSE |
start | Query | String | Default: 0 /used for pagination |
limit | Query | String | Default: 20 / number of invoices to limit in the response |
https://api.clear.in/gst/api/v0.1/taxable_entities/249baf74-7392-4fa2-b3a0-685c6c7ad87e/billofsupply?fiscal_year=2020&invoice_direction=SALE
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.
200
400
[
{
"supply_num": "NEWTESTBOS001",
"type": "SALE",
"ref_doc_number": "reference number",
"due_date": "2021-09-30",
"seller": {
"name": "GSTIN1",
"gstin": "29AAACJ0988P1ZT",
"address": "",
"city": "",
"state": "KARNATAKA",
"zip_code": "560027",
"country": null,
"trade_name": null,
"legal_name": null,
"gstin_filing_frequency": null,
"gstin_status": null,
"taxpayer_type": null,
"phone_number": null,
"is_regular_gst_registration": null
},
"receiver": {
"name": "customer name",
"gstin": "29AAFCD5862R1ZR",
"address": "",
"city": "",
"state": "KARNATAKA",
"zip_code": "560027",
"country": null,
"trade_name": null,
"legal_name": null,
"gstin_filing_frequency": null,
"gstin_status": null,
"taxpayer_type": null,
"phone_number": null,
"is_regular_gst_registration": null
},
"consignee": {
"name": "customer name",
"gstin": "",
"address": "",
"city": "",
"state": null,
"zip_code": "",
"country": null,
"trade_name": null,
"legal_name": null,
"gstin_filing_frequency": null,
"gstin_status": null,
"taxpayer_type": null,
"phone_number": null,
"is_regular_gst_registration": null
},
"nil_rated_val": 100.00,
"exempted_val": null,
"non_gst_supply_val": null,
"supply_from_composition_dealer_val": null,
"notes": "CUSTOMER NOTES",
"due_balance": null,
"transaction_payment_status": null,
"line_items": [
{
"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": 0.00,
"cgst_val": 0.00,
"sgst_rate": 0.00,
"sgst_val": 0.00,
"igst_rate": 0.00,
"igst_val": 0.00,
"cess_rate": 0.00,
"cess_val": 0.00,
"total_val": 100.00,
"customer_billing_gstin": null,
"export_type": null,
"import_type": null,
"reverse_charge": null,
"is_gst_applicable": null,
"zero_tax_category": "NILRATED",
"tax_details": {
"sgst": 0.00,
"cgst": 0.00,
"igst": 0.00,
"cess": 0.00,
"total": 0.00,
"taxableVal": 100.00
}
}
],
"ignored_warnings": null,
"owner": "1984bd22-2a81-414a-9186-e0fea43659df",
"id": "NEWTESTBOS001",
"transaction_date": "2021-09-30",
"return_period": "092021",
"quarterly_return_period": "152021",
"total_taxable_val": 100.00,
"total_cgst_val": 0.00,
"total_sgst_val": 0.00,
"total_igst_val": 0.00,
"total_cess_val": 0.00,
"total_val": 100.00,
"place_of_supply": "KARNATAKA",
"updated_at": "2021-10-01",
"is_amendment": false,
"amendment_detail": null,
"created_at": "2021-10-01",
"section_name": "NIL",
"fiscal_year": "2021",
"fiscal_month": "SEPTEMBER",
"fiscal_quarter": "Q2",
"total_tax_value": 0.00,
"source": "USER",
"discount_type": null,
"gst_status": "NA",
"gst_validation_errors": null,
"user_updated_at": "2021-10-01",
"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",
"document_number": "NEWTESTBOS001",
"original_doc_num": null,
"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,
"version_num": 1
}
]
{
"code": 400,
"message": "query param invoice_direction must be one of [SALE, PURCHASE]"
}
You can add a bill of supply by submitting a PUT request to the GST API:
{{HOST}}/gst/api/v0.1/taxable_entities/{{taxable_entity_id}}/billofsupply/{{bill_of_supply_id}}
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. |
bill_of_supply_id | Path | String | Required. Unique bill of supply ID. |
https://api.clear.in/gst/api/v0.1/taxable_entities/249baf74-7392-4fa2-b3a0-685c6c7ad87e/billofsupply/NEWTESTBOS001
Payload
{
"source": "USER",
"id": "NEWTESTBOS001",
"supply_num": "NEWTESTBOS001",
"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": 0,
"total_sgst_val": 0,
"total_igst_val": 0,
"total_cess_val": 0.00,
"total_val": 100.00,
"total_val_foreign_currency": null,
"line_items": [
{
"serial_number": 1,
"zero_tax_category": "NILRATED",
"description": "ITEM1",
"notes": null,
"quantity": 1.0,
"unit_price": 100.00,
"unit_of_measurement": "BGS",
"taxable_val": 100.00,
"cgst_rate": 0,
"cgst_val": 0,
"sgst_rate": 0,
"sgst_val": 0,
"igst_rate": 0,
"igst_val": 0,
"cess_rate": 0.00,
"cess_val": 0.00,
"total_val": 100.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
},
"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": null,
"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
400
{
"supply_num": "NEWTESTBOS001",
"type": "SALE",
"ref_doc_number": "reference number",
"due_date": "2021-09-30",
"seller": {
"name": "GSTIN1",
"gstin": "29AAACJ0988P1ZT",
"address": "",
"city": "",
"state": "KARNATAKA",
"zip_code": "560027",
"country": null,
"trade_name": null,
"legal_name": null,
"gstin_filing_frequency": null,
"gstin_status": null,
"taxpayer_type": null,
"phone_number": null,
"is_regular_gst_registration": null
},
"receiver": {
"name": "customer name",
"gstin": "29AAFCD5862R1ZR",
"address": "",
"city": "",
"state": "KARNATAKA",
"zip_code": "560027",
"country": null,
"trade_name": null,
"legal_name": null,
"gstin_filing_frequency": null,
"gstin_status": null,
"taxpayer_type": null,
"phone_number": null,
"is_regular_gst_registration": null
},
"consignee": {
"name": "customer name",
"gstin": "",
"address": "",
"city": "",
"state": null,
"zip_code": "",
"country": null,
"trade_name": null,
"legal_name": null,
"gstin_filing_frequency": null,
"gstin_status": null,
"taxpayer_type": null,
"phone_number": null,
"is_regular_gst_registration": null
},
"nil_rated_val": 100.00,
"exempted_val": null,
"non_gst_supply_val": null,
"supply_from_composition_dealer_val": null,
"notes": "CUSTOMER NOTES",
"due_balance": 100.00,
"transaction_payment_status": "UNPAID",
"line_items": [
{
"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": 0.00,
"cgst_val"