{ "openapi": "3.0.3", "info": { "title": "TaxBaaz API — by ESASOFT", "version": "v1", "description": "The TaxBaaz API lets your own software create invoices, look up FBR/PRA status, record receipts and read your books.\n\n## Getting started\n1. In TaxBaaz open **Settings > API & Webhooks** and create a key. Choose only the scopes you need.\n2. Send it on every request: `Authorization: Bearer tbx_live_...`\n3. Call `GET /v1/me` to confirm it works.\n\nA key acts as the user who created it, so that user's role, permissions and branches apply on top of the key's scopes. Keys work only if your plan includes API access.\n\n## Sandbox keys\nA key created as **sandbox** (`tbx_test_...`) is for building your integration safely. It can read your data, but every create call is run in full (validation, tax calculation, numbering) and then rolled back: **nothing is saved and nothing is sent to FBR/PRA**. The response shows what would have happened. Responses carry `X-TaxBaaz-Sandbox`. Because nothing is saved, an id returned by a sandbox create cannot be fetched afterwards.\n\n## Errors\nEvery error has the same shape: `{\"error\": {\"code\": \"...\", \"message\": \"...\", \"details\": {...}, \"request_id\": \"req_...\"}}`. Match on `code`; show `message` to people. Quote `request_id` if you contact support. Statuses: 401 key problem, 402 plan or subscription, 403 scope or permission, 404 not found, 422 invalid request, 429 rate limit, 5xx our side.\n\n## Rate limits\nPer company and plan, per minute: starter 60, business 300, enterprise 1200; sandbox keys 30. Over the limit you get 429 with a `Retry-After` header.\n\n## Idempotency\nSend `Idempotency-Key: ` on POST requests. Retrying the same request with the same key returns the original response (header `Idempotent-Replayed: true`) instead of creating a duplicate. Keys are remembered for 24 hours.\n\n## Pagination\nList endpoints take `page` and `per_page` (at most 100) and return `data`, `links` and `meta`.\n\n## Money and dates\nAmounts are strings with four decimals (never floats). Dates are `YYYY-MM-DD`, timestamps ISO 8601. Times follow the company's timezone setting.", "contact": { "name": "ESASOFT", "url": "esasoftpk.com", "email": null }, "x-footer": "Powered by ESASOFT - esasoftpk.com - 0321-4510041" }, "servers": [ { "url": "https://taxbaaz.esasoftpk.com/api", "description": "TaxBaaz" } ], "tags": [ { "name": "Account" }, { "name": "Invoices" }, { "name": "Customers" }, { "name": "Items" }, { "name": "Receipts" }, { "name": "Reports" }, { "name": "Accounting" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/v1/me": { "get": { "tags": [ "Account" ], "summary": "Who am I?", "operationId": "me", "description": "Shows the company, the user the key acts as, the key's scopes and environment, and the rate limit that applies. A good first call to check a new key.", "x-scope": null, "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Me" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/invoices": { "get": { "tags": [ "Invoices" ], "summary": "List invoices", "operationId": "invoicesIndex", "description": "Newest first. Only documents the user behind the key may see are returned.\n\n**Scope:** `invoices:read`", "x-scope": "invoices:read", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page (default 25, at most 100).", "schema": { "type": "integer" } }, { "name": "status", "in": "query", "required": false, "description": "draft, submitted, posted or cancelled.", "schema": { "type": "string" } }, { "name": "authority_status", "in": "query", "required": false, "description": "For example pending, queued, posted, failed, not_required.", "schema": { "type": "string" } }, { "name": "payment_status", "in": "query", "required": false, "description": "unpaid, partial or paid.", "schema": { "type": "string" } }, { "name": "customer_id", "in": "query", "required": false, "description": "Only this customer's documents.", "schema": { "type": "integer" } }, { "name": "document_type", "in": "query", "required": false, "description": "For example sale_invoice, credit_note.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "Invoice date on or after.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "Invoice date on or before.", "schema": { "type": "string", "format": "date" } }, { "name": "number", "in": "query", "required": false, "description": "Part of the invoice number.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of results.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } }, "links": { "type": "object" }, "meta": { "$ref": "#/components/schemas/PageMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Invoices" ], "summary": "Create an invoice", "operationId": "invoicesStore", "description": "Creates the invoice, numbers it, posts it to your books and returns it (201). Sending it to FBR/PRA happens afterwards in the background - it never delays or fails this call; watch `authority.status` or subscribe to the `invoice.posted` / `invoice.failed` webhooks. Give each line either an `item_id` or a `description` and `unit_price`. Send `\"draft\": true` to save without posting. Use an `Idempotency-Key` header so a retry cannot create a second invoice.\n\n**Scope:** `invoices:write`", "x-scope": "invoices:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique text (up to 120 characters). Retrying with the same key and body returns the first answer instead of creating a duplicate.", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Invoice" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "customer_id", "items" ], "properties": { "branch_id": { "type": "integer", "nullable": true }, "document_type": { "type": "string", "nullable": true, "enum": [ "sale_invoice", "service_invoice", "export_invoice" ] }, "invoice_date": { "type": "string", "format": "date", "nullable": true }, "due_date": { "type": "string", "format": "date", "nullable": true }, "customer_id": { "type": "integer" }, "currency": { "type": "string", "nullable": true, "maxLength": 3, "minLength": 3 }, "exchange_rate": { "type": "number", "nullable": true }, "invoice_discount_amount": { "type": "number", "nullable": true }, "other_charges": { "type": "number", "nullable": true }, "freight": { "type": "number", "nullable": true }, "notes": { "type": "string", "nullable": true, "maxLength": 2000 }, "terms": { "type": "string", "nullable": true, "maxLength": 2000 }, "draft": { "type": "boolean", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "required": [ "quantity" ], "properties": { "item_id": { "type": "integer", "nullable": true }, "description": { "type": "string", "nullable": true, "maxLength": 255 }, "quantity": { "type": "number" }, "unit_price": { "type": "number", "nullable": true }, "discount_percent": { "type": "number", "nullable": true }, "discount_amount": { "type": "number", "nullable": true }, "tax_rate_id": { "type": "integer", "nullable": true }, "unit_id": { "type": "integer", "nullable": true }, "tax_treatment": { "type": "string", "nullable": true, "enum": [ "standard", "reduced", "zero_rated", "exempt", "further_tax_applicable" ] } } } }, "payments": { "type": "array", "items": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "cash", "bank", "card", "cheque", "online", "credit" ] }, "amount": { "type": "number" }, "bank_account_id": { "type": "integer", "nullable": true }, "reference_no": { "type": "string", "nullable": true, "maxLength": 100 } } }, "nullable": true } } }, "example": { "customer_id": 12, "invoice_date": "2026-09-19", "items": [ { "item_id": 5, "quantity": 2 }, { "description": "Delivery", "quantity": 1, "unit_price": 500 } ], "payments": [ { "method": "cash", "amount": 1000 } ] } } } } } }, "/v1/invoices/{id}": { "get": { "tags": [ "Invoices" ], "summary": "Get an invoice", "operationId": "invoicesShow", "description": "One invoice with its lines and its FBR/PRA status.\n\n**Scope:** `invoices:read`", "x-scope": "invoices:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Invoice" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/invoices/{id}/status": { "get": { "tags": [ "Invoices" ], "summary": "Get an invoice's FBR/PRA status", "operationId": "invoicesStatus", "description": "A light call for polling: the invoice status, payment status, the authority status (pending, queued, posted, failed, not_required), the fiscal number(s) and, if the last attempt failed, the reason.\n\n**Scope:** `invoices:read`", "x-scope": "invoices:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/InvoiceStatus" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/invoices/{id}/pdf": { "get": { "tags": [ "Invoices" ], "summary": "Download an invoice PDF", "operationId": "invoicesPdf", "description": "The invoice printed with the company's template, including the fiscal number and QR code once posted.\n\n**Scope:** `invoices:read`", "x-scope": "invoices:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The id." } ], "responses": { "200": { "description": "The file.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/customers": { "get": { "tags": [ "Customers" ], "summary": "List customers", "operationId": "customersIndex", "description": "Sorted by name.\n\n**Scope:** `customers:read`", "x-scope": "customers:read", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page (default 25, at most 100).", "schema": { "type": "integer" } }, { "name": "search", "in": "query", "required": false, "description": "Part of the name, NTN or email.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of results.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } }, "links": { "type": "object" }, "meta": { "$ref": "#/components/schemas/PageMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Customers" ], "summary": "Create a customer", "operationId": "customersStore", "description": "A registered customer must have an NTN or STRN. Opening balances are not accepted here; import them from the TaxBaaz Import screen.\n\n**Scope:** `customers:write`", "x-scope": "customers:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique text (up to 120 characters). Retrying with the same key and body returns the first answer instead of creating a duplicate.", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Customer" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "customer_type", "filer_status" ], "properties": { "name": { "type": "string", "maxLength": 255 }, "business_name": { "type": "string", "nullable": true, "maxLength": 255 }, "customer_type": { "type": "string", "enum": [ "registered", "unregistered", "export", "government" ] }, "ntn": { "type": "string", "nullable": true }, "cnic": { "type": "string", "nullable": true }, "strn": { "type": "string", "nullable": true }, "province": { "type": "string", "nullable": true, "maxLength": 100 }, "address": { "type": "string", "nullable": true, "maxLength": 255 }, "city": { "type": "string", "nullable": true, "maxLength": 100 }, "phone": { "type": "string", "nullable": true, "maxLength": 30 }, "email": { "type": "string", "format": "email", "nullable": true, "maxLength": 255 }, "contact_person": { "type": "string", "nullable": true, "maxLength": 255 }, "credit_limit": { "type": "number", "nullable": true }, "credit_days": { "type": "integer", "nullable": true }, "payment_terms": { "type": "string", "nullable": true, "maxLength": 255 }, "filer_status": { "type": "string", "enum": [ "filer", "non-filer", "unknown" ] }, "notes": { "type": "string", "nullable": true, "maxLength": 2000 } } }, "example": { "name": "Ali Traders", "customer_type": "registered", "ntn": "1234567", "filer_status": "filer", "city": "Lahore" } } } } } }, "/v1/customers/{id}": { "get": { "tags": [ "Customers" ], "summary": "Get a customer", "operationId": "customersShow", "description": "One customer.\n\n**Scope:** `customers:read`", "x-scope": "customers:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Customer" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/items": { "get": { "tags": [ "Items" ], "summary": "List items", "operationId": "itemsIndex", "description": "Sorted by name.\n\n**Scope:** `items:read`", "x-scope": "items:read", "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page (default 25, at most 100).", "schema": { "type": "integer" } }, { "name": "search", "in": "query", "required": false, "description": "Part of the name or code.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of results.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Item" } }, "links": { "type": "object" }, "meta": { "$ref": "#/components/schemas/PageMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Items" ], "summary": "Create an item", "operationId": "itemsStore", "description": "The code must be unique in your company.\n\n**Scope:** `items:write`", "x-scope": "items:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique text (up to 120 characters). Retrying with the same key and body returns the first answer instead of creating a duplicate.", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Item" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "code", "sale_rate" ], "properties": { "name": { "type": "string", "maxLength": 255 }, "code": { "type": "string", "maxLength": 50 }, "description": { "type": "string", "nullable": true, "maxLength": 2000 }, "type": { "type": "string", "nullable": true, "enum": [ "goods", "service" ] }, "hs_code": { "type": "string", "nullable": true, "maxLength": 20 }, "unit_id": { "type": "integer", "nullable": true }, "sale_rate": { "type": "number" }, "purchase_rate": { "type": "number", "nullable": true }, "tax_rate_id": { "type": "integer", "nullable": true }, "sro_schedule_no": { "type": "string", "nullable": true, "maxLength": 50 }, "sro_item_serial_no": { "type": "string", "nullable": true, "maxLength": 50 }, "tax_treatment": { "type": "string", "nullable": true, "enum": [ "standard", "reduced", "zero_rated", "exempt", "further_tax_applicable" ] } } }, "example": { "code": "ITM-001", "name": "Copper Wire 2.5mm", "sale_rate": 1500, "hs_code": "8544.4990", "tax_rate_id": 1 } } } } } }, "/v1/items/{id}": { "get": { "tags": [ "Items" ], "summary": "Get an item", "operationId": "itemsShow", "description": "One item.\n\n**Scope:** `items:read`", "x-scope": "items:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Item" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/receipts": { "post": { "tags": [ "Receipts" ], "summary": "Record a receipt", "operationId": "receiptsStore", "description": "Records money received from a customer and posts it to the books. Apply it to invoices with `allocations`, or send `\"auto_allocate\": true` to pay the oldest invoices first; anything left stays as the customer's advance.\n\n**Scope:** `receipts:write`", "x-scope": "receipts:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique text (up to 120 characters). Retrying with the same key and body returns the first answer instead of creating a duplicate.", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Receipt" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "customer_id", "amount", "method" ], "properties": { "branch_id": { "type": "integer", "nullable": true }, "receipt_date": { "type": "string", "format": "date", "nullable": true }, "customer_id": { "type": "integer" }, "amount": { "type": "number" }, "method": { "type": "string", "enum": [ "cash", "bank_transfer", "cheque", "card", "online" ] }, "bank_account_id": { "type": "integer", "nullable": true }, "reference_no": { "type": "string", "nullable": true, "maxLength": 100 }, "cheque_no": { "type": "string", "nullable": true, "maxLength": 50 }, "cheque_date": { "type": "string", "format": "date", "nullable": true }, "remarks": { "type": "string", "nullable": true, "maxLength": 1000 }, "auto_allocate": { "type": "boolean", "nullable": true }, "allocations": { "type": "array", "items": { "type": "object", "required": [ "invoice_id", "amount" ], "properties": { "invoice_id": { "type": "integer" }, "amount": { "type": "number" } } }, "nullable": true } } }, "example": { "customer_id": 12, "amount": 25000, "method": "bank_transfer", "reference_no": "TRX-8891", "auto_allocate": true } } } } } }, "/v1/reports": { "get": { "tags": [ "Reports" ], "summary": "List reports", "operationId": "reportsIndex", "description": "The reports the user behind the key may run, with the filters each accepts.\n\n**Scope:** `reports:read`", "x-scope": "reports:read", "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ReportList" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/reports/{key}": { "get": { "tags": [ "Reports" ], "summary": "Run a report", "operationId": "reportsShow", "description": "Runs one of the reports from the list. Pass its filters as query parameters (for example `period=this_month`, `from`, `to`, `branch_id`). Paged with `page` and `per_page`.\n\n**Scope:** `reports:read`", "x-scope": "reports:read", "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The report key from GET /v1/reports." }, { "name": "page", "in": "query", "required": false, "description": "Page number, starting at 1.", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "required": false, "description": "Rows per page (default 25, at most 100).", "schema": { "type": "integer" } }, { "name": "sort", "in": "query", "required": false, "description": "A sortable column key.", "schema": { "type": "string" } }, { "name": "direction", "in": "query", "required": false, "description": "asc or desc.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ReportResult" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/accounting/trial-balance": { "get": { "tags": [ "Accounting" ], "summary": "Trial balance", "operationId": "accountingTrialBalance", "description": "Debit and credit balance of every account as at a date. Company-wide, so it needs a user who can see all branches.\n\n**Scope:** `accounting:read`", "x-scope": "accounting:read", "parameters": [ { "name": "as_of", "in": "query", "required": false, "description": "Defaults to today.", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TrialBalance" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/accounting/profit-and-loss": { "get": { "tags": [ "Accounting" ], "summary": "Profit and loss", "operationId": "accountingProfitAndLoss", "description": "Income, expenses and net income for a period. Company-wide.\n\n**Scope:** `accounting:read`", "x-scope": "accounting:read", "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Defaults to the first of this month.", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": false, "description": "Defaults to today.", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProfitAndLoss" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/accounting/balance-sheet": { "get": { "tags": [ "Accounting" ], "summary": "Balance sheet", "operationId": "accountingBalanceSheet", "description": "Assets, liabilities and equity as at a date. Company-wide.\n\n**Scope:** `accounting:read`", "x-scope": "accounting:read", "parameters": [ { "name": "as_of", "in": "query", "required": false, "description": "Defaults to today.", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BalanceSheet" } } } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Your API key: \"Authorization: Bearer tbx_live_...\". Create keys under Settings > API & Webhooks." } }, "schemas": { "Invoice": { "type": "object", "properties": { "id": { "type": "integer" }, "number": { "type": "string", "description": "The invoice number; null while a draft", "nullable": true }, "document_type": { "type": "string" }, "status": { "type": "string", "description": "draft, submitted, posted, cancelled" }, "invoice_date": { "type": "string", "nullable": true, "format": "date" }, "due_date": { "type": "string", "nullable": true, "format": "date" }, "currency": { "type": "string" }, "customer": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string", "nullable": true }, "ntn": { "type": "string", "nullable": true }, "cnic": { "type": "string", "nullable": true }, "strn": { "type": "string", "nullable": true } } }, "totals": { "type": "object", "properties": { "subtotal_excl_tax": { "type": "string", "description": "Before discount and tax (decimal string, 4 places)" }, "discount": { "type": "string", "description": "Total discount (decimal string, 4 places)" }, "taxable_value": { "type": "string", "description": "Taxable value (decimal string, 4 places)" }, "sales_tax": { "type": "string", "description": "Sales tax (decimal string, 4 places)" }, "further_tax": { "type": "string", "description": "Further tax (decimal string, 4 places)" }, "extra_tax": { "type": "string", "description": "Extra tax (decimal string, 4 places)" }, "fed": { "type": "string", "description": "FED (decimal string, 4 places)" }, "other_charges": { "type": "string", "description": "Other charges (decimal string, 4 places)" }, "freight": { "type": "string", "description": "Freight (decimal string, 4 places)" }, "rounding_adjustment": { "type": "string", "description": "Rounding (decimal string, 4 places)" }, "grand_total": { "type": "string", "description": "Amount payable (decimal string, 4 places)" }, "amount_paid": { "type": "string", "description": "Paid so far (decimal string, 4 places)" }, "balance_due": { "type": "string", "description": "Still owed (decimal string, 4 places)" } } }, "payment_status": { "type": "string", "description": "unpaid, partial, paid" }, "authority": { "type": "object", "properties": { "name": { "type": "string", "description": "fbr, pra or null when the document does not go to an authority", "nullable": true }, "status": { "type": "string", "description": "pending, queued, posted, failed, not_required", "nullable": true }, "fbr_invoice_number": { "type": "string", "description": "The FBR fiscal number once posted", "nullable": true }, "pra_invoice_number": { "type": "string", "description": "The PRA fiscal number once posted", "nullable": true }, "is_test": { "type": "boolean", "description": "Posted to a sandbox connection" }, "last_error": { "type": "string", "description": "Why the last attempt failed, if it did", "nullable": true } } }, "lines": { "type": "array", "items": { "type": "object", "properties": { "item_id": { "type": "integer", "nullable": true }, "description": { "type": "string", "nullable": true }, "quantity": { "type": "string" }, "unit_price": { "type": "string" }, "discount_amount": { "type": "string" }, "value_excl_tax": { "type": "string" }, "tax_rate_percent": { "type": "string" }, "sales_tax_amount": { "type": "string" }, "further_tax_amount": { "type": "string" }, "total_incl_tax": { "type": "string" }, "hs_code": { "type": "string", "nullable": true } } } }, "notes": { "type": "string", "nullable": true }, "is_imported": { "type": "boolean", "description": "Loaded from before the company joined TaxBaaz" }, "links": { "type": "object", "properties": { "pdf": { "type": "string", "description": "URL of the PDF (needs your key)", "nullable": true } } }, "created_at": { "type": "string", "nullable": true, "format": "date-time" }, "posted_at": { "type": "string", "nullable": true, "format": "date-time" } } }, "InvoiceStatus": { "type": "object", "properties": { "id": { "type": "integer" }, "number": { "type": "string", "nullable": true }, "status": { "type": "string" }, "payment_status": { "type": "string" }, "authority": { "type": "object", "properties": { "name": { "type": "string", "description": "fbr, pra or null when the document does not go to an authority", "nullable": true }, "status": { "type": "string", "description": "pending, queued, posted, failed, not_required", "nullable": true }, "fbr_invoice_number": { "type": "string", "description": "The FBR fiscal number once posted", "nullable": true }, "pra_invoice_number": { "type": "string", "description": "The PRA fiscal number once posted", "nullable": true }, "is_test": { "type": "boolean", "description": "Posted to a sandbox connection" }, "last_error": { "type": "string", "description": "Why the last attempt failed, if it did", "nullable": true } } } } }, "Customer": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "business_name": { "type": "string", "nullable": true }, "customer_type": { "type": "string", "description": "registered, unregistered, export, government" }, "ntn": { "type": "string", "nullable": true }, "cnic": { "type": "string", "nullable": true }, "strn": { "type": "string", "nullable": true }, "province": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "contact_person": { "type": "string", "nullable": true }, "credit_limit": { "type": "string", "nullable": true }, "credit_days": { "type": "integer", "nullable": true }, "payment_terms": { "type": "string", "nullable": true }, "filer_status": { "type": "string" }, "is_active": { "type": "boolean" }, "created_at": { "type": "string", "nullable": true, "format": "date-time" } } }, "Item": { "type": "object", "properties": { "id": { "type": "integer" }, "code": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "type": { "type": "string", "description": "goods or service" }, "hs_code": { "type": "string", "nullable": true }, "unit_id": { "type": "integer", "nullable": true }, "sale_rate": { "type": "string" }, "purchase_rate": { "type": "string" }, "tax_rate_id": { "type": "integer", "nullable": true }, "tax_treatment": { "type": "string" }, "sro_schedule_no": { "type": "string", "nullable": true }, "sro_item_serial_no": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" } } }, "Receipt": { "type": "object", "properties": { "id": { "type": "integer" }, "number": { "type": "string" }, "receipt_date": { "type": "string", "nullable": true, "format": "date" }, "customer_id": { "type": "integer" }, "amount": { "type": "string" }, "method": { "type": "string" }, "reference_no": { "type": "string", "nullable": true }, "cheque_no": { "type": "string", "nullable": true }, "cheque_status": { "type": "string", "nullable": true }, "remarks": { "type": "string", "nullable": true }, "allocations": { "type": "array", "items": { "type": "object", "properties": { "invoice_id": { "type": "integer" }, "amount": { "type": "string" } } } }, "created_at": { "type": "string", "nullable": true, "format": "date-time" } } }, "Me": { "type": "object", "properties": { "company": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "acting_as": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "key": { "type": "object", "properties": { "name": { "type": "string" }, "environment": { "type": "string", "description": "live or sandbox" }, "scopes": { "type": "array", "items": { "type": "string" } }, "expires_at": { "type": "string", "nullable": true, "format": "date-time" } } }, "rate_limit_per_minute": { "type": "integer" }, "api_version": { "type": "string" } } }, "ReportList": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "title": { "type": "string" }, "category": { "type": "string" }, "description": { "type": "string" }, "filters": { "type": "array", "items": { "type": "string" } } } } }, "ReportResult": { "type": "object", "properties": { "key": { "type": "string" }, "title": { "type": "string" }, "columns": { "type": "array", "items": { "type": "object" } }, "rows": { "type": "array", "items": { "type": "object" } }, "totals": { "type": "object", "description": "Totals row when the report has one", "nullable": true } } }, "TrialBalance": { "type": "object", "properties": { "as_of": { "type": "string", "format": "date" }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "debit": { "type": "string" }, "credit": { "type": "string" } } } }, "total_debit": { "type": "string" }, "total_credit": { "type": "string" }, "balanced": { "type": "boolean" } } }, "ProfitAndLoss": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "income": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "amount": { "type": "string" } } } }, "expenses": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "amount": { "type": "string" } } } }, "total_income": { "type": "string" }, "total_expenses": { "type": "string" }, "net_income": { "type": "string" } } }, "BalanceSheet": { "type": "object", "properties": { "as_of": { "type": "string", "format": "date" }, "assets": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "amount": { "type": "string" } } } }, "liabilities": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "amount": { "type": "string" } } } }, "equity": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "amount": { "type": "string" } } } }, "current_year_earnings": { "type": "string" }, "total_assets": { "type": "string" }, "total_liabilities": { "type": "string" }, "total_equity": { "type": "string" }, "balances": { "type": "boolean" } } }, "PageMeta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "from": { "type": "integer", "nullable": true }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "to": { "type": "integer", "nullable": true }, "total": { "type": "integer" } } }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable, for programs" }, "message": { "type": "string", "description": "For people" }, "details": { "type": "object", "description": "Per-field problems, required scopes, upgrade links...", "nullable": true }, "request_id": { "type": "string", "description": "Quote this when contacting support" } } } } } }, "responses": { "Unauthenticated": { "description": "The key is missing, wrong, expired or revoked (code `unauthenticated` or `invalid_token`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "The key lacks the scope (`insufficient_scope`), the plan has no API access or the subscription is read-only (402), or the user behind the key may not do this (`forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ValidationFailed": { "description": "A field is missing or invalid (`validation_failed`, with `details` per field) or a business rule refused it (`business_rule_violation`, `authority_validation_failed`, `credit_limit_exceeded`, `period_closed`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "Too many requests (`rate_limited`). Wait the seconds in the `Retry-After` header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "x-scopes": { "invoices:read": "List and read invoices, their FBR/PRA status and PDFs", "invoices:write": "Create invoices and other sales documents", "customers:read": "List and read customers", "customers:write": "Create customers", "items:read": "List and read items", "items:write": "Create items", "receipts:write": "Record customer receipts", "reports:read": "Run reports", "accounting:read": "Read the trial balance, profit and loss and balance sheet" }, "x-webhooks": { "events": { "invoice.created": "A sales document was created", "invoice.posted": "An invoice was accepted by FBR/PRA and has its fiscal number", "invoice.failed": "FBR/PRA rejected an invoice or retries ran out", "payment.received": "A customer receipt was recorded", "journal.posted": "A journal entry was posted to the ledger" }, "example": { "id": "evt_9x2k...", "type": "invoice.posted", "api_version": "v1", "created_at": "2026-09-19T10:15:00+05:00", "data": { "id": 4711, "number": "INV-000123", "status": "posted", "authority": { "name": "fbr", "status": "posted", "fbr_invoice_number": "1234567890123456789" } } }, "headers": { "X-TaxBaaz-Event": "The event name.", "X-TaxBaaz-Event-Id": "Same id inside the body; use it to ignore duplicates.", "X-TaxBaaz-Delivery": "This delivery attempt's id.", "X-TaxBaaz-Timestamp": "Unix time the request was signed.", "X-TaxBaaz-Signature": "t=,v1=.\" with your signing secret>" }, "retries": "A delivery that does not get a 2xx within 10 seconds is retried after 1, 5, 30, 120, 360 minutes, then abandoned. An endpoint that fails 25 deliveries in a row is switched off." } }