Marketplace IRN + TCS APIs — Seller-Aware e-Invoicing, Credit-Note Automation, Aggregator TCS Reporting
One API for IRN + reverse-IRN + TCS-aware GSTR-1 line entries. Bulk 1,000/call. Idempotent.
Build your marketplace IRN flow in a weekend — Postman + Node SDK quickstart
The problem
For Tech Lead at a marketplace platform (consumer marketplace, B2B marketplace, hyperlocal). Sellers don't issue invoices — you do, on their behalf. Returns trigger credit notes. Aggregator TCS makes the GSTR-1 messier. You need IRN + reverse-IRN + TCS reporting tied to a single transaction.
How WhiteBooks solves it
- Per-seller IRN generation in a single bulk call: each line item carries its own seller GSTIN, you get back one IRN per seller per order.
- Returns automation: einvoice.cancel_irn within 24h, einvoice.generate_credit_note after — idempotent, both reflected in the GSTR-1 TCS section.
- Section 52 TCS handling: collect the right TCS rate per seller, report in GSTR-1 with the marketplace-operator block.
- Section 9(5) deemed-supplier coverage: for food-delivery / hyperlocal categories where the platform is the deemed supplier, we route the full e-Invoice through the platform GSTIN automatically.
Key APIs
| Tool / Endpoint | What it does | Path |
|---|---|---|
einvoice.generate_irn_bulk | Per-seller breakdown | /api/v1/bulk-generate-irn |
einvoice.cancel_irn | Returns within 24h | /api/v1/cancel-irn |
gst.file_gstr1 | With TCS + aggregator section | /api/v1/gstr1/file |
reconciliation | Marketplace settlement vs IRN | /api/v1/reconciliation |
Compliance angle
Section 52 TCS (1% deduction), e-Commerce operator obligations, returns reconciliation within 24h cancellation window, Section 9(5) deemed-supplier classification (food-delivery, hyperlocal), GSTR-8 (TCS) monthly filing.
Live numbers
- Throughput: 1,000 invoices / EWBs per single API call (bulk mode).
- Latency: p50 87 ms IRN, p95 312 ms — live at whitebooks.in/status.
- Uptime: 99.994% rolling 30-day; 99.99% SLA with credits on Enterprise.
- Region: Mumbai + Hyderabad active-active; KSA in
me-south-1.
Sample architecture
Sample customer pattern
A consumer marketplace with 30,000+ sellers routes every order through WhiteBooks bulk IRN. A single bulk-generate call processes 1,000 orders across 600+ sellers; the per-line response carries seller-specific IRN and signed QR. Returns within 24h are cancelled programmatically; credit notes after are generated and reflected in GSTR-1.
Frequently asked questions
Can we process IRN for 600 different sellers in one bulk call?
Yes. einvoice.generate_irn_bulk accepts up to 1,000 invoices and each can carry its own seller GSTIN. The response is per-line: you get 1,000 IRNs (or per-line error codes for the few that fail). Idempotency keys ensure retries are safe.
How does Section 52 TCS reporting work?
When you file GSTR-8 (monthly TCS return), our gst.file_gstr8 endpoint accepts the per-seller TCS collected and computed amounts. The TCS section of GSTR-1 is auto-populated from the bulk IRN responses so reconciliation between IRN and TCS is zero-touch.
What about Section 9(5) deemed-supplier (food-delivery, hyperlocal)?
When the platform is the deemed supplier under Sec 9(5), the IRN is issued under the platform GSTIN and the seller is shown as the back-end fulfiller. Our gateway handles the classification per category code (HSN) so your order flow doesn't branch.
How are returns handled inside the 24h cancellation window?
Call einvoice.cancel_irn within 24h with reason code "01" (returned) and remarks. After 24h, generate a credit-note IRN via einvoice.generate_credit_note against the original IRN. Both flows update the GSTR-1 TCS section automatically.
Can we reconcile marketplace settlement against IRN?
Yes. The reconciliation endpoint takes your settlement file (per-seller payout) and matches against IRN responses. Mismatches (settlement without IRN, IRN without settlement) are flagged for finance review.
Get started
Related use cases: Logistics · Retail · Manufacturing · Fintech · Pharma · E-Commerce · SaaS · CA Firms · ERP Providers
Reference: All APIs hub · /docs/gst · /docs/einvoice · /docs/eway · Pricing · Architecture · Status · Changelog