# (Deprecated) Invoices {% hint style="warning" %} **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](/cleartax-docs/gst-api/gst-2.0-api-reference.md) instead. {% endhint %} 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](/cleartax-docs/gst-api-1/gst-api-reference/resources-and-masters/place-is-supply-master.md). | | 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](https://cleartax.gitbook.io/cleartax-for-developers/gst-api/gst-api-reference/resources-and-masters/place-is-supply-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 {% hint style="info" %} SGST and CGST rate should be Zero for export invoices {% endhint %} | 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](/cleartax-docs/gst-api-1/gst-api-reference/invoices.md#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 | {% hint style="info" %} Learn more about ITC and its types [here](https://cleartax.in/s/gst-input-tax-credit) {% endhint %} ### 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 {% tabs %} {% tab title="200" %} ```javascript { "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": 1.0, "discount_rate": null, "discount": null, "taxable_val": 100.00, "cgst_rate": 9.00, "cgst_val": 9.00, "sgst_rate": 9.00, "sgst_val": 9.00, "igst_rate": 0.00, "igst_val": 0.00, "cess_rate": 0.00, "cess_val": 0.00, "total_val": 118.00, "customer_billing_gstin": null, "export_type": null, "import_type": null, "reverse_charge": null, "is_gst_applicable": 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 }, "tax_details": { "sgst": 9.00, "cgst": 9.00, "igst": 0.00, "cess": 0.00, "total": 18.00, "taxableVal": 100.00 } } ], "seller": { "name": "GSTIN1", "gstin": "29AAACJ0988P1ZT", "address": "", "city": "", "state": "KARNATAKA", "zip_code": "560027", "country": "", "trade_name": null, "legal_name": null, "gstin_filing_frequency": null, "gstin_status": null, "taxpayer_type": null, "phone_number": "", "is_regular_gst_registration": null }, "receiver": { "name": "customer name", "gstin": "29AAFCD5862R1ZR", "address": "", "city": "", "state": "KARNATAKA", "zip_code": "560027", "country": "", "trade_name": null, "legal_name": null, "gstin_filing_frequency": null, "gstin_status": null, "taxpayer_type": null, "phone_number": "", "is_regular_gst_registration": null }, "consignee": { "name": "customer name", "gstin": "", "address": "", "city": "", "state": null, "zip_code": "", "country": "", "trade_name": null, "legal_name": null, "gstin_filing_frequency": null, "gstin_status": null, "taxpayer_type": null, "phone_number": "", "is_regular_gst_registration": null }, "reverse_charge_applicable": false, "tcs_applicable": null, "tds_applicable": null, "country_of_supply": null, "recon_status": null, "flag_for_supply": null, "auto_populated_to_refunds": true, "supplier_claiming_refund": null, "return_period_from_transcation_date": null, "doc_number": "NEWTEST001", "document_number": "NEWTEST001", "sub_type": "REGULAR", "original_doc_num": null, "doc_date": 1632960000000, "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, "export": { "export_type": null, "shipping_bill_num": null, "shipping_port_num": "", "shipping_bill_date": null }, "import": { "bill_of_entry": null, "bill_of_entry_value": null, "bill_of_entry_date": null, "import_invoice_type": null, "port_code": null }, "ecommerce": { "ecommerce_operator": null, "merchant_id": null }, "version_num": 1 } ``` {% endtab %} {% tab title="404" %} ```javascript { "errors": { "err_1": { "code": "404", "message": "Invoice with id EX17_29AAFCD5862R1R_SALE_2019_NA does not exist", "error_group_code": 0, "error_id": 0 } } } ``` {% endtab %} {% tab title="400" %} ```javascript { "errors": { "err_1": { "code": "400", "message": "Must be either GOODS or SERVICES", "error_group_code": 0, "error_id": 0 } }, "error_sources": { "line_items": { "0": { "gst_type": { "error_refs": [ "err_1" ] } } } } } ``` {% endtab %} {% endtabs %} #### Response Parameters The response for this API will be a complete [Invoice Object](/cleartax-docs/gst-api-1/gst-api-reference/invoices.md#invoice-object). In addition to the keys specified in the Invoice Object, you may receive the below additional keys which may be relevant for you. | **Parameter** | Type | Description | | ----------------------- | ------ | --------------------------------------------------------------------------- | | invoice\_status | String | Invoice status can be \['DRAFT', 'CREATED', 'APPROVED', 'PAID'], | | owner | String | Owner ID of the user Example: 249bf74-7392-4fa2-b3a0-685c6c7ad87e | | gst\_status | String | Transaction GST filing status, managed by CT \['STAGED', 'SYNCED', 'FILED'] | | gst\_validation\_errors | Array | Validation errors reported by govt on SAVE/SUBMIT | | updated\_at | String | Transaction updated date in YYYY-MM-dd format | | user\_updated\_at | String | Transaction user updated date in YYYY-MM-dd format | | created\_at | String | Transaction created date in YYYY-MM-dd format | #### Error Detail | **Parameter** | Type | Description | | -------------- | ------ | ------------------------------------------------------ | | error\_code | String | Error Code | | message | String | Error message | | error\_sources | String | Displays under which object and field the error is in. | ## Get Invoices You can get multiple invoices by submitting a **GET** request to the GST API: #### URL Query String ``` {{HOST}}/gst/api/v0.1/taxable_entities/{{taxable_entity_id}}/invoices?return_period=XXXXXX{{HOST}}/api/v0.1/taxable_entities/{{taxable_entity_id}}/invoices?invoice_direction=sale&return_period=XXXXXX ``` #### 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. | | 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 | Mandatory. SALE, PURCHASE | | id | Query | Array | Unique Transaction ID | | is\_ammended | Query | Boolean | TRUE, FALSE | | invoice\_type | Query | Array | B2B , B2BUR , B2BA , B2CL , B2CS , EXPORT , IMPORT , ISD , COMPOSITE , B2B\_EXPORT | | start | Query | String | Default: 0 /used for pagination | | limit | Query | String | Default: 20 / number of invoices to limit in the response | {% hint style="info" %} 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. {% endhint %} #### Sample Request ``` https://api.clear.in/gst/api/v0.1/taxable_entities/249baf74-7392-4fa2-b3a0-685c6c7ad87e/invoices?fiscal_year=2019&invoice_direction=SALE&start=0 ``` {% tabs %} {% tab title="200" %} ```javascript [ { "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": 0.00, "sgst_itc_claim_amount": 0.00, "igst_itc_claim_amount": 0.00, "cess_itc_claim_amount": 0.00, "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": 1.0, "discount_rate": null, "discount": null, "taxable_val": 100.00, "cgst_rate": 9.00, "cgst_val": 9.00, "sgst_rate": 9.00, "sgst_val": 9.00, "igst_rate": 0.00, "igst_val": 0.00, "cess_rate": 0.00, "cess_val": 0.00, "total_val": 118.00, "customer_billing_gstin": null, "export_type": null, "import_type": null, "reverse_charge": null, "is_gst_applicable": 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 }, "tax_details": { "sgst": 9.00, "cgst": 9.00, "igst": 0.00, "cess": 0.00, "total": 18.00, "taxableVal": 100.00 } } ], "seller": { "name": "GSTIN1", "gstin": "29AAACJ0988P1ZT", "address": "", "city": "", "state": "KARNATAKA", "zip_code": "560027", "country": "", "trade_name": null, "legal_name": null, "gstin_filing_frequency": null, "gstin_status": null, "taxpayer_type": null, "phone_number": "", "is_regular_gst_registration": null }, "receiver": { "name": "customer name", "gstin": "29AAFCD5862R1ZR", "address": "", "city": "", "state": "KARNATAKA", "zip_code": "560027", "country": "", "trade_name": null, "legal_name": null, "gstin_filing_frequency": null, "gstin_status": null, "taxpayer_type": null, "phone_number": "", "is_regular_gst_registration": null }, "consignee": { "name": "customer name", "gstin": "", "address": "", "city": "", "state": null, "zip_code": "", "country": "", "trade_name": null, "legal_name": null, "gstin_filing_frequency": null, "gstin_status": null, "taxpayer_type": null, "phone_number": "", "is_regular_gst_registration": null }, "reverse_charge_applicable": false, "tcs_applicable": null, "tds_applicable": null, "country_of_supply": null, "recon_status": null, "flag_for_supply": null, "auto_populated_to_refunds": true, "supplier_claiming_refund": null, "return_period_from_transcation_date": "092021", "doc_number": "NEWTEST001", "document_number": "NEWTEST001", "sub_type": "REGULAR", "original_doc_num": null, "doc_date": 1632960000000, "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, "export": { "export_type": null, "shipping_bill_num": null, "shipping_port_num": "", "shipping_bill_date": null }, "import": { "bill_of_entry": null, "bill_of_entry_value": null, "bill_of_entry_date": null, "import_invoice_type": null, "port_code": null }, "ecommerce": { "ecommerce_operator": null, "merchant_id": null }, "version_num": 1 } ] ``` {% endtab %} {% tab title="400" %} ```javascript { "code": 400, "message": "query param invoice_direction must be one of [SALE, PURCHASE]" } ``` {% endtab %} {% endtabs %} ## Add an Invoice You can add an invoice by submitting a **PUT** request to the GST API: {% hint style="info" %} You can cancel an invoice by using the same Add invoice API except changing the request method to **DELETE** instead if **PUT**. {% endhint %} {% hint style="success" %} Max 5000 line items per invoice and max 100 invoices per request {% endhint %} #### 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 | | invoice | Body | Object | Required. Invoice data in [Invoice Object](/cleartax-docs/gst-api-1/gst-api-reference/invoices.md#resource-objects). | #### Sample Request ``` https://api.clear.in/gst/api/v0.1/taxable_entities/249baf74-7392-4fa2-b3a0-685c6c7ad87e/invoices/NEWTEST001 ``` #### Sample Payload ```javascript { "source": "USER", "id": "NEWTEST001", "serial_number": "NEWTEST001", "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": 9, "total_sgst_val": 9, "total_igst_val": 0, "total_cess_val": 0.00, "total_val": 118.00, "total_val_foreign_currency": null, "line_items": [ { "serial_number": 1, "zero_tax_category": null, "description": "ITEM1", "voucher_number": "v245", "voucher_date": "2023-06-19", "quantity": 1.0, "unit_price": 100.00, "unit_of_measurement": "BGS", "taxable_val": 100.00, "cgst_rate": 9, "cgst_val": 9, "sgst_rate": 9, "sgst_val": 9, "igst_rate": 0, "igst_val": 0, "cess_rate": 0.00, "cess_val": 0.00, "total_val": 118.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 }, "export": { "export_type": null, "shipping_bill_num": null, "shipping_port_num": "", "shipping_bill_date": null }, "import": { "bill_of_entry": null, "bill_of_entry_value": null, "bill_of_entry_date": null, "import_invoice_type": null, "port_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": "UIN_REGISTERED", "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" } ``` {% tabs %} {% tab title="201" %} ```javascript { "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", "voucher_number": "v245", "voucher_date": "2023-06-19", "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": 9.00, "cgst_val": 9.00, "sgst_rate": 9.00, "sgst_val": 9.00, "igst_rate": 0.00, "igst_val": 0.00, "cess_rate": 0.00, "cess_val": 0.00, "total_val": 118.00, "customer_billing_gstin": null, "export_type": null, "import_type": null, "reverse_charge": null, "is_gst_applicable": 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 }, "tax_details": { "sgst": 9.00, "cgst": 9.00, "igst": 0.00, "cess": 0.00, "total": 18.00, "taxableVal": 100.00 } } ], "seller": { "name": "GSTIN1", "gstin": "29AAACJ0988P1ZT", "address": "", "city": "", "state": "KARNATAKA", "zip_code": "560027", "country": "", "trade_name": null, "legal_name": null, "gstin_filing_frequency": null, "gstin_status": null, "taxpayer_type": null, "phone_number": "", "is_regular_gst_registration": null }, "receiver": { "name": "customer name", "gstin": "29AAFCD5862R1ZR", "address": "", "city": "", "state": "KARNATAKA", "zip_code": "560027", "country": "", "trade_name": null, "legal_name": null, "gstin_filing_frequency": null, "gstin_status": null, "taxpayer_type": null, "phone_number": "", "is_regular_gst_registration": null }, "consignee": { "name": "customer name", "gstin": "", "address": "", "city": "", "state": null, "zip_code": "", "country": "", "trade_name": null, "legal_name": null, "gstin_filing_frequency": null, "gstin_status": null, "taxpayer_type": null, "phone_number": "", "is_regular_gst_registration": null }, "reverse_charge_applicable": false, "tcs_applicable": null, "tds_applicable": null, "country_of_supply": null, "recon_status": null, "flag_for_supply": null, "auto_populated_to_refunds": true, "supplier_claiming_refund": null, "return_period_from_transcation_date": null, "doc_number": "NEWTEST001", "document_number": "NEWTEST001", "sub_type": "REGULAR", "original_doc_num": null, "doc_date": 1632960000000, "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, "export": { "export_type": null, "shipping_bill_num": null, "shipping_port_num": "", "shipping_bill_date": null }, "import": { "bill_of_entry": null, "bill_of_entry_value": null, "bill_of_entry_date": null, "import_invoice_type": null, "port_code": null }, "ecommerce": { "ecommerce_operator": null, "merchant_id": null }, "version_num": 1 } ``` {% endtab %} {% tab title="400" %} ```javascript { "errors": { "err_1": { "code": "BAD_REQUEST_GLOBAL", "message": "Total taxable value should be 100.00 instead of 10.0", "error_group_code": 0, "error_id": 0, "severity": "ERROR" } }, "error_sources": { "total_taxable_val": { "error_refs": [ "err_1" ] } } } ``` {% endtab %} {% endtabs %} ## Add Invoices You can add multiple invoices by submitting a **PUT** request to the GST API: #### URL Query String ``` {{HOST}}/gst/api/v0.1/taxable_entities/{{taxable_entity_id}}/invoicesv2 ``` #### 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. | | X-Cleartax-Auth-Token | Header | String | Mandatory. The auth token generated from ClearTax user id and password. | #### Sample Request ``` https://api.clear.in/gst/api/v0.1/taxable_entities/249baf74-7392-4fa2-b3a0-685c6c7ad87e/invoicesv2 ``` #### Sample Payload ```javascript [ { "source": "USER", "id": "NEWTEST001", "serial_number": "NEWTEST001", "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": 9, "total_sgst_val": 9, "total_igst_val": 0, "total_cess_val": 0.00, "total_val": 118.00, "total_val_foreign_currency": null, "line_items": [ { "serial_number": 1, "zero_tax_category": null, "description": "ITEM1", "voucher_number": "v245", "voucher_date": "2023-06-19", "quantity": 1.0, "unit_price": 100.00, "unit_of_measurement": "BGS", "taxable_val": 100.00, "cgst_rate": 9, "cgst_val": 9, "sgst_rate": 9, "sgst_val": 9, "igst_rate": 0, "igst_val": 0, "cess_rate": 0.00, "cess_val": 0.00, "total_val": 118.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 }, "export": { "export_type": null, "shipping_bill_num": null, "shipping_port_num": "", "shipping_bill_date": null }, "import": { "bill_of_entry": null, "bill_of_entry_value": null, "bill_of_entry_date": null, "import_invoice_type": null, "port_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": "UIN_REGISTERED", "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 {% hint style="info" %} This endpoint will send error details inside 'errorResponse' object with status code 200. {% endhint %} {% tabs %} {% tab title="200" %} ```javascript [ { "id": "NEWTEST001", "status": true, "data": { "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": null, "is_amendment": false, "amendment_detail": null, "created_at": null, "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": null, "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", "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", "voucher_number": "v245", "voucher_date": "2023-06-19", "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": 9.00, "cgst_val": 9.00, "sgst_rate": 9.00, "sgst_val": 9.00, "igst_rate": 0.00, "igst_val": 0.00, "cess_rate": 0.00, "cess_val": 0.00, "total_val": 118.00, "customer_billing_gstin": null, "export_type": null, "import_type": null, "reverse_charge": null, "is_gst_applicable": 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 }, "tax_details": { "sgst": 9.00, "cgst": 9.00, "igst": 0.00, "cess": 0.00, "total": 18.00, "taxableVal": 100.00 } } ], "seller": { "name": "GSTIN1", "gstin": "29AAACJ0988P1ZT", "address": "", "city": "", "state": "KARNATAKA", "zip_code": "560027", "country": "", "trade_name": null, "legal_name": null, "gstin_filing_frequency": null, "gstin_status": null, "taxpayer_type": null, "phone_number": "", "is_regular_gst_registration": null }, "receiver": { "name": "customer name", "gstin": "29AAFCD5862R1ZR", "address": "", "city": "", "state": "KARNATAKA", "zip_code": "560027", "country": "", "trade_name": null, "legal_name": null, "gstin_filing_frequency": null, "gstin_status": null, "taxpayer_type": null, "phone_number": "", "is_regular_gst_registration": null }, "consignee": { "name": "customer name", "gstin": "", "address": "", "city": "", "state": null, "zip_code": "", "country": "", "trade_name": null, "legal_name": null, "gstin_filing_frequency": null, "gstin_status": null, "taxpayer_type": null, "phone_number": "", "is_regular_gst_registration": null }, "reverse_charge_applicable": false, "tcs_applicable": null, "tds_applicable": null, "country_of_supply": null, "recon_status": null, "flag_for_supply": null, "auto_populated_to_refunds": true, "supplier_claiming_refund": null, "return_period_from_transcation_date": null, "doc_number": "NEWTEST001", "document_number": "NEWTEST001", "sub_type": "REGULAR", "original_doc_num": null, "doc_date": 1632960000000, "place_of_supply_display_name": "Karnataka", "is_amended": false, "bank_details": null, "custom_fields": null, "export": { "export_type": null, "shipping_bill_num": null, "shipping_port_num": "", "shipping_bill_date": null }, "import": { "bill_of_entry": null, "bill_of_entry_value": null, "bill_of_entry_date": null, "import_invoice_type": null, "port_code": null }, "ecommerce": { "ecommerce_operator": null, "merchant_id": null }, "version_num": 0 }, "errorResponse": null, "warningResponse": null } ] ``` {% endtab %} {% tab title="200(error response)" %} ``` ... "errorResponse": { "errors": { "err_1": { "code": "BAD_REQUEST_ATTR", "message": "60000 must be between 0.0 and 100.0.", "error_group_code": 0, "error_id": 0, "severity": "ERROR" }, "err_2": { "code": "BAD_REQUEST_ATTR", "message": "Please use a GST compliant tax rate - [0, 0.05, 0.125, 0.5, 0.75, 1.5, 2.5, 3.75, 6, 9, 14]", "error_group_code": 12, "error_id": 12, "severity": "ERROR" } }, "error_sources": { "line_items": { "0": { "sgst_rate": { "error_refs": [ "err_1", "err_2" ] } } } } }, ... ``` {% endtab %} {% endtabs %} ## Canceling or Deleting an Invoice #### Canceling an Invoice You can cancel a sales invoice by submitting a **`DELETE`** request to the GST API where the request URL and headers remain the same as in [Add an Invoice](https://cleartax.gitbook.io/cleartax-for-developers/gst-api/gst-api-reference/json-api-reference/invoices#add-an-invoice) section. {% hint style="info" %} Note: The status of the invoice will be "cancelled" when this action is performed. {% endhint %} {% hint style="danger" %} You can cancel ONLY a sales invoice. A purchase invoice cannot be canceled but only be deleted. {% endhint %} #### Deleting an Invoice You can delete a purchase invoice by submitting a **`DELETE`** request to the GST API where the request URL and headers remain same as in [Add an Invoice](https://cleartax.gitbook.io/cleartax-for-developers/gst-api/gst-api-reference/json-api-reference/invoices#add-an-invoice) section. In addition to the following request parameter. #### Request Parameter | Parameters | Parameters Type | Type | Description | | ---------- | --------------- | ------- | --------------------------------------------------------- | | delete | query | Boolean | Mandatory, if you want to delete a document. Value: true | --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.cleartax.in/cleartax-docs/gst-api-1/gst-api-reference/invoices.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.