Billora Invoicing API

01 — Start here

Overview

Billora handles e-invoicing and FBR digital-invoice submission for your business. This API lets your own accounting system submit an invoice the moment it's finalized, instead of someone re-entering it into Billora by hand.

Base URL for every endpoint below:

https://erp.billora.pk/api/v1/invoices/

02 — Access

Authentication

Every request needs two headers, issued per company from Billora's admin panel (sys_admin → company → API Credentials):

A bad or missing key/secret returns 403:

{
  "detail": "Invalid API secret."
}

03 — Quick start

End-to-end example

One call, one response. No separate "check back later" step for the normal case.

curl -X POST https://erp.billora.pk/api/v1/invoices/ \
  -H "X-Api-Key: your_api_key" \
  -H "X-Api-Secret: your_api_secret" \
  -H "Content-Type: application/json" \
  --max-time 180 \
  -d '{
    "client_invoice_ref": "ERP-2026-04871",
    "invoice_date": "2026-10-13",
    "customer": {
      "name": "Nando'"'"'s Pakistan Pvt Ltd",
      "ntn": "1211412-0",
      "address": "Plot 4, Korangi Industrial Area, Karachi",
      "province": "SINDH",
      "registration_type": "Registered"
    },
    "tax_rate": 18,
    "items": [
      { "description": "Printed packaging boxes", "hs_code": "4819.1000", "uom": "Numbers, pieces, units", "quantity": 500, "rate": 45.00 }
    ],
    "notes": "ERP invoice #4871"
  }'

Response — invoice accepted and already posted to FBR:

{
  "reference_number": "BLR-20261013-7F3A9C21E0",
  "status": "accepted",
  "trans_id": 10512,
  "fbr_invoiceno": "3310104ABPR1760...DI",
  "error": null,
  "fbr_mode": "live"
}

fbr_mode is in every response: live (real FBR), sandbox (FBR test system - the FBR invoice number isn't a real one) or offline (no FBR connection set up - nothing is sent or kept, status failed).

Endpoint

Submit an invoice

Validates, builds, and posts the invoice to FBR before responding. See Request fields for the full body schema and Status values for what the response's status can be.

{
  "status": "rejected",
  "error": "customer.ntn or customer.cnic is required when registration_type is 'Registered'. items[0].rate must be greater than 0."
}

Endpoint

Check a submission's status

Mainly useful for the rare ambiguous outcome — everything else is already final in the submit response.

{
  "reference_number": "BLR-20261013-7F3A9C21E0",
  "status": "accepted",
  "error": null,
  "trans_id": 10512,
  "fbr_invoiceno": "3310104ABPR1760...DI",
  "created_at": "2026-10-13T11:02:04",
  "updated_at": "2026-10-13T11:02:41",
  "fbr_mode": "live"
}

Unknown reference number returns 404 with {"error": "Not found"}.

Endpoint

Check credentials and FBR mode

Submits nothing. Use it to test the API key/secret and see which FBR mode your invoices will be posted in.

{
  "company_id": 14,
  "company_name": "Delizia Private Limited",
  "fbr_mode": "live"
}

Endpoint

Delete a submission's invoice

Removes the invoice from Billora so it can be corrected and submitted again with the same client_invoice_ref. Allowed for invoices posted in sandbox (testing) mode and for rejected/failed submissions. Returns 409 for an invoice FBR accepted in Live mode, or while an FBR outcome is still unknown.

{
  "reference_number": "BLR-20261013-7F3A9C21E0",
  "status": "deleted",
  "fbr_mode": "sandbox"
}

Endpoint

Retry a failed submission

Only works on a submission currently in rejected or failed — anything else returns 409. Runs the same build-and-post sequence again and returns the new outcome, same shape as submit's response.

Reference

Scenarios not yet set up

If your company already has a sale type configured for the scenario_id you send, it's just used — nothing below applies. If it doesn't, Billora sets one up automatically on this first call instead of rejecting it, as long as:

• Your company is already enabled for that scenario_id with FBR in Billora (this is a one-time thing Billora support does per scenario — it's not something this API call can grant on its own).
• If the scenario needs an SRO reference, sro_schedule_no and/or sro_item_serial_no match a real entry in FBR's own SRO reference list — an unrecognized value is rejected, not guessed.

Everything else about the scenario (its FBR transaction type) is looked up from FBR's own reference data, never taken from what you send. This only covers a plain-percentage tax_rate — a scenario with a fixed or compound FBR rate (e.g. a fixed amount per unit) still needs Billora support to configure once, since trusting a client-declared tax formula is treated differently from trusting which already-approved scenario applies.

Reference

Request body fields

Reference

Status values

Reference

Errors

Reference

Idempotency & retries

client_invoice_ref is your safety net. Billora remembers it per invoice — submitting the same value again, for any reason, returns whatever the first attempt actually resolved to instead of processing it a second time.

1. 1
   Always send the same client_invoice_ref for a given invoice on every attempt — e.g. your own internal invoice number, not a freshly generated value per call.
2. 2
   If your own request times out (see Timeouts) before you see a response, it's safe to just call submit again with the same body. You'll either get the real result back immediately, or the original call will still be finishing — either way, nothing gets posted to FBR twice.
3. 3
   The one exception is ambiguous — that specifically means Billora itself doesn't know the outcome yet either. Use status, not a resubmit, until it resolves.

Reference

Rate limits

Each API client has a per-minute request limit (default 60/min, configurable per client). Exceeding it returns:

{
  "detail": "Request was throttled. Expected available in 60 seconds."
}

HTTP 429. If your integration needs a higher limit, ask Billora to raise it for your API client.

Reference

Timeouts