ClearTax Docs
Subscribe for Updates
  • Introduction to ClearTax APIs
  • ☁️Clear Finance Cloud
    • Introduction to Clear Finance Cloud
    • Learn Clear Finance Cloud Basics
      • API client
      • Access token
      • FTP client
      • How to get Custom Upload Template ID?
    • CFC API Reference
      • Resources and Masters
        • Sale Document Line Object
        • Purchase Document Line Object
      • Generate Access Token API
      • Ingestion API
        • Ingest Documents via File
          • Get Pre-signed URL
          • Upload File to Storage
          • Trigger File Ingestion
          • Get File Ingestion Status
        • (Deprecated) Ingest Documents via JSON
    • Notifications
  • 🇮🇳GLS API
    • GLS API Reference
      • Resources and Masters
      • Advanced Ingestion API Reference
        • Get Pre-signed URL
        • Upload File to Storage
        • Create Ingestion Activity
        • Get Ingestion Activity Status
  • 🇮🇳GST API
    • Introduction to GST API
    • GST 2.0 API Reference
      • Upload Documents
    • GST FTP Magnet
  • 🇮🇳Max ITC API
    • Introduction to Max ITC API
    • Getting Started with Max ITC API
    • Max ITC API Reference
      • Resources and Masters
        • Input and output templates
        • Error Code Master
        • Learn Max ITC API Architecture
      • Max ITC APIs
        • Fetch Max ITC Configuration
        • Upload Purchase Documents
          • Ingest PR via File
          • (Deprecated) Ingest PR via JSON
        • Trigger Max ITC Workflow
        • Get Max ITC Results
        • Postman Collection
    • Max ITC FTP Magnet
  • 🇮🇳TDS API
    • Introduction to TDS API
    • TDS API Reference
      • Resources and Masters
        • Deduction Document Line Objects
        • Output Template(Error)
      • TDS APIs
        • Upload Deductions
          • Ingest Deductions via File
            • Get Pre-signed URL
            • Upload File to Storage
            • Trigger File Ingestion
            • Get File Ingestion Status
          • (Deprecated) Ingest Deductions via JSON
  • 🇮🇳E-Invoicing API
    • Introduction to E-Invoicing API
    • Learn E-Invoicing API Basics
      • How to get E-Invoicing User Auth Token?
      • How to scan the E-Invoice QR code?
      • How to add GSTIN to E-Invoicing?
        • Clear IRP API Credentials
    • Learn E-waybill API Basics
    • E-Invoicing API Reference
      • Setting up your account
      • Clear Schema
        • Generate IRN
        • Cancel IRN
        • Get E-Invoice PDF
        • Get E-Invoice by IRN
        • Generate E-Waybill by IRN
        • Generate E-Waybill for Non-IRN documents
        • Bulk Generate E-Waybill for Non-IRN documents
        • Cancel E-Waybill
        • Get E-Waybill PDF
        • Update E-Waybill Transporter ID
        • Update E-Waybill Part-B
        • Extend E-Waybill Validity
        • Generate/Regenerate Consolidated EWB
        • Get Consolidated EWB PDF
        • Initiate Multi-Vehicle E-Waybills
        • Update EWB Status from NIC
        • Download E-waybills by Others
        • Get E-Waybill Download Status
        • Get E-Waybills
        • Get latest E-Waybill status from Government
        • Generate B2C Payment QR Code
          • Generate B2C Payment QR Code (Lite)
        • Get Signed PDF
        • Sign PDF API Base 64 Encoded
        • Send an E-Invoice via Email
        • Get Invoice Details
      • Government Schema
        • Generate IRN
        • Cancel IRN
        • Get Invoice by IRN
        • Generate E-Waybill by IRN
      • Resources and Masters
        • E-Invoice Object
        • Country Code Master
        • State Code Master
        • Pincode Master
        • Pincode State Mapping Pattern
        • Port Code Master
        • Currency Code Master
        • UQC Master
        • Tax Rates
        • Error Codes
    • E-Invoicing FTP Magnet
  • 🇮🇳Invoicing API
    • Invoicing API Reference
      • Create an Invoice
      • Create Document (Non-Sale)
      • Download PDF of a Document
      • Get Document details
      • Resources and Master
        • Country Master
        • State Master
        • Pincode Master
        • Port Master
        • Currency Master
        • Unit Master
        • Document Types
        • Supply Types
  • 🇲🇾E-INVOICING MALAYSIA API
    • E-Invoicing Malaysia API Reference
      • Resources and Masters
        • Error resolution guide
        • Frequently asked questions (FAQs)
        • E-Invoice Object
      • Generate Access Token API
      • Malaysia E-Invoicing APIs
        • Generate E-Invoice for a Document
        • Status Check for Submitted E-Invoice
        • Cancel E-Invoice
        • Upload E-Invoice
        • Get Documents
        • Get E-Invoice PDF
        • Get Document via UUID
        • Delete Invoice
        • Send Bulk Email
        • Search Taxpayer Tin API
  • E-Invoicing FTP Magnet (XML)
  • E-Invoicing FTP Magnet (Excel)
  • 🇸🇦E-Invoicing KSA API
    • Introduction to E-Invoicing KSA API
    • Learn E-Invoicing KSA API Basics
      • How to get E-Invoicing KSA Auth Token?
      • How to add a VAT number to KSA E-Invoicing Account?
      • How to add Branch for existing Vat to KSA E-Invoicing Account ?
      • How to register a device for a VAT?
      • How to generate OTP on ERAD Portal?
      • How to get Print Template ID?
      • KSA E-Invoicing Integration Architecture
    • E-Invoicing KSA API Reference
      • Resources and Masters
        • E-Invoice Object
        • Error Details Object
        • Data Types
        • Code Lists
        • Common Errors and Resolution
      • Authentication
      • Generate Access Token API
      • KSA E-Invoicing APIs
        • Generate E-Invoice
          • Additional Standard (B2B) E-Invoice Examples
          • Additional Simplified (B2C) E-Invoice Examples
        • Generate E-Invoice Async
        • Generate E-Invoice via XML
        • Send Signed E-Invoice XML To ZATCA
        • Get Bulk Invoice Lite
        • Get Invoice
        • Get E-Invoice PDF
        • Get E-Invoice PDF/A-3 with PDF API
        • Register Device
        • Get PCSID Generation Status
        • Renew PCSID
        • Generate E-Invoice (Phase I)
        • Generate QR Code (Phase I)
        • Generate Device ID
        • Generate CSID and PCSID
        • Send E-Invoice via Email
        • Add Business units API
    • E-Invoicing KSA FTP Magnet
    • E-Invoicing KSA XML reporting FTP Magnet
  • 🧩Add-ons and Extensions
    • SAP Add-on
      • SAP Connectivity Checklist
        • Steps to import SSL/TLS certificates in SAP
        • Steps to check ICM settings in SAP
        • Steps to test connectivity in SAP
        • Steps to troubleshoot connectivity issues in SAP
    • Tally Add-on
  • Microsoft Dynamics 365(F&O)
  • General
    • Go-Live Cutover Activity Checklist
    • How to check DNS resolution?
    • How to check hostname reachability?
    • How to check if hostname is trusted?
    • How to get the SSL certificate of a host?
  • ⭐GST GSP API
    • Introduction to GST GSP API
    • Getting Started with GST GSP API
    • GST GSP API Reference
      • Sample API
    • Migrating from Karvy GST GSP
  • ⭐E-Waybill GSP API
    • Introduction to E-Waybill GSP API
    • Getting Started with EWB GSP API
      • How to register EWB GSP on NIC?
      • Sandbox GSTIN for EWB GSP
    • E-Waybill GSP API Reference
      • Sample API
    • Migrating from Karvy EWB GSP
  • ⭐E-Invoicing GSP API
    • Introduction to E-Invoicing GSP API
    • Getting Started with EINV GSP API
      • How to register EINV GSP on IRP?
      • Sandbox GSTIN for EINV GSP
    • E-Invoicing GSP API Reference
      • Sample API
  • Subscribe for Updates
  • 🚫(Deprecated) GST 1.0 API
    • (Deprecated) Introduction to GST API
    • (Deprecated) Learn GST API Basics
    • (Deprecated) Getting Started with GST API
      • (Deprecated) How to set up ClearTax account?
      • (Deprecated) How to authenticate API requests?
      • (Deprecated) How to upload an invoice from File?
      • (Deprecated) How to create custom import template?
    • (Deprecated) GST 1.0 API Reference
      • Taxpayer Information
      • (Deprecated) Invoices
      • (Deprecated) Bills of Supply
      • (Deprecated) Credit Debit Notes (CDN)
      • (Deprecated) Advances
      • (Deprecated) Resources and Masters
        • (Deprecated) How to read GST error response
        • (Deprecated) Unit of Measurement master
        • (Deprecated) State master
        • (Deprecated) Document Classification/Section Name master
      • (Deprecated) Items
      • (Deprecated) Contacts
      • (Deprecated) GST File Upload API Reference
  • 🚫Deprecated E-Waybill API
    • (Deprecated) Introduction to E-Waybill API
    • (Deprecated) Learn E-Waybill API Basics
    • (Deprecated) Getting Started with E-Waybill API
    • (Deprecated) E-Waybill API Reference
      • (Deprecated) Resources and Masters
        • (Deprecated) Unit Master
        • (Deprecated) State Master
        • (Deprecated) Error Master
      • (Deprecated) E-Waybill JSON API Reference
        • (Deprecated) Generating E-Waybill
        • (Deprecated) Getting E-Waybill
        • (Deprecated) Updating E-Waybill
        • (Deprecated) Extending Validity of E-Waybill
        • (Deprecated) Multi-vehicle E-Waybill
        • (Deprecated) Printing E-Waybill
        • (Deprecated) Cancelling E-Waybill
        • (Deprecated) Generating Consolidated E-Waybill
        • (Deprecated) Getting Consolidated E-Waybill
        • (Deprecated) Regenerating Consolidated E-Waybill
        • (Deprecated) Printing Consolidated E-Waybill
      • (Deprecated) E-Waybill File Upload API Reference
        • (Deprecated) Creating or Updating Documents
        • (Deprecated) Getting Upload Status
        • (Deprecated) Getting Upload Validation
        • (Deprecated) Getting Upload History
        • (Deprecated) Rate Limiting & Best Practices
    • (Deprecated) E-Waybill FTP Magnet
