Real-Time IRN APIs for Retail POS — Sub-100 ms IRN, GSTR-1 Auto-Filing at Counter Throughput
p50 87 ms IRN. Sub-100 ms typical. Designed for in-store POS round-trip without queuing the customer.
Drop a single POST in your POS — IRN + QR back in ~90 ms
The problem
For Head of Engineering at a retail chain, modern-trade brand, QSR network. Every store POS issues 10,000+ invoices/day. Above the ₹5 Cr threshold you must e-Invoice in real time at the moment of sale. Any IRN latency above 200 ms means a queue at the counter — a UX disaster during peak hours.
How WhiteBooks solves it
- Sub-100 ms IRN generation in the fast path: p50 87 ms, p95 312 ms — measured against the IRP from Mumbai and Hyderabad regions.
- Signed QR code + signed JSON returned in the same response — print directly to the customer receipt without a second round-trip.
- Bulk back-fill for end-of-day reconciliation when the POS was offline mid-shift.
- Auto-roll-up to GSTR-1 from the day's POS feeds — file the monthly return without re-keying.
Key APIs
| Tool / Endpoint | What it does | Path |
|---|---|---|
einvoice.generate_irn | Single, fast path | /api/v1/generate-irn |
einvoice.generate_irn_bulk | EOD back-fill batch | /api/v1/bulk-generate-irn |
einvoice.cancel_irn | Returns / refunds within 24h | /api/v1/cancel-irn |
gst.file_gstr1 | Auto roll-up of daily B2C | /api/v1/gstr1/file |
Compliance angle
₹5 Cr e-Invoice mandate, B2C QR code requirement, returns handling (cancel IRN within 24h vs credit note after), GSTR-1 monthly filing with auto-split between B2B / B2C / B2CL.
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 modern-trade retail chain with 380 stores routes every POS sale ≥ ₹5 Cr threshold through WhiteBooks. Receipt prints with signed QR in under 200 ms end-to-end. Daily B2C aggregation rolls up automatically; finance opens GSTR-1 prefilled on the 7th of each month.
Frequently asked questions
Can the IRN call complete fast enough not to queue the customer?
Yes. p50 latency is 87 ms and p95 is 312 ms measured at the IRP edge from Mumbai and Hyderabad. Most POS round-trips (terminal → kiosk → response) sit under 200 ms end-to-end including network. We publish live latency at whitebooks.in/status.
What if our network drops mid-sale?
Use einvoice.generate_irn_bulk for the end-of-shift back-fill — it accepts up to 1,000 invoices per call with idempotency keys. The IRP allows IRN generation up to 7 days after invoice date so a brief outage is recoverable.
How do we handle a return or refund inside the 24h cancellation window?
Call einvoice.cancel_irn with the IRN, NIC reason code (typically "01" for duplicate or "02" for data entry error), and remarks. After 24 hours you issue a credit note IRN against the original.
Do you auto-roll up daily POS sales into GSTR-1?
Yes. We aggregate B2B (named-buyer with GSTIN), B2C (consumer ≤ ₹2.5 L), and B2CL (consumer > ₹2.5 L inter-state) into the correct GSTR-1 sections. Finance opens GSTR-1 prefilled and only reviews / files.
Do you support the ₹5 Cr e-Invoice mandate threshold check?
Yes. Pass the seller GSTIN and total turnover when subscribing; we route invoices through the IRN path only when threshold-applicable. Smaller invoices skip the IRP step automatically.
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