(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.
Resource Objects
Bill of supply Object
The request and response objects are same as invoice objects except the following.
Parameter
Type
Field Validation
Description
supply_num
String
​
Mandatory. Document Number
Get a Bill of Supply
You can get a bill of supply by submitting a GET request to the GST API:
URL Query String
{{HOST}}/gst/api/v0.1/taxable_entities/{{taxable_entity_id}}/billofsupply/{{bill_of_supply_id}}
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.
bill_of_supply_id
Path
String
Required. Unique bill of supply ID.
Sample Request
https://api.clear.in/gst/api/v0.1/taxable_entities/249baf74-7392-4fa2-b3a0-685c6c7ad87e/billofsupply/NEWTESTBOS001
Sample Response
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
        }
    }
}
Get Bills of Supply
You can get multiple bill of supply's by submitting a GET request to the GST API:
URL Query String
{{HOST}}/gst/api/v0.1/taxable_entities/{{taxable_entity_id}}/billofsupply?fiscal_year=2020&invoice_direction=SALE
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.
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
Sample Request
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.
Sample Response
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]"
}
Add a Bill of Supply
You can add a bill of supply by submitting a PUT request to the GST API:
URL Query String
{{HOST}}/gst/api/v0.1/taxable_entities/{{taxable_entity_id}}/billofsupply/{{bill_of_supply_id}}
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.
bill_of_supply_id
Path
String
Required. Unique bill of supply ID.
Sample Request
https://api.clear.in/gst/api/v0.1/taxable_entities/249baf74-7392-4fa2-b3a0-685c6c7ad87e/billofsupply/NEWTESTBOS001
Sample Payload
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"
}
Sample Response
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"
Parameter	Type	Field Validation	Description
supply_num	String		Mandatory. Document Number
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.