Powered by GitBook
On this page
  • ClearTax User Account
  • Business ID
  • Taxable Entity ID
  • Documents
  • Different ways to send data to ClearTax GST
  • JSON Upload API
  • File Upload API
  • Templates or Formats
  • Government Templates
  • ClearTax Templates
  • E-commerce Templates
  • Custom Templates

Was this helpful?

  1. (Deprecated) GST 1.0 API

(Deprecated) Learn GST API Basics

Previous(Deprecated) Introduction to GST APINext(Deprecated) Getting Started with GST API

Last updated 2 years ago

Was this helpful?

ClearTax GST API is your gateway for introducing GST compliance in your app. Start here to learn about the core components available for you to build with, and to get some guidance on how to start thinking about designing apps with ClearTax GST API. This is intended to be an overview of the core platform components that are available to help you better understand the APIs.

ClearTax User Account

Every user who registers with ClearTax GST gets an account associated with the email ID used for signing up. A registered user can add any number of Businesses/Clients and GSTINs under their account and manage all of them from the same login. A user can log in to ClearTax GST with the email ID and password or can interact with ClearTax GST programmatically with an authentication token.

Business ID

Every user account on ClearTax GST can have multiple businesses or clients. A business can be a group of GSTINs related to the same real world legal entity or person. Every time a user creates a new business or client in their account, ClearTax will assign an ID to that business or client, commonly referred to as Business ID. This ID is unique to that business or client, and cannot be used by any other user unless the admin user gives access to it.

