(Deprecated) Credit Debit Notes (CDN)

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.

When goods supplied are returned or when there is a revision in the invoice value due to goods (or services) not being up to the mark or extra goods being issued a Debit Note or Credit Note is issued.

Resource Objects

Credit debit note Object

The request and response objects are same as invoice objects except the following.

Parameter

Type

Field Validation

Description

cdn_status

String

Is the document created?

cdn_type

String

[CREDIT, DEBIT]

Mandatory.

original_invoice_serial_num

String

Optional. Original invoice document number against which this CDN is raised.

original_invoice_date

String

Optional. Original invoice date.

original_note_number

String

Conditional. Original note number, mandatory if you are amending a CDN

original_invoice_type

String

[SALE, PURCHASE]

Mandatory. Original Invoice Type.

original_invoice_classification

String

[B2B, B2BUR, B2BA, B2CL, B2CS, EXPORT, IMPORT, ISD, COMPOSITE, B2B_EXPORT, NIL_BOS, B2C]

Mandatory. Original Invoice Classification.

original_note_date

String

Conditional. Original note date, mandatory if you are amending a CDN

note_num

String

Mandatory. CDN number

transaction_date

String

Mandatory. Credit note issued date

itc_type

String

Optional. [ NOT_SELECTED, INELIGIBLE, INPUT, CAPITAL_GOOD, INPUT_SERVICE, BLANK ]

Get a CDN

You can get a CDN by submitting a GET request to the GST API:

URL Query String

{{HOST}}/gst/api/v0.1/taxable_entities/{{taxable_entity_id}}/cdns/{{cdn_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.

cdn_id

Path

String

Required. Unique CDN ID.

Sample Request

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

Sample Response

{
    "ignored_warnings": null,
    "owner": "1984bd22-2a81-414a-9186-e0fea43659df",
    "id": "NEWTESTCDN001",
    "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-10-01",
    "is_amendment": false,
    "amendment_detail": null,
    "created_at": "2021-10-01",
    "section_name": "CDN",
    "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-10-01",
    "uploaded_once": false,
    "is_canceled": false,
    "is_rate_inclusive_of_tax": false,
    "rounding_factor": null,
    "due_balance": null,
    "transaction_payment_status": 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",
    "original_invoice_classification": "B2B",
    "export_type": null,
    "import_type": null,
    "return_period_from_transcation_date": null,
    "linked_sales_invoice_category": null,
    "linked_purchase_invoice_category": null,
    "inward_supply_type": null,
    "note_num": "NEWTESTCDN001",
    "original_note_number": null,
    "original_note_gstin": null,
    "original_note_date": null,
    "original_invoice_serial_num": "NEWTEST001",
    "original_invoice_date": "2021-09-30",
    "original_invoice_type": "SALE",
    "reason": null,
    "cdn_type": "CREDIT",
    "differential_val": 100.00,
    "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
            },
            "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,
    "pre_gst": null,
    "recon_status": null,
    "flag_for_supply": null,
    "auto_populated_to_refunds": true,
    "supplier_claiming_refund": null,
    "notes": "CUSTOMER NOTES",
    "cdn_status": "CREATED",
    "export_currency": null,
    "conversion_rate": null,
    "total_val_foreign_currency": null,
    "country_of_supply": null,
    "provisional_itc_claimed": null,
    "cgst_itc_claim_amount": null,
    "sgst_itc_claim_amount": null,
    "igst_itc_claim_amount": null,
    "cess_itc_claim_amount": null,
    "linked_transaction_client_id": "NEWTEST001",
    "linked_transaction_type": "INVOICE",
    "ref_doc_number": null,
    "doc_number": "NEWTESTCDN001",
    "document_number": "NEWTESTCDN001",
    "original_doc_num": null,
    "doc_date": 1632960000000,
    "place_of_supply_display_name": "Karnataka",
    "is_amended": false,
    "bank_details": null,
    "custom_fields": null,
    "export": null,
    "import": null,
    "ecommerce": {
        "ecommerce_operator": null,
        "merchant_id": null
    },
    "version_num": 2
}

GET CDNs

You can get multiple CDNs by submitting a GET request to the GST API:

URL Query String

{{HOST}}/gst/api/v0.1/taxable_entities/{{taxable_entity_id}}/cdns?return_period=MMYYYY

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/cdns?id=NEWTESTCDN001&invoice_direction=sale

Sample Response

[
    {
        "ignored_warnings": null,
        "owner": "1984bd22-2a81-414a-9186-e0fea43659df",
        "id": "NEWTESTCDN001",
        "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-10-01",
        "is_amendment": false,
        "amendment_detail": null,
        "created_at": "2021-10-01",
        "section_name": "CDN",
        "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-10-01",
        "uploaded_once": false,
        "is_canceled": false,
        "is_rate_inclusive_of_tax": false,
        "rounding_factor": null,
        "due_balance": null,
        "transaction_payment_status": 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",
        "original_invoice_classification": "B2B",
        "export_type": null,
        "import_type": null,
        "return_period_from_transcation_date": "092021",
        "linked_sales_invoice_category": null,
        "linked_purchase_invoice_category": null,
        "inward_supply_type": null,
        "note_num": "NEWTESTCDN001",
        "original_note_number": null,
        "original_note_gstin": null,
        "original_note_date": null,
        "original_invoice_serial_num": "NEWTEST001",
        "original_invoice_date": "2021-09-30",
        "original_invoice_type": "SALE",
        "reason": null,
        "cdn_type": "CREDIT",
        "differential_val": 100.00,
        "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
                },
                "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,
        "pre_gst": null,
        "recon_status": null,
        "flag_for_supply": null,
        "auto_populated_to_refunds": true,
        "supplier_claiming_refund": null,
        "notes": "CUSTOMER NOTES",
        "cdn_status": "CREATED",
        "export_currency": null,
        "conversion_rate": null,
        "total_val_foreign_currency": null,
        "country_of_supply": null,
        "provisional_itc_claimed": null,
        "cgst_itc_claim_amount": 0.00,
        "sgst_itc_claim_amount": 0.00,
        "igst_itc_claim_amount": 0.00,
        "cess_itc_claim_amount": 0.00,
        "linked_transaction_client_id": "NEWTEST001",
        "linked_transaction_type": "INVOICE",
        "ref_doc_number": null,
        "doc_number": "NEWTESTCDN001",
        "document_number": "NEWTESTCDN001",
        "original_doc_num": null,
        "doc_date": 1632960000000,
        "place_of_supply_display_name": "Karnataka",
        "is_amended": false,
        "bank_details": null,
        "custom_fields": null,
        "export": null,
        "import": null,
        "ecommerce": {
            "ecommerce_operator": null,
            "merchant_id": null
        },
        "version_num": 2
    }
]

Add a CDN

You can add a CDN by submitting a PUT request to the GST API:

URL Query String

{{HOST}}/gst/api/v0.1/taxable_entities/{{taxable_entity_id}}/cdns/{{cdn_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.

cdn_id

Path

String

Required. Unique CDN ID.

Sample Request

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

Sample Request Payload

{
    "source": "USER",
    "id": "NEWTESTCDN001",
    "note_num": "NEWTESTCDN001",
    "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",
            "notes": null,
            "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
        }
    ],
    "cdn_type": "CREDIT",
    "original_invoice_serial_num": "NEWTEST001",
    "original_invoice_date": "2021-09-30",
    "original_note_number": null,
    "original_invoice_type": "SALE",
    "original_invoice_classification": "B2B",
    "original_note_date": null,
    "tds_applicable": null,
    "country_of_supply": 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

{
    "ignored_warnings": null,
    "owner": "1984bd22-2a81-414a-9186-e0fea43659df",
    "id": "NEWTESTCDN001",
    "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-10-01",
    "is_amendment": false,
    "amendment_detail": null,
    "created_at": "2021-10-01",
    "section_name": "CDN",
    "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-10-01",
    "uploaded_once": false,
    "is_canceled": false,
    "is_rate_inclusive_of_tax": false,
    "rounding_factor": null,
    "due_balance": null,
    "transaction_payment_status": 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",
    "original_invoice_classification": "B2B",
    "export_type": null,
    "import_type": null,
    "return_period_from_transcation_date": null,
    "linked_sales_invoice_category": null,
    "linked_purchase_invoice_category": null,
    "inward_supply_type": null,
    "note_num": "NEWTESTCDN001",
    "original_note_number": null,