Import Invoices from Excel/CSV into TaxConnect

Use the Import from Excel feature when you do not have a live accounting connection. Prepare the TaxConnect CSV in Excel or another spreadsheet application, save it as CSV, and upload it through the Excel import page. This guide covers the workflow, the actual CSV schema, multi-line invoices, and the limits the importer enforces before submission to FBR. For the accounting-software overview, see Connect Accounting.

Overview

Import from Excel is the right path when you keep books in a system that cannot connect directly to TaxConnect through OAuth, or when you want to validate a one-off batch without giving TaxConnect live access. The importer accepts a CSV file that you prepare using Microsoft Excel or another spreadsheet application. The importer contract is CSV-based. Native .xlsx upload is not supported; you must export or save your file as CSV before uploading.

After upload, TaxConnect groups rows that share the same invoice number into a single invoice, normalises your data, applies your tax mappings, and prepares the batch for validation and submission through the standard FBR queue.

Before you start

• Active organisation is required. Select or activate the organisation in TaxConnect before importing. Imports fail when no organisation is active.
• Tax mappings must be configured. Configure your tax mappings so that each tax rate in your file resolves to a valid FBR scenario. The importer will not guess scenario codes for you.
• Sandbox is the place to test. Run your first import and a small submission batch in the sandbox before moving to production.
• FBR limits apply. Maximum 25 invoices per submission batch. A larger imported file is fine to import and review, but submissions to FBR through TaxConnect must be split into batches of 25 or fewer.

Prepare the file

1. Open Invoices inside the target organisation.
2. Click Import from Excel and download invoices_template.csv.
3. Open the template in Microsoft Excel or another spreadsheet application.
4. Keep the header names unchanged. Headers are case-sensitive. Adding, renaming, or reordering columns is allowed; missing required columns are reported during validation.
5. Add one row per invoice line item. Invoice-level information such as buyer details and invoice date is repeated on each line-item row. See Multi-line invoices.
6. Save or export the file as CSV (.csv, UTF-8). Do not save as .xlsx — the importer only accepts CSV.
7. Upload the CSV through Import from Excel. Review the imported rows in the grid, fix any validation errors, then validate and submit.

Multi-line invoices

TaxConnect uses one CSV row = one invoice line item. Rows that share the same invoice_number are grouped into a single invoice. An invoice with three products or services appears as three CSV rows with the same invoice number.

Example file layout for two invoices, one with three line items:

The first three rows become a single invoice containing three line items. The fourth row becomes a separate invoice. Invoice-level fields such as buyer_name, buyer_ntn, and invoice_date_str are repeated on each line-item row.

Field reference

The following fields are recognised by the current importer. Required fields are marked. The field names are case-sensitive.

Invoice-level fields

• invoice_number — required. Your invoice reference. Rows with the same value are grouped into a single invoice. Example: INV-001.
• invoice_date_str — required. Format DD/MM/YYYY. Example: 15/06/2026.
• status — optional. Defaults to DRAFT if blank.
• subtotal — optional numeric.
• total_tax — optional numeric.
• total — optional numeric.

Buyer fields

• buyer_name — required.
• buyer_ntn — optional. May contain either a 7-digit NTN or a 13-digit CNIC. TaxConnect strips non-digit characters during normalisation and warns you if the result does not match either length. If the field is blank, TaxConnect can attempt to autofill the buyer NTN/STRN from previously learned buyer mappings.
• buyer_strn — optional. 7–15 digits.
• buyer_address — optional.
• buyer_province — optional. Defaults to the organisation default where appropriate.

Seller fields

Note: seller_name and seller_ntn are not CSV fields. They are read from the active organisation’s company_name and tax_id. Do not add them to the file.

• seller_strn — optional. 7–15 digits. Defaults from organisation configuration where appropriate.
• seller_address — optional.
• seller_province — optional. Defaults from organisation settings where appropriate.

Line-item fields