Whenever you send an API request to get or update business level information, you will include the Business ID in the URL of the request as a path parameter to identify which business you are referring to.

You can get the Business ID of your Business by logging in to your ClearTax account and selecting the "Business Name/PAN" as shown in the highlighted part of URL in the below image:

Taxable Entity ID

Every business or client on ClearTax GST can have multiple GSTINs. Every time a user creates a new GSTIN under any of his businesses or clients, ClearTax will assign an ID to that user’s instance of that GSTIN (taxable entity), commonly referred to as Taxable Entity ID. This ID is unique to that taxable entity, and cannot be used by any other user unless the admin user gives access to it.

Whenever you send an API request to get or update GSTIN level information, you will include the Taxable Entity ID in the URL of the request as a path parameter to identify which GSTIN you are referring to.

You can get the Taxable Entity ID of your GSTIN by logging in to your ClearTax account and selecting the "GSTIN" as shown in the highlighted part of URL in the below image:

Documents

A document is an official record issued by a seller, buyer or transporter involved in a business transaction. ClearTax GST supports the following types of documents:

Outward Documents

Inward Documents

Sales Invoices

Purchase Invoices

Outward Bills of Supply

Inward Bills of Supply

Outward Credit Debit Notes

Inward Credit Debit Notes

Advance Receipts

