Shopify FBR Integration Explained: From Order to Digital Invoice

For a Pakistani Shopify merchant, integration means turning commerce data into an FBR digital-invoice request, sending it through the approved route, storing the response and keeping both systems reconcilable. Shopify remains the operational source for the order. FBR returns its own invoice identifier and validation result. Your books must explain the relationship between them.

S.R.O. 69(I)/2025 established the Chapter XIV framework for electronic sales tax invoices and licensed integrators. Rollout dates were subsequently notified and revised, including through S.R.O. 709(I)/2025, S.R.O. 1413(I)/2025 and S.R.O. 1852(I)/2025. Scope and deadlines are legal questions; the API connection is only the implementation.

An order contains customer details, billing and shipping addresses, line items, quantities, prices, discounts, shipping lines, taxes, payment status and fulfilment status. Some values change after order creation. A customer may edit an address, an operator may add a discount, or a courier may return a COD parcel. The integration must use a defined event rather than whatever the order looks like at an arbitrary moment.

Agree the invoicing trigger with your adviser and operations team. FBR’s FAQ refers to time of supply under section 2(44) of the Sales Tax Act, 1990 as receipt of payment or delivery, whichever is earlier. How that rule applies to your prepaid and COD flows deserves explicit advice. Do not copy another store’s trigger without comparing facts.

Shopify does not natively know every FBR field. The integration may need a seller registration number, scenario ID, invoice type, buyer registration status, HS code, unit of measure, rate, SRO or schedule reference and sale type. These should come from controlled merchant settings and product mappings, not free-text guesses made at submission time.

A useful rule is to separate facts from tax decisions. Quantity and paid price are usually facts from Shopify. Whether the buyer is treated as registered, whether further tax applies, and which SRO schedule governs a line are decisions requiring validated source data and professional approval.

Before sending, software should check mandatory fields, date formats, numeric precision, totals and known code lists. It should also detect operational problems such as an order already linked to an FBR invoice. Local validation gives a faster, clearer message, but it cannot replace FBR validation because server-side rules and reference data can change.

The current FBR technical documentation distinguishes validation and posting methods and uses JSON payloads with token-based authorization. Endpoint names and sample formats have changed across documentation versions. Use the endpoint and token shown in the merchant’s current Digital Invoicing portal rather than hard-coding an old PDF example.

A valid submission should produce an FBR invoice number and item-level or invoice-level status information. Store the raw response, normalized status, submission time and link to the Shopify order. The FBR number is not the Shopify order number: both identifiers should remain visible so customer support, accounts and auditors can trace the transaction.

A timeout is not proof of failure. The server may have accepted the invoice while the response was lost. A robust workflow marks the result as uncertain, checks available invoice details or status facilities, and retries only with duplicate protection. Blindly pressing submit is how one commercial sale becomes two reported invoices.

FBR’s technical documentation requires the FBR Digital Invoicing System logo and QR code on the issued invoice and describes printing the returned FBR invoice number. The exact presentation should follow the current specification. The customer-facing document should also retain the commercial information your team needs, such as Shopify order reference and line descriptions.

Do not generate a decorative QR code before FBR acceptance. It needs to represent the approved verification value or invoice number according to the current specification. Keep the rendered document reproducible from stored data; if a customer asks six months later, the team should not have to rebuild it by hand.

Rejected invoices need an operator queue with the literal error, affected field, attempted payload and safe action. Common causes include invalid registration details, unsupported rates, missing HS codes, wrong scenario data, expired or incorrect tokens and source IPs that are not whitelisted. Correct the source mapping so the next order does not repeat the same failure.

Returns and post-invoice changes require their own process. STGO 01 of 2026 discusses cancellation, deletion or editing of a valid electronic sales tax invoice generated because of a bona fide mistake within 72 hours, with prior Commissioner approval after that period. A commercial return may instead involve debit or credit-note rules. Ask your adviser which process fits the event.

At minimum, compare eligible Shopify events, submitted invoices, valid FBR responses, pending or failed records, cancellations and refunds. Compare values as well as counts. A dashboard showing “99 successful” is misleading if one high-value order is missing or if discounts were mapped incorrectly across every line.

Good integration is boring: clear ownership, stable mappings, visible failures and repeatable reconciliation. ComplyStream can provide the workflow between Shopify and the FBR process, but the merchant and adviser still own registration scope and tax treatment. Review those decisions whenever your catalogue or operating model changes.