(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

{
    "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
}

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

[
    {
        "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
    }
]

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

{
    "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

{
    "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": 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": "eb0e179d-32f9-469d-ae80-dae5cda90dd7",
    "receiver_contact_id": "eb0e179d-32f9-469d-ae80-dae5cda90dd7",
    "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": 0
}

Add Bills of Supply

You can add multiple bills 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

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.

Sample Request

https://api.clear.in/gst/api/v0.1/taxable_entities/249baf74-7392-4fa2-b3a0-685c6c7ad87e/billofsupply

Sample Payload

[
    {
        "source": "USER",