• productDescription — required.
• hsCode — optional. When the HS code begins with zero, prefix it with an apostrophe in Excel so Excel does not convert it into a number. Example: ‘8432.1010.
• quantity — required.
• uoM — optional. Example: “Numbers, pieces, units”. Because this value contains a comma, CSV requires the value to be enclosed in double quotes.
• taxRatePercent — optional. Example: 18 for 18%.
• valueSalesExcludingST — optional numeric.
• salesTaxApplicable — optional numeric.
• discount — optional numeric.
• totalValues — optional numeric.
• extraTax — optional numeric.
• furtherTax — optional numeric.
• salesTaxWithheldAtSource — optional numeric.
• fedPayable — optional numeric.
• fixedNotifiedValueOrRetailPrice — optional numeric.
• saleType — required. The value must match the exact FBR sale-type description available in TaxConnect, for example Goods at standard rate (default). Do not enter single letters such as S, E, or Z. This field is saleType, not taxType.
• sroScheduleNo — optional.
• sroItemSerialNo — optional.

What the importer normalises

Before the rows reach validation, TaxConnect cleans and normalises the data so that common spreadsheet quirks do not block your submission. Specifically, the importer:

• Groups line items that share the same invoice_number into a single invoice.
• Strips non-digit characters from NTN, CNIC, and STRN values and warns when the resulting value is not 7 or 13 digits.
• Retrieves previously learned buyer NTN/STRN information when the imported file leaves the field blank.
• Matches saleType descriptions to the FBR transaction types available in TaxConnect.
• Normalises HS codes against the available reference data.
• Applies the organisation’s configured tax mappings to determine the relevant FBR scenario before validation.

Tax mappings and FBR scenarios

TaxConnect uses the organisation’s configured tax mappings to determine how invoice line tax rates correspond to FBR scenarios. The application resolves the relevant mapping to an FBR scenario code (for example SN001, SN002) before validation and submission. You do not enter FBR scenario codes by hand in normal use; the mapping configuration handles that step.

Import the file

1. Open Invoices inside the target organisation.
2. Click Import from Excel.
3. Select the prepared CSV file. TaxConnect reads the header row, groups rows by invoice_number, and normalises each row.
4. Review the imported invoices in the grid. Fix any validation errors flagged on individual rows.
5. Select the invoices you want to send to FBR (up to 25 per batch).
6. Click Validate. When validation passes, click Submit to FBR.

Validate and submit

After import, follow the Validate & Submit guide to run schema validation, monitor the queue, and review submitted history. The submission limits below are enforced by the validator and the queue.

• Maximum 25 invoices per submission batch. Larger imported files are fine to import and review, but submissions to FBR through TaxConnect must be split into batches of 25 or fewer. The system will show a warning if your selection exceeds the batch limit.
• Maximum 100 invoices per rolling hour. A safety limit, not a subscription limit. Prevents accidental mass submissions and protects the queue from overload. The counter resets automatically after one hour.

Troubleshooting

Wrong number of columns

Cause: a field contains a comma without CSV quotation marks. Example problem: Numbers, pieces, units. Correct form: “Numbers, pieces, units”.

Could not match sale type

Cause: the saleType value does not exactly match an FBR description available in TaxConnect. Copy the value from the list shown by TaxConnect rather than typing it from memory.

NTN/CNIC/STRN characters removed

TaxConnect strips dashes, spaces, and other non-digit characters from NTN, CNIC, and STRN values during normalisation. Verify the resulting identifier before submission. A 7-digit value is treated as a NTN; a 13-digit value is treated as a CNIC.

Invalid NTN/CNIC

NTN must be 7 digits. CNIC must be 13 digits. If the value is shorter or longer, or contains non-digit characters that resolve to a different length, validation will fail.

Leading-zero HS code changed by Excel

When an HS code begins with zero, prefix the cell value with an apostrophe in Excel so Excel does not convert it into a number. Example: ‘8432.1010.

Missing productDescription or quantity

Check that the column headers in your CSV match the field names exactly, including case. Headers are case-sensitive. Required fields cannot be blank.

More than 25 invoices selected

The submission will be rejected. Split the selection into two or more batches of 25 or fewer invoices.

No active organisation

Select or activate an organisation in TaxConnect before importing. The importer needs an active organisation to apply defaults, validate inputs, and prepare submission.

Related guides

• Excel to FBR digital invoicing — the commercial overview of the Excel import workflow.
• Connect Accounting — choose between Xero, QuickBooks Online, and Excel import.
• Tax Mapping — configure how your tax rates map to FBR scenarios.
• Sandbox Testing — validate the import and submission flow before production.
• Validate & Submit — run validation, submit to FBR, and monitor the queue.
• FBR IRIS Setup — generate the sandbox and production tokens required for submission.