If your business runs on ERPNext and you're sales tax registered in Pakistan, FBR digital invoicing isn't optional. Every sales invoice must be sent to FBR in real time and carry an FBR invoice number and QR code.
ERPNext handles this well. With the right app and configuration, your normal Sales Invoice workflow posts to FBR automatically, with no separate portal, no re-typing and no end-of-month uploads.
This guide walks through the full ERPNext FBR digital invoicing setup: what you need before you start, how to configure ERPNext, how to pass sandbox testing, and how to keep invoices flowing after go-live.
How ERPNext FBR Integration Works
When you submit a Sales Invoice in ERPNext:
ERPNext converts the invoice into the format FBR requires (JSON)
The invoice is sent to FBR through PRAL or another FBR-licensed integrator
FBR validates it and returns an FBR invoice number and QR code, or an error
ERPNext saves the FBR number, prints the QR code on the invoice and logs the response
Your team keeps working in ERPNext as usual. The FBR step happens in the background.
Before You Start: Prerequisites
Have these ready before touching ERPNext:
Sales tax registration (NTN and STRN) with working IRIS access
ERPNext on a supported version (most FBR apps target recent versions such as v15)
A server with a static IP address. FBR whitelists your server's IP before production. This matters if you're on shared or cloud hosting.
A list of your products with HS codes, and a clear idea of which sale types apply to you (standard rate, reduced rate, Third Schedule, exempt and so on)
Clean customer data: NTN or CNIC, registration status and province for each customer
Step 1: Enable Digital Invoicing on IRIS
Log in to IRIS (iris.fbr.gov.pk) with your business credentials.
Open the Digital Invoicing section and select your licensed integrator. PRAL offers its service free of cost.
Submit your software's technical details as requested.
FBR issues a sandbox token for testing.
Keep the token secure. You'll receive a separate production token later.
Step 2: Install an FBR Digital Invoicing App in ERPNext
ERPNext doesn't include FBR digital invoicing out of the box, so you add it through a Frappe app. Options include:
Apps on the Frappe Cloud Marketplace, for one-click installation on Frappe Cloud
Community apps on GitHub, installed on self-hosted ERPNext
A custom-built integration, for businesses with complex requirements
On a self-hosted setup, installation typically looks like this (the app URL depends on the app you choose):
bash
cd frappe-bench
bench get-app <fbr-app-repository-url> --branch version-15
bench --site yoursite.com install-app <app_name>
bench --site yoursite.com migrate
bench restartChoosing an app: check that it supports the latest FBR API version, handles sales returns and credit notes, has an automatic retry queue for failed submissions, and keeps full request and response logs. Also check that someone actively maintains it, because FBR updates its API and validation rules regularly.
For Pakistan-specific fields (NTN, STRN and CNIC on customers and suppliers) and tax reports such as Annexure C, a Pakistan localisation app is also worth installing.
Step 3: Configure Company and FBR Settings
Company:
Enter your NTN/CNIC, STRN, registered address and province exactly as they appear on IRIS
FBR Digital Invoicing Settings (names vary slightly by app):
Environment: Sandbox (for now)
API base URL: as provided in FBR's technical documentation
Authorization token: your sandbox token
Seller NTN/CNIC mapping: linked to the correct company, which is especially important in multi-company setups
Step 4: Prepare Your Master Data
This is where most FBR rejections come from, so spend the most time here.
Items:
Add the correct HS code to every item that is sold
Set the correct sale type (standard rate, reduced rate, Third Schedule, exempt, and so on)
Map your ERPNext UOMs to FBR's accepted units of measure
For Third Schedule items, make sure the retail price field is set up where required
Taxes:
Create Item Tax Templates for each tax category you use
Set up Sales Taxes and Charges Templates for sales tax, and for extra or further tax where it applies
Assign templates at item level, so users never type tax amounts by hand
Customers:
Record NTN or CNIC, registration type (registered or unregistered) and province
Make these fields mandatory for new customers
A useful rule: if the master data is right, the invoice will be right.
Step 5: Update the Invoice Print Format
Your printed or PDF Sales Invoice must show:
The FBR invoice number
The QR code
NTN/STRN for both seller and buyer, where applicable
An item-wise breakdown of value, tax rate and tax amount
Most FBR apps add these fields automatically. Include them in your print format and test the printed output, especially on thermal printers, where small QR codes can become unreadable.
Step 6: Complete Sandbox Testing
FBR requires your system to pass testing for the scenarios that apply to your business before you go live, for example standard-rate sales, reduced-rate goods and Third Schedule items.
In ERPNext:
Create test Sales Invoices for each required scenario
Select the matching sale type on each invoice and submit
Check the response. A valid invoice receives an FBR number and QR code, and an invalid one shows an error.
Fix the cause in your master data, not on the invoice itself, and retest
Common sandbox errors include HS code not matching the sale type (error 0052), tax calculation mismatches, UOM errors and missing buyer details. See our guide to common FBR integration errors and fixes.
Step 7: Go Live in Production
Once your scenarios pass:
FBR whitelists your server's IP and issues a production token
In ERPNext's FBR settings, switch Environment to Production and enter the production token
Submit a small first batch of real invoices and confirm each one receives a valid FBR number and QR code
Brief your sales and accounts teams on what changed: invoices are now final once posted to FBR
Changing servers later? Update your whitelisted IP before migrating, or production submissions will fail.
Step 8: Handle Returns, Corrections and Cancellations
Sales returns and credit notes must also be reported correctly. Check that your app supports them before go-live.
Under current rules, a digital invoice can be cancelled or edited within 72 hours for genuine errors. After that, you need the Commissioner's approval.
Set up a daily review of rejected or incorrect invoices so corrections happen within that window.
Step 9: Monitor Every Day
A working integration still needs monitoring. In ERPNext, set up:
A list view or report of Sales Invoices filtered by FBR status (Valid, Invalid, Pending)
Automatic retry for invoices that failed because of internet or FBR downtime
Email or system notifications for failed submissions
Scheduled background jobs (make sure the scheduler and workers are running on your server)
API logs for troubleshooting
At month-end, reconcile ERPNext sales against FBR-reported invoices before filing your sales tax return. Because everything is in one system, this takes minutes instead of days.
Using ERPNext POS? (Tier-1 Retailers)
If you're a Tier-1 retailer using ERPNext POS, POS Invoices also need to reach FBR in real time with the QR code printed on the receipt. Make sure:
Your FBR app supports POS Invoices, not only Sales Invoices
Each outlet and counter is registered on IRIS
Offline sales queue and sync automatically when the connection returns
See our step-by-step FBR POS integration guide for the full retail process.
ERPNext FBR Setup Checklist
IRIS digital invoicing enabled, integrator selected, sandbox token received
FBR app installed and settings configured
Company NTN, STRN and province correct
HS code, sale type and UOM set on every sold item
Item Tax Templates and Sales Tax Templates configured
Customer NTN/CNIC, registration type and province complete
Print format shows FBR number and QR code
All applicable sandbox scenarios passed
Static IP whitelisted, production token entered
Returns and credit notes tested
Retry queue, notifications and daily monitoring in place
Common Setup Mistakes to Avoid
Hard-coding values to pass sandbox scenarios. They fail on real invoices later.
Letting users type tax amounts manually instead of using tax templates
Skipping UOM mapping. "Nos" in ERPNext isn't automatically FBR's unit.
Hosting without a static IP, or migrating servers without updating the whitelist
Not testing returns and credit notes before go-live
Using an unmaintained app that breaks on the next FBR API update
Not checking the scheduler. If background jobs stop, invoices stop posting.
Why Businesses Choose ERPNext for FBR Compliance
One system: sales, inventory, accounting and FBR invoicing together
No double entry: FBR data comes straight from your Sales Invoices
Easy reconciliation: sales tax returns match FBR-reported invoices
Open source: no per-user licence fees
Flexible: works for manufacturers, distributors, wholesalers, retailers and multi-company groups
How Bizloom ERP Can Help
Bizloom ERP implements ERPNext with FBR digital invoicing for businesses across Pakistan, whether you're new to ERPNext or already using it. We can:
Set up ERPNext from scratch with FBR integration built in, or add FBR to your existing ERPNext
Clean and configure HS codes, sale types, UOMs and tax templates
Complete sandbox scenarios and go-live
Set up print formats, retry queues, alerts and monitoring
Provide managed ERPNext hosting with a stable server setup for FBR integration
Keep your integration updated when FBR changes its API or rules
Book a demo session to see FBR digital invoicing running live in ERPNext.
Related reading: