NetSuite integration

Connecting Oracle NetSuite to FBR digital invoicing

For finance and IT teams on NetSuite, often OneWorld and often with more than one Pakistani company. Send every sale to FBR without slowing down the people who save it.

Updated

eInvoicePro API documentation, which NetSuite scripts use to send sales to FBR

How it works

How a NetSuite link to FBR works

NetSuite gives you three places to add the FBR step: the moment a record is saved, a background script, and a script that receives messages from outside NetSuite. A good set-up uses all three, each for a different job.

1. Mark the sale when it is saved

A user event script runs after an invoice or cash sale is saved. It does one quick job: it sets a status field to pending FBR. It does not call FBR. If the save itself calls an outside service, three things go wrong. The user waits for FBR to reply. The script uses up its limited processing allowance. And if the connection drops, the record is left half-finished.

2. Send from a background script

Every few minutes, a scheduled or map/reduce script picks up pending sales. It builds each one in FBR’s format. The sale type comes from the tax code. The HS code and FBR unit come from the item. The registration type and province come from the customer. It then sends them to eInvoicePro’s API as one job of up to 1,000 invoices. Each invoice carries its NetSuite internal ID as a unique key. So if a send times out and you resend, the same sale never goes twice from your side.

3. Bring the results back

Results come back for each invoice: an FBR invoice number, or a clear reason for rejection with FBR’s exact reply. You can collect them in two ways. The same background script can check back on the job. Or eInvoicePro can send webhooks to a small script in NetSuite that receives them. These are messages sent the moment something happens: invoice-submitted, invoice-failed or job-completed. Save the FBR number, status and any error on the sale, and print the number and QR code on the customer copy.

Why the extra step is worth it

FBR wants invoices sent when they are raised, so run the background script every few minutes, not overnight. With the work split this way, users save sales at normal speed. FBR outages don’t stop data entry. And every sale shows its FBR status, which finance can report on with an ordinary saved search.

Your data

The custom fields to add

FBR’s details live in NetSuite custom fields. The IDs below are suggestions. What matters is that each detail is stored in exactly one place.

Suggested NetSuite custom fields for FBR digital invoicing
Suggested field Type What it holds
custentity_fbr_ntn Entity (customer) Buyer NTN or 13-digit CNIC, digits only. Skip it if an existing tax registration field already holds this reliably
custentity_fbr_reg_type Entity (customer) Registered or unregistered, based on FBR’s check of the customer’s number
custitem_fbr_hs_code Item HS code from FBR’s own list, saved as text so leading zeros are kept
custitem_fbr_uom Item FBR’s name for the unit. NetSuite’s unit names are not the same as FBR’s
customrecord_fbr_tax_map Custom record type One row for each sales tax code, with fields such as custrecord_fbr_sale_type for the FBR sale type, SRO schedule and item serial
custbody_fbr_status Transaction body Pending, filed or failed. Your saved searches report on this field
custbody_fbr_invoice_no Transaction body The FBR invoice number, saved as text, exactly as FBR returns it
custbody_fbr_error Transaction body FBR’s error code and message for the last failed attempt
custcol_fbr_line_result Transaction line Optional: the result for each line, for invoices where one line was rejected

The province comes from the customer’s address and your subsidiary’s address. Match NetSuite’s state values to FBR’s province names once. The prefixes follow NetSuite’s own rules: custentity for entities, custitem for items, custbody for transaction headers, custcol for lines, and custrecord for fields on custom records.

Why the sale type sits on the tax code

We keep the sale type on a small custom record, one row per tax code, not on every item. This is on purpose. In NetSuite, the tax code already decides how a line is taxed. Match each tax code to an FBR sale type once, and every new item gets the right treatment from its tax code. No item needs its own. Items still need their HS code and unit, because those describe the goods, not the tax. Our guide to matching tax codes goes through FBR’s rules line by line.

OneWorld

Subsidiaries, NTNs and FBR credentials

To FBR, each Pakistani company (legal entity) is a separate seller. NetSuite OneWorld already works this way. Your link to FBR just has to follow it.

One NTN per Pakistani subsidiary

Each subsidiary that sells in Pakistan sends invoices under its own NTN, with its own FBR credentials. One eInvoicePro account holds credentials for all of them. A single job can mix sales from different subsidiaries, and the right credentials are picked for each invoice.

Everything else stays out

Subsidiaries outside Pakistan, and transaction types that aren’t sales to a buyer, must never join the list waiting for FBR. Filter them out by subsidiary and transaction type in the background script, not after FBR rejects them.

Sales between your own companies need a rule

Decide one clear rule for these transactions. FBR refuses an invoice where the buyer is also the seller. So keep out anything booked between records that share one NTN, such as branch transfers.

Build or buy

Build it all in SuiteScript, or use a ready connection?

With SuiteScript, your own team can build a direct link to FBR. But whatever you build yourself, you must also look after.

All in SuiteScript

NetSuite calling FBR directly

  • Your developer handles FBR’s invoice format, each subsidiary’s token, resending failures and reading errors line by line
  • Every FBR change means a script change, another round of testing and a new release
  • FBR does not block duplicates, so your code must handle lost replies with care
  • You build the HS code, unit, rate and SRO look-ups against FBR’s lists yourself
