What makes a POS integration tax-compliant?
A compliant POS files every sale to the correct authority at settlement, prints the returned fiscal QR on the receipt, handles rejections and duplicates gracefully, and uses idempotency so retries and reprints never double-file. TaxBridge provides the API; this checklist covers the client side.
The checklist
- File at settlement, not at order open
- Map every line with HS code, tax rate and totals
- Send an
Idempotency-Keyon every submission - Print the returned
qrCodeon the receipt - Store
submissionIdfor status and reprints - Surface validation (400) and rejection (422) messages to the cashier
- Retry 502/504 with the same idempotency key
- Test every path with the simulator before go-live
Minimal request
POST /api/v1/invoices
curl -X POST https://taxbridge.themetasum.com/api/v1/invoices \
-H "Authorization: Bearer tbk_test_9f3a21c7b4d6e8f0_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 0b6d1c4e-7f9a-4a51-8d3c-2e5f7a91b204" \
-H "X-Tax-Authority: PRA" \
-d '{
"invoiceNumber": "INV-10001",
"invoiceDate": "2026-08-10T10:30:00",
"invoiceType": "Sale",
"currency": "PKR",
"paymentMode": "Cash",
"customer": { "name": "Walk-in Customer" },
"items": [{
"description": "Chicken Karahi Full", "hsCode": "11001010",
"quantity": 1, "unitPrice": 1500.00,
"taxRate": 16, "taxAmount": 240.00, "total": 1740.00
}],
"subTotal": 1500.00, "tax": 240.00, "total": 1740.00
}'Handle the outcomes
| HTTP | Meaning | What your code does |
|---|---|---|
201 | Approved by the authority | Print qrCode, store submissionId |
200 | Idempotent replay (duplicate:true) | Treat like the original — no quota consumed |
400 INVALID_INVOICE | Normalizer rejected it; details[] lists every problem | Fix and resubmit — no quota consumed |
402 QUOTA_EXCEEDED | Plan limit hit or subscription expired | Upgrade or renew |
409 DUPLICATE_INVOICE | Invoice number already approved for this authority + environment | Do not resubmit |
422 | Authority rejected it (status:"REJECTED") | Read authorityMessage, fix the data |
429 | Rate limit or sandbox soft cap | Honour Retry-After |
502 / 504 | Authority errored or timed out | Retry with the same Idempotency-Key |
Frequently asked questions
When should the POS call the API?
At settlement, when the bill is finalised — that is the taxable event.
What do I print on the receipt?
The qrCode returned by the API, plus your invoice number; keep the submissionId for later status checks.
How do I avoid double-filing on reprint?
Use the same Idempotency-Key; an idempotent resubmission returns the stored result with no new filing.