Reviewed: 10 October 2026. Audience: Pakistani sales-tax-registered businesses, accountants, POS/ERP operators and software implementation teams.
Error 0099 is an HS code and UOM compatibility error, not a generic network problem. FBR's Digital Invoicing API specification v1.12 says the UOM must correspond to the submitted HS code. Check the specific rejected invoice line, retrieve the acceptable unit, correct the mapping and revalidate. Official FBR technical specification.
What does FBR error 0099 mean?
Every invoice item sent through FBR Digital Invoicing has an HS code (hsCode) and a unit-of-measure field (uoM). The HS code identifies the category of goods or services for reporting; the UOM describes the quantity basis. FBR validates whether that combination is accepted by its reference data.
In its published API error table, FBR labels code 0099 as a UOM problem and explains that the UOM must match the provided HS code. The error can occur even when the product name, buyer details and invoice totals otherwise look correct. See the official error table, printed page 40.
Important distinction: A business's stock unit does not always have to be the same as the reporting unit in its electronic invoice. For instance, an ERP may sell cartons or boxes while a particular HS code requires a different accepted FBR unit. The correct mapping must reflect the actual product and applicable reference data.
Why does an HS code and UOM mismatch happen?
- Stock units were sent directly to FBR: a POS records Box, Foot or Pack but the selected HS code does not permit that reporting unit.
- The HS code changed: staff updated the product classification but retained the previous FBR unit.
- Excel imports used generic units: a bulk upload populated all products with the same UOM without checking HS-code compatibility.
- Text or mapping differs: software sends its internal abbreviation rather than the accepted FBR unit description.
- Outdated master data: the accepted UOM mapping was not rechecked when product details or reference information changed.
Changing the UOM purely to make a validation message disappear is not enough. The HS classification, actual measurement and financial values must remain truthful and consistent.
How do you fix FBR digital invoicing error 0099?
Step 1: Find the invoice item that failed
Open the complete validation response in your invoicing system. Check validationResponse, any invoiceStatuses entries, the item's itemSNo, its errorCode and the text returned by FBR. A technical HTTP success does not automatically mean every invoice item passed business validation.
Record the draft invoice reference and the affected product before changing any data. If the original invoice has already been posted successfully, review its status instead of posting it again.
Step 2: Confirm the HS code is correct
Check the product's real classification against your approved product master and applicable tax guidance. Do not select an unrelated HS code just because it accepts your preferred unit. Where the classification is uncertain, confirm it with your tax or customs adviser.
Step 3: Check the allowed UOM using FBR's HS_UOM API
FBR's published API v1.12 includes an HS_UOM reference method. It takes an HS code and a sales-annexure identifier and returns an allowed unit ID and description.
Illustration from the FBR specification:
GET https://gw.fbr.gov.pk/pdi/v2/HS_UOM?hs_code=5904.9000&annexure_id=3In the official example, the response describes a unit as Square Meter. This is an illustration, not permission to use Square Meter for unrelated products. The appropriate annexure_id and live result must be verified for your own transaction. Source: FBR API v1.12, section 5.9.
Step 4: Map the POS or ERP unit to the FBR reporting unit
Maintain two separate fields where necessary: the unit used for warehouse stock and sales operations, and the FBR unit returned or approved for the HS code. Add a documented conversion factor if they differ. This allows inventory operations to stay understandable while the submitted invoice uses an accepted reporting unit.
Have an authorized operator check the product's mapped UOM before enabling it for production invoices. Do not silently change historical stock quantities or previously finalized transactions.
Step 5: Recalculate quantity and verify invoice values
When the reporting unit changes, quantity must be converted accurately. Confirm that the tax-exclusive line amount, tax calculation and final line values still reconcile. Do not change quantities without checking the corresponding rate and line value in your software.
Step 6: Revalidate, then submit only once
Run the appropriate FBR invoice-validation workflow with the corrected line. Check both invoice-level and item-level results. Post only when the invoice is valid and ready. After posting, store the response, FBR invoice number and processing status against the originating POS or ERP transaction. If the submission outcome is uncertain, investigate its status before retrying to reduce duplicate-invoice risk.
For broader validation and response handling, read our FBR Digital Invoicing errors guide.
Example: Your shop sells cartons but the FBR unit is different
Consider a hypothetical product sold in cartons. Suppose its actual, verified FBR mapping permits reporting the item in individual units rather than cartons. The sale can still be recorded as cartons inside the POS, provided the electronic invoice converts the quantities and values consistently.
| Field | Illustrative value |
|---|---|
| Quantity sold in POS | 3 cartons |
| Units in one carton | 12 |
| Price per carton before sales tax | PKR 1,200 |
| Equivalent FBR reporting quantity | 36 units |
| Equivalent price per unit before tax | PKR 100 |
| Sales value excluding tax | PKR 3,600 |
Both 3 × PKR 1,200 and 36 × PKR 100 give the same pre-tax sales value of PKR 3,600. This example demonstrates unit conversion only; it does not assert that a specific HS code accepts individual units or prescribe a tax rate. Apply the actual FBR-approved UOM and the correct tax rules for the item.
Is error 0099 the same as errors 0096, 0097 or 0104?
No. These codes identify different checks in FBR's published error table:
| Code | Meaning | First check |
|---|---|---|
| 0099 | UOM is not valid for the HS code | HS code and accepted UOM mapping |
| 0096 | Selected HS code allows only KWH | Applicable energy unit |
| 0097 | KG is required | Applicable kilogram UOM |
| 0104 | Calculated percentage sales tax does not match | Rate and sales-tax calculation |
Fix the error FBR actually returned rather than applying a generic solution to every rejected invoice. These descriptions come from the official API specification v1.12, printed page 40.
How can businesses prevent error 0099 from returning?
The best long-term fix is accurate product master data, not a one-off invoice edit. For each product that needs digital invoicing, record:
- Approved HS code and product description
- POS or inventory unit
- FBR reporting UOM and source reference
- Conversion factor, where needed
- Applicable sale type and tax configuration
- Who checked the classification and when it was checked
Before going live, test one representative invoice per significant product group and repeat the test after large product imports or mapping changes. Software teams should make invalid HS/UOM combinations visible before submission, rather than leaving users with a cryptic error at the final step.
A reliable FBR Digital Invoicing software workflow also preserves validation responses and provides a way to correct rejected drafts without confusing them with accepted invoices.
Frequently asked questions about FBR error 0099
Can I keep Box or Pack as my stock unit?
Yes, if your system supports a separate FBR reporting unit and a correct conversion. The submitted UOM must still be accepted for the HS code, and converted quantities and invoice values must remain accurate.
Does error 0099 mean my HS code is wrong?
Not necessarily. The HS code may be correct while the submitted UOM is incompatible. Check the classification and the permitted unit together before changing either one.
What if the FBR HS_UOM response lists more than one unit?
Select an allowed unit that truthfully describes the supply and that your software can convert reliably. Do not choose a unit solely to pass validation.
Should I keep resubmitting an invoice that returns error 0099?
No. Correct the rejected invoice data and validate again. Before any repeated production posting attempt, confirm whether the earlier attempt was accepted or is still unresolved.
Is a successful API connection proof that the invoice was accepted?
No. A successful network response is separate from the invoice's business-validation outcome. Check the returned invoice status and individual item errors.
Need help fixing FBR digital invoicing rejections?
If your team keeps encountering HS code, UOM or invoice-validation problems, start with the product records and the exact FBR response. NexZion Solutions helps Pakistani businesses with FBR Digital Invoicing preparation, master-data setup, validation workflows and integration support.
Explore NexZion Solutions' FBR Digital Invoicing software and setup support, or contact the team with your business type and error message so the issue can be assessed against the applicable FBR requirements.
Official references: FBR/PRAL Technical Documentation for DI API v1.12 (sections 4–5, error table); FBR Digital Invoicing Technical Assistance; FBR Digital Invoicing FAQs.
This guide explains a technical validation error, not a substitute for tax classification or legal advice. Official specifications and reference data may change; verify the current requirements when deploying or updating an integration.
NexZion Solutions publishes practical guides based on business-software, compliance-workflow, website and automation implementation experience in Pakistan.