Ready connection

NetSuite → eInvoicePro → FBR

  • Your scripts convert NetSuite data and send jobs of up to 1,000 invoices
  • eInvoicePro’s API handles FBR changes, with no new NetSuite release from you
  • Stopping duplicates, resending single invoices and FBR’s exact replies come built in
  • Many subsidiaries, one account. Switching from test to live is a single setting

Using NetSuite? Book a demo

See how eInvoicePro sends invoices to FBR, and bring your questions about connecting it to NetSuite.

Watch out

NetSuite traps to avoid

These pass your team’s testing, then fail at the first month-end.

Records

  • Cash sales are a separate record type from invoices, and they are sales too
  • Credit memos need the original sale’s FBR number, not just its NetSuite number
  • Document numbers with prefixes or slashes must be changed. FBR accepts only letters, digits and hyphens
  • Editing an invoice in NetSuite after you send it changes nothing at FBR

Scripts

  • A script that runs on save also runs on edits. Don’t mark an invoice already sent for FBR again
  • Your settings decide whether sales that arrive by CSV import, other integrations or web services run your user event script. Test every way sales enter NetSuite
  • Background scripts have processing limits. Size your jobs so a large batch doesn’t get stuck
  • NetSuite’s limit on requests running at once is shared between SOAP, REST and RESTlets. The script that receives eInvoicePro’s messages competes with your other integrations
  • Refreshing your NetSuite test account copies live data into it. Make sure a refreshed test account can’t send to FBR’s live system

Data

  • Customers added by sales teams often have no tax ID or province
  • Items without an HS code must be caught by your own check, not by FBR
  • Prices that include tax hide the value before tax that FBR needs on each line
  • A discount on the whole invoice has to be spread across the lines for FBR

Going live

A realistic four-week plan to go live

NetSuite’s test account and FBR’s test system (each called a sandbox) fit together neatly. Just never let either one touch your live systems.

  1. Week 1

    Match and add fields

    Create the custom fields. Match every sales tax code to an FBR sale type. Fill in HS codes and FBR units on the items you sell. Record each Pakistani subsidiary’s NTN.

  2. Weeks 2–3

    Build and test in both test systems

    Set up the scripts in your NetSuite test account and point them at eInvoicePro in test mode. Work through the scenarios FBR has given each of your NTNs. No business gets all 28. When the test invoices pass, FBR issues your live tokens automatically.

  3. Week 4

    Run side by side

    In your live NetSuite, check every sale against FBR without sending it. Each day, compare the results with a saved search of the day’s sales, one subsidiary at a time.

  4. Go live

    Send all day

    Switch the background script to live sending on a short schedule. Build a saved search of failed and pending sales, and make one person responsible for it.

Finance or controller

Matches tax codes to FBR sale types, and checks every day that each subsidiary’s figures agree.

NetSuite administrator or partner

Builds the fields and scripts, sets them up in the test and live accounts, and watches the search of failed sales.

eInvoicePro

Checks every invoice against FBR’s lists, sends it to FBR and returns FBR’s invoice number and QR data for the NetSuite invoice. Our team helps you set it up.

FAQ

Frequently Asked Questions

Still have a question?

Ask our team on WhatsApp. Tell us what you sell and where, and we will point you to the right setup.

Ask on WhatsApp
Does NetSuite support FBR digital invoicing on its own?

No. NetSuite has no Pakistan FBR version built in. You add FBR sending with custom fields and a few small scripts. They send each sale to eInvoicePro and save the FBR number it returns.

Should NetSuite contact FBR when the invoice is saved?

Mark it then, but send it from a background script. Calling FBR during the save makes users wait for FBR. It also uses up the script’s processing allowance, and leaves the record half-finished if the connection drops.

We have several Pakistani subsidiaries. Do we need a separate connection for each?

No. Each subsidiary sends under its own NTN with its own FBR credentials. But one eInvoicePro account holds them all, and a single job can mix sales from different subsidiaries.

Do cash sales need to go to FBR too?

Yes, if they are taxable sales. NetSuite records them as a different transaction type from invoices, so make sure your scripts cover both.

How do we stop the same sale going to FBR twice?

Send the NetSuite internal ID as each invoice’s unique key. Then, if you resend after a network timeout, eInvoicePro knows it is the same invoice. FBR itself does not block duplicates. So if you don’t know whether a sale reached FBR, check whether FBR has it before you resend.

Can a credit memo in NetSuite cancel an FBR invoice?

No. A credit memo is a NetSuite document, and FBR never treats it as a cancellation. To cancel or edit an invoice already sent, you do it yourself in FBR’s portal within 72 hours, if it was a genuine mistake. After that, you issue a new note that carries the original FBR invoice number.

Do we need to replace NetSuite?

No. NetSuite stays your main record. The link adds a step that sends each sale to FBR, plus a few fields to hold FBR’s results.

Ready to simplify your FBR digital invoicing?

Join 2000+ businesses that use eInvoicePro to make invoices and send them to FBR.

Chat with us