Advance Payments

Different ways to send data to ClearTax GST

ClearTax GST provides 2 ways to send data:

  1. JSON Upload API

  2. File Upload API

JSON Upload API

The JSON Upload API gives you the ability to upload your documents to ClearTax GST with real-time validation check. With this API, you will be able to upload the following types of documents from your app in JSON format:

  1. Sales or Purchase Invoices

  2. Outward or Inward Bills of Supply

  3. Advance Receipts or Payments

  4. Outward or Inward Credit Debit Notes

  5. Delivery Challans

  6. Estimates

Using this API gets your documents validated in real time. Once a request containing documents is sent, the JSON Upload API will return response with validations that can be used to update the source database and inform the business user to fix and resend. This lets you build more tightly integrated apps, removing the necessity of business user logging into ClearTax Portal for fixing errors.

File Upload API

The File Upload API gives you the ability to upload your documents to ClearTax GST with staged validation checks. With this API, you will be able to upload following types of documents from your local file system in CSV or Excel format:

  1. Sales Invoices or Outward Bills of Supply

  2. Purchase Invoices or Inward Bills of Supply

  3. Advance Receipts

  4. Advance Payments

  5. Outward Credit Debit Notes

  6. Inward Credit Debit Notes

Using this API gets your documents staged in ClearTax database, removing the overhead of correcting validation errors at the time of sending the documents. This lets business user send documents faster and in more efficient manner. Once a file containing documents is uploaded, the File Upload API will return an activity_id that can be used for future requests to check upload status and validation errors.

Templates or Formats

ClearTax GST supports uploading of 4 types of templates (also called formats).

  1. Government Templates

  2. ClearTax Templates

  3. E-commerce Templates

  4. Custom Templates

Government Templates

These templates are created by Government (GSTN). Some offline accounting software like Tally and Busy have options to export data in this format. So if your app uses the same format, you can use these templates to generate the Excel or CSV to be imported to ClearTax. In case of Excel, Government Templates support different segments (B2B, B2CS, etc) in separate sheets of the same workbook and hence can be sent to ClearTax in single request. In case of CSV, each document type (Invoice, CDN, etc) and segment needs to be created as a separate file and sent in a separate request by specifying the data_type and vendor_type as request parameter.

ClearTax Templates

These templates are created by ClearTax and used by most of our customers. If you are new to GST file formats, we recommend these templates for your app as they are simpler and more flexible. Whether you use Excel or CSV, each document type can be sent in a separate file by specifying the data_type as request parameter. In case of Excel, ClearTax Template supports only the first sheet in the workbook.

E-commerce Templates

In addition to Government templates and ClearTax templates, ClearTax also supports E-commerce templates of the following:

  • Amazon Sellers

    • Sales by sellers from Indian states

    • Sales by sellers from Union Territories

  • Flipkart Sellers

    • Flipkart Sales Invoice

    • Flipkart Sales CDNs (Outward Credit Debit Notes)

  • Paytm Sellers

    • Paytm Sales Invoice

    • Paytm Sales CDNs (Outward Credit Debit Notes)

Custom Templates

Custom templates are handled in the same way as ClearTax templates. The benefit here is, you will be able to specify your own headers and map it to the header required by ClearTax. When you create a new custom template, you will receive a custom_mapper_id which you will have to specify as request parameter when uploading files to ClearTax GST.

🚫
(Deprecated) GST File Upload API Reference
(Deprecated) How to create custom import template?
(Deprecated) How to set up ClearTax account?
(Deprecated) How to authenticate API requests?