BasePipeAPI documentationbasepipe.io

BasePipe API

BasePipe is the accounting engine inside your product. You call the API; your customers see your brand. Every sale, purchase, payment and bank line becomes a balanced double-entry record, and the reports come out right because the books can't be got wrong.

This guide gets you from a test key to a recorded invoice and a profit and loss report. The reference lists every endpoint.

Getting started

Your keys

BasePipe gives you two kinds of key. Keep both on your server; never put them in an app or a web page.

bp_test_…Practice. Works only on practice businesses. Nothing here is real, so build and test freely.
bp_live_…Live. Works only on live businesses. Issued when you go live.

Your first test key comes from BasePipe when you're set up. After that, your admin screen makes and revokes keys under API keys.

Your first call

The API lives at https://api.basepipe.io. Send JSON, and your key in the Authorization header.

curl https://api.basepipe.io/v1/businesses \
  -H "Authorization: Bearer bp_test_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Al Noor Catering"}'

That makes a practice business with its own books: a starter list of accounts, Qatari riyals as its currency, and a financial year starting in January. Keep the id it returns; every other call about this business uses it.

{
  "id": "01a1e8c2-…",
  "name": "Al Noor Catering",
  "base_currency": "QAR",
  "livemode": false,
  "fiscal_year_start_month": 1,
  "timezone": "Asia/Qatar",
  "created_at": "2026-11-16T09:12:00Z"
}

How the API works

Amounts

Every amount is a whole number in the smallest unit of the currency. 12.50 QAR is 1250; 99 QAR is 9900. There are no decimals anywhere in the API, so nothing is ever lost to rounding.

Dates

Dates are YYYY-MM-DD, in the business's own time zone. Times are ISO 8601 in UTC.

Errors

A refused request returns a status code and a body like this:

{ "error": { "code": "rejected", "message": "Entry does not balance: debits 2500, credits 100" } }
400invalid_request: a field is missing or in the wrong format. The message names it.
401unauthorised: no key, or a key that's unknown or revoked.
403paused: your account is paused; or a feature that's switched off for you.
404not_found: it doesn't exist, or it belongs to another partner, or to the other mode (practice or live).
409conflict: it already exists, or it has already been done.
422rejected: the books refused it, and the message says why (it doesn't balance, the month is closed, the account doesn't exist).
429too_many_requests: more than 600 requests in a minute. Wait for the Retry-After seconds and try again.

Sending the same thing twice

Networks fail. When you record an entry or make a document, send an Idempotency-Key header with a value of your own (your record's id is ideal). If the same key arrives again, BasePipe returns what it made the first time instead of making it twice.

-H "Idempotency-Key: order-58213"

Lists

Lists return { "data": [ … ] }, newest first. Most take ?limit= (50 by default, at most 200).

The rules of the books

These rules live inside the database, so no app, partner or AI can get round them. Knowing them saves surprises.

  1. Every change to the books is a journal entry, and every entry balances: total debits equal total credits.
  2. A recorded entry is never edited or deleted. A mistake is corrected with a reversal: a new entry that undoes it.
  3. Every entry records who prepared it, who approved it, when, and where it came from.
  4. Once a month is closed, nothing dated in it can change.
  5. Documents (invoices, bills, receipts) start as drafts. A draft touches nothing. Approving it records it in the books and gives it a number, such as INV-000001. After that it can only be voided, which reverses it.

A first sale, start to finish

Using the business made above. Replace $BIZ with its id.

1. Add a customer

POST /v1/businesses/$BIZ/contacts
{ "name": "Gulf Cafe", "kind": "customer" }

2. Draft an invoice

POST /v1/businesses/$BIZ/documents
{
  "kind": "invoice",
  "contact_id": "<the customer's id>",
  "issue_date": "2026-11-01",
  "due_date": "2026-11-30",
  "created_by": "user:fatima",
  "lines": [
    { "description": "Catering, 40 people", "account": "4000", "quantity": 40, "unit_price": 3500 }
  ]
}

The draft comes back with its total worked out: 140000 (1,400.00 QAR). Nothing is in the books yet.

3. Approve it

POST /v1/businesses/$BIZ/documents/<id>/approve
{ "approved_by": "owner:fatima" }

Now it's recorded as INV-000001: the customer owes 1,400.00, and sales are 1,400.00 higher.

4. Send it

POST /v1/businesses/$BIZ/documents/<id>/share

Returns a link to a page the customer can open and print, in your brand. Send it however you like, for example on WhatsApp.

5. Record the payment

POST /v1/businesses/$BIZ/payments
{
  "direction": "in",
  "contact_id": "<the customer's id>",
  "date": "2026-11-10",
  "amount": 40000,
  "money_account": "1010",
  "created_by": "user:fatima",
  "approved_by": "owner:fatima",
  "allocations": [ { "document_id": "<the invoice's id>", "amount": 40000 } ]
}

400.00 arrived in the bank account (1010) against the invoice, which now has 1,000.00 left to pay.

6. See the results

GET /v1/businesses/$BIZ/reports/who-owes-us
GET /v1/businesses/$BIZ/reports/profit-and-loss?from=2026-11-01&to=2026-11-30
GET /v1/businesses/$BIZ/reports/profit-and-loss?from=2026-11-01&to=2026-11-30&format=html&lang=ar

Reports come as JSON, or as a printable page (format=html) in English or Arabic, ready to save as PDF.

The starter accounts

Every new business starts with these. Lines name accounts by their code. A few more (card payments on the way, tax accounts, income received in advance) are added the first time they're needed.

CodeAccountType
1000Cashasset
1010Bank accountasset
1100Money customers oweasset
1200Stockasset
1300Paid in advanceasset
1500Equipmentasset
1510Equipment wear and tear to dateasset
2000Bills to payliability
2100Salaries owedliability
2200Loansliability
3000Owner's capitalequity
3100Owner's drawingsequity
3200Retained earningsequity
3900Opening balancesequity
4000Salesincome
4100Other incomeincome
5000Cost of goods soldexpense
6000Rentexpense
6100Salaries and wagesexpense
6200Electricity and waterexpense
6300Bank feesexpense
6400Marketingexpense
6500Transport and fuelexpense
6600Office suppliesexpense
6700Repairs and maintenanceexpense
6800Equipment wear and tearexpense
6900Other expensesexpense

Ready-made screens

You don't have to build every screen yourself. BasePipe's screens carry your name and colour, and open from one-time links your server asks for.

Owner dashboardThe business owner's home: what's waiting for a yes, sales, bills, bank, reports, the AI bookkeeper. POST /v1/businesses/{id}/dashboard-links returns a link that works once.
Accountant screenFor the person who keeps the books: drafts to check, bank matching, month-end, the trial balance and the full reports. Add accountants with POST /v1/reviewers. You can choose not to offer it.
Sign-upA step-by-step sign-up for new businesses, in English and Arabic: GET /v1/signup-page.
Your admin screenFor your team: businesses, plans and prices, accountants, keys, branding and activity.

Set your name and colour with POST /v1/branding.

WhatsApp

Owners can run their books from WhatsApp: send a photo of a receipt, say "sold 1,200 cash today", ask for an invoice, answer the bookkeeper's questions. Messages come from your own WhatsApp number, in your name.

  1. Register your number: POST /v1/whatsapp-numbers.
  2. Link each owner's phone to their business: POST /v1/businesses/{id}/whatsapp-owners.
  3. Register your approved message templates (for messages sent more than a day after the owner last wrote): POST /v1/whatsapp-templates.

BasePipe sets up the WhatsApp side with you; ask us before your first number.

The AI bookkeeper

Switch it on per plan (ai_bookkeeper on POST /v1/plans) and set the most it may record on its own (ai_auto_limit). Every morning, for each business on that plan, it:

  • records the drafts it's sure of (a known supplier and accounts, no possible duplicate, how it was paid, within the limit);
  • matches and records bank lines whose account is clear;
  • asks the owner a plain question about anything else, on WhatsApp and on their dashboard, and learns from the answer;
  • closes last month once nothing is left open, and sends the owner a summary.

Everything it does is logged and can be undone. Read it with GET /v1/businesses/{id}/bookkeeper.

Plans and billing

Your plans and prices are yours: POST /v1/plans sets the price, free trial, monthly limits and whether the AI bookkeeper is included. New businesses start on your default plan's trial. A business whose trial or paid period ends unpaid becomes read-only until it's paid. Record payments with POST /v1/businesses/{id}/subscription/payments; see what you owe BasePipe each month with GET /v1/billing/statement.

Not there yet

So you can plan around them:

  • Webhooks. BasePipe doesn't call your server yet. For now, read what changed when you need it.
  • Paging beyond 200. Lists return at most 200 items; filter by date to narrow them.
  • Screens inside your app. The ready-made screens open as full pages today, not inside a frame in your app.
  • Live bank feeds. Bank statements are imported from files (CSV, PDF or a photo), not fetched from the bank.

Questions about any of this: ask your contact at BasePipe.

Reference

Every endpoint, grouped by what it's about. 149 in all.

Businesses

List your businesses

GET/v1/businesses

Lists every business your partner account owns in the key's mode. A test key sees only practice businesses and a live key only live ones.

Returns

200 with data: a list of businesses, each with id, name, base_currency, livemode, fiscal_year_start_month, timezone, created_at.

Create a business

POST/v1/businesses

Creates a business with its own set of books. A test key creates a practice business and a live key a live one. By default it gets the starter chart of accounts (Cash 1000, Bank account 1010, Sales 4000, Rent 6000 and so on).

Body

namestringrequiredThe business's name, as it appears on invoices and reports.
base_currencystringThree-letter currency code the books are kept in. Defaults to QAR.
starter_accountsbooleanAdd the starter chart of accounts. Defaults to true. Send false to build the chart yourself.
fiscal_year_start_monthintegerMonth the financial year starts in, from 1 (January) to 12 (December). Defaults to 1.
timezonestringIANA time zone used for the business's 'today', reminders and the daily sales question. Defaults to Asia/Qatar.

Example

{
  "name": "Al Noor Catering",
  "base_currency": "QAR",
  "starter_accounts": true,
  "fiscal_year_start_month": 1,
  "timezone": "Asia/Qatar"
}

Returns

201 with the business: id, name, base_currency, livemode, fiscal_year_start_month, timezone, created_at.

Errors

  • 400 invalid_request: the body is not a JSON object, name is missing, base_currency is not three capital letters, starter_accounts is not true or false, or fiscal_year_start_month is not a whole number from 1 to 12
  • 422 rejected: the time zone is not known (Unknown time zone ...)

Get a business

GET/v1/businesses/{business}

Returns one of your businesses. Use it to read the base currency, financial year start and time zone before recording anything.

Path

businessThe business id.

Returns

200 with id, name, base_currency, livemode, fiscal_year_start_month, timezone, created_at.

Errors

  • 404 not_found: no business with this id belongs to your partner account in the key's mode

Check the API and your key

GET/v1/health

Answers with ok when the API is up and your key is accepted. Like every /v1 route it needs a valid key, so it is a quick way to test a new key.

Returns

200 with {"ok": true}.

Errors

  • 401 unauthorised: the Authorization header is missing, is not "Bearer bp_...", or the key is not recognised or has been revoked
  • 403 paused: your partner account is paused
  • 429 too_many_requests: too many requests from your partner account; wait a minute (see the retry-after header)

Accounts

List the chart of accounts

GET/v1/businesses/{business}/accounts

Lists every account in the business's books, ordered by code. Entries refer to accounts by these codes.

Path

businessThe business id.

Returns

200 with data: a list of accounts, each with id, code, name, name_ar, type (asset, liability, equity, income or expense), parent_id, is_active.

Errors

  • 404 not_found: the business is not yours or is in the other mode

Add an account

POST/v1/businesses/{business}/accounts

Adds an account to the business's chart of accounts, for example a second bank account or a new kind of expense. The report group decides where the account appears on the balance sheet and profit and loss.

Path

businessThe business id.

Body

codestringrequiredUnique code in this business, up to 20 letters, numbers, dots or dashes, e.g. 1020.
namestringrequiredAccount name in English.
name_arstringAccount name in Arabic.
typestringrequiredOne of asset, liability, equity, income, expense.
report_groupstringWhere it shows in reports. Must suit the type: asset takes cash, current_asset or fixed_asset; liability takes current_liability or long_term_liability; equity takes equity; income takes sales or other_income; expense takes cost_of_sales, operating_expense or other_expense. If left out, reports use current_asset, current_liability, equity, sales or operating_expense by type.

Example

{
  "code": "1020",
  "name": "QNB current account",
  "name_ar": "حساب QNB الجاري",
  "type": "asset",
  "report_group": "cash"
}

Returns

201 with the account: id, code, name, name_ar, type, parent_id, is_active, report_group.

Errors

  • 400 invalid_request: code, name or type is missing, type is not one of the five types, the code has characters other than letters, numbers, dots or dashes or is over 20 long, or the report group doesn't suit the type
  • 404 not_found: the business is not yours or is in the other mode
  • 409 conflict: an account with this code already exists

Journal entries

List journal entries

GET/v1/businesses/{business}/entries

Lists the business's journal entries, newest number first. To page back, pass next_before from the last page as before.

Path

businessThe business id.

Query

limitintegerHow many entries to return, 1 to 200. Defaults to 50.
beforeintegerOnly entries with a number below this one.

Returns

200 with data (entries in the same shape as Get a journal entry), has_more, and next_before (the number to pass as before for the next page, or null).

Errors

  • 400 invalid_request: before is not an entry number
  • 404 not_found: the business is not yours or is in the other mode

Record a journal entry

POST/v1/businesses/{business}/entries

Records a balanced journal entry: total debits must equal total credits, with at least two lines. Saved entries are never edited; to correct one, reverse it. Send an Idempotency-Key header so a retried request returns the entry already recorded instead of a second one.

Path

businessThe business id.

Body

datedaterequiredEntry date, YYYY-MM-DD. Its month must be open.
sourcestringrequiredWhere the entry comes from: document, manual (an accountant's correction, a bank fee), scheduled (a regular run such as monthly wear and tear) or opening (opening balances).
source_refstringYour reference for what the entry came from, such as a document number. Required when source is document.
memostringrequiredWhy the entry was made.
created_bystringrequiredWho prepared the entry.
approved_bystringrequiredWho approved the entry.
linesarrayrequiredAt least two lines.
lines[].accountstringrequiredAccount code, e.g. 6300. The account must be in this business's books and switched on.
lines[].debitintegerDebit amount in the smallest currency unit (12.50 QAR = 1250). Each line has a debit or a credit above zero, not both.
lines[].creditintegerCredit amount in the smallest currency unit.
lines[].descriptionstringA note for this line.
lines[].branchstringBranch to tag the line with, by id or name. Must exist and be switched on.
lines[].projectstringProject to tag the line with, by id or name. Must exist and be switched on.

Example

{
  "date": "2026-11-05",
  "source": "manual",
  "memo": "QNB monthly account charge",
  "created_by": "Fatima Al-Kuwari",
  "approved_by": "Fatima Al-Kuwari",
  "lines": [
    {
      "account": "6300",
      "debit": 1500,
      "description": "Monthly bank charge"
    },
    {
      "account": "1010",
      "credit": 1500
    }
  ]
}

Returns

201 with the entry: id, number (runs 1, 2, 3 per business with no gaps), date, source, source_ref, memo, created_by, approved_by, reverses_entry_id, posted_at, and lines (line_no, account, account_name, debit, credit, description). A repeated Idempotency-Key returns the earlier entry.

Errors

  • 400 invalid_request: the body is not a JSON object; date is not YYYY-MM-DD; source is not document, manual, scheduled or opening; memo, created_by or approved_by is missing; lines is not a list; a line has no account code; or a debit or credit is not a whole number
  • 404 not_found: the business is not yours or is in the other mode
  • 422 rejected: fewer than two lines; an account is not in the books or is switched off; a line has both or neither of debit and credit; debits and credits don't balance; the month is closed; a branch or project doesn't exist or is switched off; or source is document with no source_ref

Get a journal entry

GET/v1/businesses/{business}/entries/{entry}

Returns one journal entry with its lines.

Path

businessThe business id.
entryThe entry id.

Returns

200 with id, number, date, source (document, manual, scheduled, opening or reversal), source_ref, memo, created_by, approved_by, reverses_entry_id, posted_at, and lines (line_no, account, account_name, debit, credit, description).

Errors

  • 404 not_found: the business is not yours, or there is no entry with this id in it

Reverse a journal entry

POST/v1/businesses/{business}/entries/{entry}/reverse

Corrects a saved entry by recording its mirror image: every debit becomes a credit and the other way round. The original stays as it was. If the original's month is closed, pass a date in an open month.

Path

businessThe business id.
entryThe id of the entry to reverse.

Body

reasonstringrequiredWhy it is reversed. The memo becomes 'Reversal of entry <number>: <reason>'.
bystringrequiredWho reversed it (recorded as both preparer and approver).
datedateDate of the reversal, YYYY-MM-DD. Defaults to the original entry's date.

Example

{
  "reason": "Bank charge was posted twice",
  "by": "Fatima Al-Kuwari",
  "date": "2026-11-10"
}

Returns

201 with the new reversal entry: source reversal, reverses_entry_id set to the original's id, and its lines.

Errors

  • 400 invalid_request: the body is not a JSON object, reason or by is missing, or date is not YYYY-MM-DD
  • 404 not_found: the business is not yours, or there is no entry with this id in it
  • 422 rejected: the entry is itself a reversal, it has already been reversed, or the reversal's month is closed

Close a month

POST/v1/businesses/{business}/months/{month}/close

Closes a month so nothing more can be recorded in it, for example after the accountant has checked it. Closing a month that is already closed changes nothing.

Path

businessThe business id.
monthThe month, YYYY-MM, e.g. 2026-10.

Body

bystringrequiredWho closed the month.

Example

{
  "by": "Fatima Al-Kuwari"
}

Returns

200 with month and status (closed).

Errors

  • 400 invalid_request: the month doesn't look like 2026-10, the body is not a JSON object, or by is missing
  • 404 not_found: the business is not yours or is in the other mode

Get the trial balance

GET/v1/businesses/{business}/reports/trial-balance

Totals every account's debits and credits up to and including a date. Only accounts with activity are listed; total_debit always equals total_credit.

Path

businessThe business id.

Query

as_ofdateLast day to include, YYYY-MM-DD. Defaults to today (UTC).

Returns

200 with as_of, currency, accounts (code, name, type, debit, credit, balance; balance is debit minus credit for asset and expense accounts and credit minus debit for the rest), total_debit, total_credit.

Errors

  • 400 invalid_request: as_of is not YYYY-MM-DD
  • 404 not_found: the business is not yours or is in the other mode

Move money between own accounts

POST/v1/businesses/{business}/transfers

Records money moved between the business's own bank, cash and card accounts, for example cash taken from the till to the bank. It is saved as a manual journal entry debiting the receiving account and crediting the sending one. Send an Idempotency-Key header to make retries safe.

Path

businessThe business id.

Body

datedaterequiredTransfer date, YYYY-MM-DD. Its month must be open.
from_accountstringrequiredCode of the account the money leaves.
to_accountstringrequiredCode of the account the money goes into.
amountintegerrequiredAmount above zero in the smallest currency unit (12.50 QAR = 1250).
memostringWhy. Defaults to 'Transfer from <account> to <account>'.
created_bystringrequiredWho prepared it.
approved_bystringrequiredWho approved it.

Example

{
  "date": "2026-11-06",
  "from_account": "1000",
  "to_account": "1010",
  "amount": 850000,
  "memo": "Till cash deposited at QNB",
  "created_by": "Fatima Al-Kuwari",
  "approved_by": "Fatima Al-Kuwari"
}

Returns

201 with the journal entry, in the same shape as Record a journal entry (source manual, source_ref transfer).

Errors

  • 400 invalid_request: date is not YYYY-MM-DD; from_account, to_account, created_by or approved_by is missing; or amount is not a whole number above zero
  • 404 not_found: the business is not yours or is in the other mode
  • 422 rejected: an account is not in the books or is switched off; both accounts are the same; an account is not an asset or liability (bank, cash or card); both are liabilities; or the month is closed

Customers and suppliers

List customers and suppliers

GET/v1/businesses/{business}/contacts

Lists the business's contacts in name order. Filter by kind to get only customers or only suppliers; contacts of kind both are included in either filter.

Path

businessId of the business. Test keys only see practice businesses; live keys only see live ones.

Query

kindstringcustomer, supplier or both. customer or supplier also returns contacts of kind both.

Returns

200 with data: a list of contacts, each with id, kind, name, name_ar, phone, email, tax_number, address, country, is_resident, default_tax, created_at.

Errors

  • 400 invalid_request: kind is not customer, supplier or both.
  • 404 not_found: the business does not exist or is not visible to this key.

Add a customer or supplier

POST/v1/businesses/{business}/contacts

Adds a customer, a supplier, or a contact that is both to the business's books. Invoices, bills and credits must name a contact; expenses and cash sales may. A supplier based outside Qatar (is_resident false) gets the 5% withholding tax code WHT5 as its default tax unless you send default_tax yourself.

Path

businessId of the business. Test keys only see practice businesses; live keys only see live ones.

Body

kindstringrequiredcustomer, supplier or both. A customer can be used on invoices, cash sales and credit notes; a supplier on bills, expenses and supplier credits; both on either side.
namestringrequiredThe contact's name as it should appear on documents.
name_arstringThe name in Arabic. Shown under the English name on shared invoices and matched when owners write in Arabic.
phonestringPhone number, free text.
emailstringEmail address, free text.
tax_numberstringThe contact's tax registration number. Printed on shared invoices.
addressstringPostal address, free text. Printed on shared invoices.
countrystringTwo-letter country code such as QA or AE. Stored in capitals.
is_residentbooleanWhether the contact is resident in Qatar. Defaults to true. false on a supplier (or both) with no default_tax sets up and uses WHT5.
default_taxstringCode of a tax code already set up for the business. Used on every document line for this contact that leaves out "tax". Send null for no default.

Example

{
  "kind": "supplier",
  "name": "Doha Flour Mill",
  "name_ar": "مطحنة الدوحة للدقيق",
  "phone": "+974 4444 1234",
  "email": "accounts@dohaflourmill.qa",
  "tax_number": "QA300123456",
  "address": "Street 24, Industrial Area, Doha",
  "country": "QA",
  "is_resident": true
}

Returns

201 with the contact: id, kind, name, name_ar, phone, email, tax_number, address, country, is_resident, default_tax (tax code or null), created_at.

Errors

  • 400 invalid_request: kind is not customer, supplier or both; name is missing; a text field is not text; country is not two letters; is_resident is not true or false.
  • 400 invalid_request: the default_tax code is not set up for this business; nothing is saved.
  • 404 not_found: the business does not exist or is not visible to this key.

Documents

List documents

GET/v1/businesses/{business}/documents

Lists the business's documents, newest issue date first. Filter by kind and status, for example status=draft to find drafts waiting for approval.

Path

businessId of the business. Test keys only see practice businesses; live keys only see live ones.

Query

kindstringinvoice, bill, expense, cash_sale, credit_note or supplier_credit.
statusstringdraft (not in the books yet), recorded (approved and in the books) or void (cancelled; its entry was reversed).
limitintegerHow many to return, 1 to 200. Defaults to 50.

Returns

200 with data: a list of documents in the same shape as the create response, including lines and credits.

Errors

  • 400 invalid_request: kind or status is not one of the allowed values.
  • 404 not_found: the business does not exist or is not visible to this key.

Create a draft document

POST/v1/businesses/{business}/documents

Creates a draft invoice, bill, expense, cash sale, credit note or supplier credit. A draft is not in the books and has no number; approve it to record it. Invoices and bills are settled later by payments; expenses and cash sales were paid on the spot and name the money account used; credit notes and supplier credits reverse sales or purchases and are applied to invoices or bills, or refunded.

Path

businessId of the business. Test keys only see practice businesses; live keys only see live ones.

Body

kindstringrequiredinvoice (a sale the customer pays later), bill (a purchase you pay later), expense (a purchase already paid), cash_sale (a sale paid on the spot), credit_note (takes a sale back and lowers what a customer owes), or supplier_credit (takes a purchase back and lowers what you owe a supplier). The kind cannot be changed later.
contact_idstringId of a contact. Required for invoice, bill, credit_note and supplier_credit; optional for expense and cash_sale. Sales kinds (invoice, cash_sale, credit_note) need a customer or both; purchase kinds (bill, expense, supplier_credit) need a supplier or both.
issue_datedaterequiredThe document's date, YYYY-MM-DD. The entry is recorded on this date when approved, so its month must be open by then.
due_datedateWhen an invoice or bill must be paid, YYYY-MM-DD. Defaults to issue_date (due on receipt). Ignored for other kinds, whose due date is always the issue date.
referencestringYour own reference, such as the supplier's invoice number or a purchase order number.
memostringA note on the document.
created_bystringrequiredWho prepared the draft, such as a user's email or name. Kept on the document and its entry.
money_accountstringExpense and cash_sale only: code of the account the money was paid from or into, such as 1000 (Cash) or 1010 (Bank account). Must be an asset account; for an expense it can also be an equity account such as 3000 when the owner paid personally. Can be left out on the draft but is needed before approval. Must be left out for invoice, bill, credit_note and supplier_credit.
party_namestringThe other party's name when there is no contact, such as the shop on a receipt. Used in the entry's description and in duplicate checks.
attachment_refstringA reference to a stored file for this document. Set by the receipts endpoint; usually left out.
confidencenumberFrom 0 to 1: how sure whoever prepared the draft (for example an AI reader) was that it is right. Informational only.
currencystringThree-letter currency code of the document, such as USD or AED. Defaults to the business's currency. Line amounts are in this currency's smallest unit.
ratenumberFor a document in another currency: how many units of the business's currency one unit of this currency is worth on the issue date (for example 3.64 for USD to QAR). If left out it is looked up from your exchange rates and BasePipe's fixed pegs; a document with no rate can be saved but not approved.
branchstringName or id of a branch tag for the whole document. Lines without their own branch use it.
projectstringName or id of a project tag for the whole document. Lines without their own project use it.
linesarrayrequiredAt least one line. The document total is the sum of each line's amount plus its tax (withholding tax is subtracted instead).
lines[].descriptionstringWhat the line is for. Required unless the line names an item, in which case it defaults to the item's name.
lines[].accountstringCode of the account the line goes to, such as 4000 (Sales) or 6000 (Rent). Each line needs account or item. With an item on a sales document it defaults to the item's sales account and must be an income account; on a purchase document the line always goes to the item's stock account, and any account given must be that one.
lines[].itemstringCode of a stock item. Approving the document moves stock: bills and expenses bring it in at the line amount, invoices and cash sales take it out at average cost, credit notes bring returns back in, supplier credits send it back out.
lines[].quantitynumberHow many, above zero. Defaults to 1. Can have decimals, such as 2.5 kg.
lines[].unit_priceintegerrequiredPrice of one unit before discount and tax, in the smallest unit of the document's currency (12.50 QAR is 1250). Must be above zero.
lines[].discountintegerAn amount taken off the line, in the smallest currency unit. 0 means no discount. Must be less than quantity x unit_price. Give discount or discount_percent, not both.
lines[].discount_percentnumberA percentage taken off quantity x unit_price, from 0 up to but not including 100; the result is rounded to the nearest unit. Give discount or discount_percent, not both.
lines[].taxstringCode of a tax code set up for the business. Leave the field out to use the contact's default tax code; send null for no tax. Output (sales) codes only go on invoices, cash sales and credit notes; input and withholding codes only on bills, expenses and supplier credits. Tax is the line amount (after discount) x the code's rate, rounded.
lines[].branchstringName or id of a branch tag for this line only.
lines[].projectstringName or id of a project tag for this line only.

Example

{
  "kind": "invoice",
  "contact_id": "01936f4e-8a2b-7c3d-9e4f-5a6b7c8d9e0f",
  "issue_date": "2026-11-16",
  "due_date": "2026-12-16",
  "reference": "PO-4471",
  "memo": "Catering for the National Day staff lunch",
  "created_by": "fatima@gulfcafe.qa",
  "lines": [
    {
      "description": "Lunch buffet, per person",
      "account": "4000",
      "quantity": 40,
      "unit_price": 6500,
      "discount_percent": 10
    },
    {
      "description": "Delivery and setup",
      "account": "4100",
      "quantity": 1,
      "unit_price": 25000,
      "tax": null
    }
  ]
}

Returns

201 with the draft document: id, kind, status (draft), number (null until approved), contact {id, name}, party_name, money_account, attachment_ref, confidence, currency, rate, base_total (null until approved), issue_date, due_date, reference, memo, total, paid, outstanding, created_by, created_at, approved_by, recorded_at, entry_id, voided_by, voided_at, void_reason, branch, project, order_id, recurring_id, lines [{line_no, description, account, item, quantity, unit_price, discount, amount (quantity x unit_price less discount), tax, tax_amount}], credits.

Errors

  • 400 invalid_request: the body is not a JSON object; kind is not one of the six kinds; issue_date or due_date is not YYYY-MM-DD; created_by is missing; contact_id is not an id; currency is not three letters; rate is not above zero; confidence is not from 0 to 1.
  • 400 invalid_request: lines is empty; a line has neither account nor item; a line has no description and no item; quantity is not above zero; unit_price or discount is not a whole number above zero; both discount and discount_percent are given; discount_percent is not from 0 up to 100.
  • 404 not_found: the business does not exist or is not visible to this key.
  • 422 rejected: an invoice, bill or credit has no contact; the contact is not in this business, or is a supplier on a sale or a customer on a purchase.
  • 422 rejected: a money_account is given on an invoice, bill or credit; the money account is not in the books or is not a bank, cash (or, for an expense, owner's) account.
  • 422 rejected: a line's account, item, tax code, branch or project is not in the business or is switched off; an item sold goes to a non-income account; a purchase line with an item names an account other than the item's stock account; a tax code is on the wrong side (sales vs purchases); a discount takes the whole line.
  • 422 rejected: the currency is not one BasePipe knows; the business is read-only because its plan is unpaid.

Get a document

GET/v1/businesses/{business}/documents/{document}

Returns one document with its lines, what has been paid or credited against it, and any documents that look like duplicates. Check possible_duplicates before approving a draft made from a receipt.

Path

businessId of the business. Test keys only see practice businesses; live keys only see live ones.
documentId of the document.

Returns

200 with the document (same fields as the create response) plus possible_duplicates: other non-void documents of the same kind with the same total, dated within 3 days, with the same contact or party name, each with document_id, number, status, issue_date, party, total. credits lists credit applications touching this document: id, credit_id, document_id, credit_number, document_number, date, amount.

Errors

  • 404 not_found: the business or the document does not exist or is not visible to this key.

Replace a draft document

PUT/v1/businesses/{business}/documents/{document}

Replaces a draft's details and all of its lines. Send the whole draft again: fields left out are cleared (contact_id, due_date, reference, memo, money_account, party_name, attachment_ref and confidence), except currency and rate, which keep their current values. The kind, created_by, branch and project cannot be changed here; recorded and void documents cannot be changed at all.

Path

businessId of the business. Test keys only see practice businesses; live keys only see live ones.
documentId of the draft document.

Body

contact_idstringId of a contact. Required for invoice, bill, credit_note and supplier_credit; must be a customer (or both) on sales kinds and a supplier (or both) on purchase kinds.
issue_datedaterequiredThe document's date, YYYY-MM-DD.
due_datedateInvoices and bills only: when payment is due, YYYY-MM-DD. Defaults to issue_date.
referencestringYour own reference, such as the supplier's invoice number.
memostringA note on the document.
money_accountstringExpense and cash_sale only: code of the bank or cash account paid from or into (or an equity account for an expense the owner paid personally). Must be left out for invoices, bills and credits.
party_namestringThe other party's name when there is no contact.
attachment_refstringReference to the stored receipt file. Send back the value from the document to keep the receipt attached.
confidencenumberFrom 0 to 1: how sure the preparer was. Informational only.
currencystringThree-letter currency code. Left out, the draft keeps its currency.
ratenumberUnits of the business's currency per one unit of the document's currency. Left out, the current rate is kept if the currency is unchanged, otherwise it is looked up.
linesarrayrequiredThe full list of lines, replacing the old ones. At least one.
lines[].descriptionstringWhat the line is for. Required unless the line names an item.
lines[].accountstringAccount code for the line. Each line needs account or item; see the create endpoint for how items choose accounts.
lines[].itemstringCode of a stock item.
lines[].quantitynumberHow many, above zero. Defaults to 1. Decimals allowed.
lines[].unit_priceintegerrequiredPrice of one unit before discount and tax, in the smallest currency unit. Above zero.
lines[].discountintegerAmount off the line in the smallest currency unit, less than quantity x unit_price. Not with discount_percent.
lines[].discount_percentnumberPercentage off quantity x unit_price, from 0 up to but not including 100. Not with discount.
lines[].taxstringTax code for the line. Leave it out to use the contact's default; null for no tax.
lines[].branchstringName or id of a branch tag for this line.
lines[].projectstringName or id of a project tag for this line.

Example

{
  "contact_id": "01936f4e-9b1c-7d2e-8f3a-4b5c6d7e8f90",
  "issue_date": "2026-11-14",
  "due_date": "2026-12-14",
  "reference": "DFM-20931",
  "memo": "Flour delivery for November",
  "lines": [
    {
      "description": "Flour, 50 kg bag",
      "account": "5000",
      "quantity": 20,
      "unit_price": 9500,
      "discount": 5000
    },
    {
      "description": "Delivery to Al Sadd branch",
      "account": "6500",
      "quantity": 1,
      "unit_price": 15000
    }
  ]
}

Returns

200 with the updated draft document, same shape as the create response.

Errors

  • 400 invalid_request: the same validation errors as creating a draft (dates, lines, amounts, discount, currency, rate, confidence).
  • 404 not_found: the business or the document does not exist or is not visible to this key.
  • 422 rejected: the document is recorded or void and can no longer be changed.
  • 422 rejected: the same book rules as creating a draft (contact kind, money account, accounts, items, tax codes, tags, discounts, currency).

Delete a draft document

DELETE/v1/businesses/{business}/documents/{document}

Deletes a draft and its lines for good. Only drafts can be deleted; to cancel a recorded document, void it instead.

Path

businessId of the business. Test keys only see practice businesses; live keys only see live ones.
documentId of the draft document.

Returns

200 with id and deleted: true.

Errors

  • 404 not_found: the business or the document does not exist or is not visible to this key.
  • 422 rejected: the document is recorded or void; recorded documents are never deleted.

Approve and record a draft

POST/v1/businesses/{business}/documents/{document}/approve

Records a draft in the books. The document gets its number (INV-, BILL-, EXP-, SALE-, CN- or SC- followed by six digits) and its journal entry, dated on the issue date, and stock items move. After this it cannot be changed, only voided.

Path

businessId of the business. Test keys only see practice businesses; live keys only see live ones.
documentId of the draft document.

Body

approved_bystringrequiredWho approved it, such as the owner's or accountant's email. Kept on the document and its entry.

Example

{
  "approved_by": "owner@gulfcafe.qa"
}

Returns

200 with the document, now with status recorded, number, approved_by, recorded_at, entry_id and base_total (the total in the business's currency). For an invoice, bill or credit, outstanding is the full total; for an expense or cash sale, paid is the full total.

Errors

  • 400 invalid_request: approved_by is missing.
  • 404 not_found: the business or the document does not exist or is not visible to this key.
  • 422 rejected: the document is already recorded or void.
  • 422 rejected: an expense or cash sale has no money_account yet.
  • 422 rejected: the document is in another currency and has no exchange rate.
  • 422 rejected: after withholding tax nothing is left to pay.
  • 422 rejected: the business has no receivable or payable account set; the month of the issue date is closed; not enough of a stock item is in stock; the business is read-only because its plan is unpaid.

Void a recorded document

POST/v1/businesses/{business}/documents/{document}/void

Cancels a recorded document by reversing its entry and any stock it moved. The document stays in the books with status void. Void the payments and take off the credits set against it first.

Path

businessId of the business. Test keys only see practice businesses; live keys only see live ones.
documentId of the recorded document.

Body

reasonstringrequiredWhy it is being voided. Kept on the document and in the reversing entry's description.
bystringrequiredWho voided it.
datedateDate of the reversing entry, YYYY-MM-DD. Defaults to the original entry's date; give a date in an open month if that month is closed.

Example

{
  "reason": "Issued to the wrong customer",
  "by": "owner@gulfcafe.qa",
  "date": "2026-11-16"
}

Returns

200 with the document, now with status void, voided_by, voided_at and void_reason.

Errors

  • 400 invalid_request: reason or by is missing; date is not YYYY-MM-DD.
  • 404 not_found: the business or the document does not exist or is not visible to this key.
  • 422 rejected: the document is a draft (delete it instead) or is already void.
  • 422 rejected: payments are allocated to it, or credits are applied to or from it.
  • 422 rejected: the month of the reversal date is closed; the stock it moved has moved since and can't be undone at its original cost; the business is read-only.

Payments

List payments

GET/v1/businesses/{business}/payments

Lists the business's payments in and out, newest first, with what each was allocated to.

Path

businessId of the business. Test keys only see practice businesses; live keys only see live ones.

Query

limitintegerHow many to return, 1 to 200. Defaults to 50.

Returns

200 with data: a list of payments in the same shape as the record response, including void payments.

Errors

  • 404 not_found: the business does not exist or is not visible to this key.

Record a payment

POST/v1/businesses/{business}/payments

Records money received from a customer or paid to a supplier, straight into the books, and optionally sets it against open documents. Money in settles invoices and supplier credit refunds; money out settles bills and credit note refunds. Any part not allocated stays with the contact as a deposit you can allocate later.

Path

businessId of the business. Test keys only see practice businesses; live keys only see live ones.

Body

directionstringrequiredin for money received, out for money paid.
contact_idstringrequiredId of the customer or supplier. A contact of kind both is treated as a customer for money in and a supplier for money out, unless the allocations point at its invoices or credit notes.
datedaterequiredThe date the money moved, YYYY-MM-DD. Its month must be open.
amountintegerrequiredThe amount that reached or left the account, in the smallest unit of the business's currency. Above zero.
money_accountstringrequiredCode of the bank or cash account, such as 1010 (Bank account) or 1000 (Cash). Must be an active asset account.
referencestringA bank or cheque reference.
memostringDescription of the entry. Defaults to text like 'Payment from Gulf Cafe' or 'Refund to Gulf Cafe'.
created_bystringrequiredWho entered the payment.
approved_bystringrequiredWho approved it. Payments are recorded at once, so this is required.
allocationsarrayRecorded documents of this contact to set the payment against. The total allocated, in the business's currency, cannot exceed amount.
allocations[].document_idstringrequiredId of a recorded invoice, bill, credit note or supplier credit of the same contact.
allocations[].amountintegerrequiredHow much of the document this settles, in the smallest unit of the document's currency. Cannot exceed what is still outstanding on it.
allocations[].base_amountintegerFor a document in another currency: what this part was worth in the business's currency. Defaults to amount converted at the document's rate. A difference from the document's rate is recorded as an exchange gain or loss on account 6950.

Example

{
  "direction": "in",
  "contact_id": "01936f4e-8a2b-7c3d-9e4f-5a6b7c8d9e0f",
  "date": "2026-11-20",
  "amount": 259000,
  "money_account": "1010",
  "reference": "QNB TRF 88213",
  "created_by": "fatima@gulfcafe.qa",
  "approved_by": "owner@gulfcafe.qa",
  "allocations": [
    {
      "document_id": "01937a10-1c2d-7e3f-8a4b-5c6d7e8f9a0b",
      "amount": 259000
    }
  ]
}

Returns

201 with the payment: id, direction, status (recorded), contact {id, name}, date, amount, money_account, reference, memo, created_by, approved_by, recorded_at, entry_id, voided_by, voided_at, void_reason, allocations [{document_id, number, amount}]. Send an Idempotency-Key header to make retries safe: a repeat with the same key returns the payment already recorded.

Errors

  • 400 invalid_request: direction is not in or out; contact_id or an allocation's document_id is not an id; date is not YYYY-MM-DD; amount, an allocation amount or base_amount is not a whole number above zero; money_account, created_by or approved_by is missing; allocations is not a list.
  • 404 not_found: the business does not exist or is not visible to this key.
  • 422 rejected: the contact is not in this business; the money account is not an active bank or cash account; the business has no receivable or payable account set.
  • 422 rejected: an allocated document is not in this business, is not recorded, belongs to another contact, was paid on the spot (expense or cash sale), or is on the wrong side for the direction.
  • 422 rejected: an allocation is more than the document has left to pay or refund, or the allocations add up to more than the payment.
  • 422 rejected: the month is closed; the business is read-only.

Get a payment

GET/v1/businesses/{business}/payments/{payment}

Returns one payment with its current allocations. Allocations taken off when the payment was voided are not listed.

Path

businessId of the business. Test keys only see practice businesses; live keys only see live ones.
paymentId of the payment.

Returns

200 with the payment: id, direction, status, contact, date, amount, money_account, reference, memo, created_by, approved_by, recorded_at, entry_id, voided_by, voided_at, void_reason, allocations [{document_id, number, amount}].

Errors

  • 404 not_found: the business or the payment does not exist or is not visible to this key.

Allocate a payment to a document

POST/v1/businesses/{business}/payments/{payment}/allocations

Sets part of an existing payment against one recorded document of the same contact, for example a customer's deposit against their next invoice. Use it for money that was not allocated when the payment was recorded.

Path

businessId of the business. Test keys only see practice businesses; live keys only see live ones.
paymentId of the payment.

Body

document_idstringrequiredId of a recorded invoice, bill, credit note or supplier credit of the payment's contact, on the right side for the payment's direction.
amountintegerrequiredHow much of the document this settles, in the smallest unit of the document's currency. Cannot exceed what is outstanding on it.
bystringrequiredWho made the allocation.
base_amountintegerFor a document in another currency: what this part was worth in the business's currency. Defaults to amount at the document's rate; the difference is recorded as an exchange gain or loss.

Example

{
  "document_id": "01937a10-1c2d-7e3f-8a4b-5c6d7e8f9a0b",
  "amount": 50000,
  "by": "fatima@gulfcafe.qa"
}

Returns

201 with the payment, its allocations list now including the new one.

Errors

  • 400 invalid_request: document_id is not an id; amount or base_amount is not a whole number above zero; by is missing.
  • 404 not_found: the business or the payment does not exist or is not visible to this key.
  • 422 rejected: the payment is void.
  • 422 rejected: the document is not in this business, is not recorded, belongs to another contact, was paid on the spot, or is on the wrong side for the direction.
  • 422 rejected: the amount is more than the document has left, or more than the payment has left to allocate; the month of the payment is closed when an exchange difference has to be recorded.

Void a payment

POST/v1/businesses/{business}/payments/{payment}/void

Cancels a payment by reversing its entry, and any exchange difference entries, and takes off all its allocations, so the documents it paid are open again. The payment stays with status void.

Path

businessId of the business. Test keys only see practice businesses; live keys only see live ones.
paymentId of the payment.

Body

reasonstringrequiredWhy it is being voided, such as a bounced cheque.
bystringrequiredWho voided it.
datedateDate of the reversing entry, YYYY-MM-DD. Defaults to the payment's date; give a date in an open month if that month is closed.

Example

{
  "reason": "Cheque returned unpaid by the bank",
  "by": "owner@gulfcafe.qa"
}

Returns

200 with the payment, now with status void, voided_by, voided_at, void_reason and an empty allocations list.

Errors

  • 400 invalid_request: reason or by is missing; date is not YYYY-MM-DD.
  • 404 not_found: the business or the payment does not exist or is not visible to this key.
  • 422 rejected: the payment is already void; the month of the reversal date is closed; the business is read-only.

Credits

Undo a credit application

POST/v1/businesses/{business}/credit-applications/{application}/undo

Takes a credit back off the invoice or bill it was applied to, so both are open again by that amount. Any exchange difference entry it made is reversed.

Path

businessId of the business. Test keys only see practice businesses; live keys only see live ones.
applicationId of the credit application, from the credits list on the credit or the document.

Body

bystringrequiredWho took the credit off.
datedateDate for reversing an exchange difference entry, YYYY-MM-DD. Defaults to that entry's date.

Example

{
  "by": "fatima@gulfcafe.qa"
}

Returns

200 with the credit document, without the undone application in its credits list.

Errors

  • 400 invalid_request: by is missing; date is not YYYY-MM-DD.
  • 404 not_found: the business or the credit application does not exist or is not visible to this key.
  • 422 rejected: the credit has already been taken back; the reversal falls in a closed month.

Apply a credit to a document

POST/v1/businesses/{business}/documents/{document}/apply

Sets a recorded credit note against an open invoice of the same customer, or a supplier credit against an open bill of the same supplier, lowering what is owed on both. No money moves. To pay the credit back in money instead, record a payment and allocate it to the credit.

Path

businessId of the business. Test keys only see practice businesses; live keys only see live ones.
documentId of the recorded credit note or supplier credit.

Body

document_idstringrequiredId of the recorded invoice (for a credit note) or bill (for a supplier credit). Same contact and same currency as the credit.
amountintegerrequiredHow much to apply, in the smallest unit of the documents' currency. Cannot exceed the credit left or what is left to pay on the document.
bystringrequiredWho applied it.
datedateDate of the application, YYYY-MM-DD. Defaults to the later of the two documents' issue dates and cannot be before it.

Example

{
  "document_id": "01937a10-1c2d-7e3f-8a4b-5c6d7e8f9a0b",
  "amount": 32500,
  "by": "fatima@gulfcafe.qa"
}

Returns

201 with the credit document; its credits list includes the new application (id, credit_id, document_id, credit_number, document_number, date, amount) and its outstanding shows the credit left. Keep the application id to undo it.

Errors

  • 400 invalid_request: document_id is not an id; amount is not a whole number above zero; by is missing; date is not YYYY-MM-DD.
  • 404 not_found: the business or the credit document does not exist or is not visible to this key.
  • 422 rejected: the target document is not in this business; the path document is not a credit note or supplier credit; a credit note is applied to something other than an invoice, or a supplier credit to something other than a bill.
  • 422 rejected: either document is not recorded; they belong to different contacts or are in different currencies.
  • 422 rejected: the amount is more than the credit left or more than the document has left to pay; the date is before both documents exist; an exchange difference has to be recorded in a closed month.

Receipts

Download a document's receipt file

GET/v1/businesses/{business}/documents/{document}/file

Returns the original receipt photo or PDF stored for a document, for the owner or an accountant to look at. The response is the file itself with its content type, not JSON.

Path

businessId of the business. Test keys only see practice businesses; live keys only see live ones.
documentId of the document the receipt belongs to.

Returns

200 with the file bytes, Content-Type set to the file's media type (such as image/jpeg or application/pdf) and Cache-Control private, max-age=300.

Errors

  • 404 not_found: the business or the document does not exist or is not visible to this key.
  • 404 not_found: the document has no stored file, file storage is off, or the file is missing (Receipt file not found).

Read a receipt into a draft

POST/v1/businesses/{business}/receipts

Upload a receipt photo or PDF; it is stored (when file storage is on) and read by AI into a draft expense with an account for each line, checked against the printed total, plus plain questions for the owner. Send JSON {"file": base64, "media_type": "image/jpeg"} or a multipart form with a "file" field; media types are image/jpeg, image/png, image/webp, image/gif and application/pdf, up to 10 MB. Optional text fields created_by (defaults to claude-assistant) and money_account (defaults to 1000 for cash, 1010 for card or bank transfer, none if unknown) can be sent alongside; nothing is recorded until the draft is approved.

Path

businessId of the business. Test keys only see practice businesses; live keys only see live ones.

Body

filestringrequiredThe receipt: base64 in a JSON body (a data: URL prefix is allowed), or a file part in a multipart form.
media_typestringrequiredJSON body only: image/jpeg, image/png, image/webp, image/gif or application/pdf. In a form, the file part's own type is used.
created_bystringWho sent the receipt. Defaults to claude-assistant.
money_accountstringCode of the account it was paid from, overriding what the reader saw on the receipt.

Returns

201 with kind receipt, reading {supplier, date, currency, printed_total, lines_total, lines_add_up, paid_with, confidence}, questions (list of text), stored (whether the file was kept) and draft (the draft expense, as in the documents endpoints, with possible_duplicates). If the file is a till report: 200 with kind till_report, till {date, cash, card, total, printed_total, adds_up, confidence, questions} and stored, and nothing is created. If it is a bank statement: 201 with kind bank_statement and stored; send it to the statements endpoint instead.

Errors

  • 400 invalid_request: no file; the JSON has no media_type or the file is not valid base64; the media type is not allowed; the file is empty or over 10 MB.
  • 403 read_only: the business is read-only until its plan is paid.
  • 404 not_found: the business does not exist or is not visible to this key.
  • 422 unreadable: the reader could not read the file, or no amounts could be read.
  • 422 not_a_receipt: the file doesn't look like a receipt or bill.
  • 422 rejected: the draft could not be created under the books' rules, for example an unknown currency or money account.
  • 429 receipt_limit: this month's receipt reading on the business's plan is used up.
  • 502 reader_unavailable: the reading service is not answering; try again.
  • 503 reader_off: receipt reading is not switched on for this service.

Shared invoices

Get a share link for an invoice

POST/v1/businesses/{business}/documents/{document}/share

Returns a link to send a customer for a recorded invoice. The link opens the invoice as a page in English and Arabic that the customer can read, print or save as a PDF, with no sign-in. Each invoice has one link: asking again returns the same one. No request body is needed.

Path

businessId of the business. Test keys only see practice businesses; live keys only see live ones.
documentId of the recorded invoice.

Returns

201 with document_id and url (such as https://app.basepipe.io/i/<token>). Anyone with the link can see that one invoice. The page shows what is still due and the business's payment details; once paid in full it shows Paid in full, and if voided it says the invoice was cancelled.

Errors

  • 404 not_found: the business does not exist or is not visible to this key.
  • 404 not_found: the document does not exist or is not an invoice (Invoice not found).
  • 409 not_recorded: the invoice is still a draft; approve it first.

Set how customers pay

POST/v1/businesses/{business}/payment-details

Sets the payment instructions printed under How to pay on the business's shared invoices, such as bank name and IBAN. Line breaks are kept. They are hidden on invoices that are paid in full or void.

Path

businessId of the business. Test keys only see practice businesses; live keys only see live ones.

Body

payment_detailsstringrequiredThe instructions, up to 500 characters. Send null to remove them.

Example

{
  "payment_details": "Bank transfer to Gulf Cafe W.L.L.\nQatar National Bank\nIBAN QA58 QNBA 0000 0000 0012 3456 7890 1\nPlease quote the invoice number."
}

Returns

200 with payment_details as sent.

Errors

  • 400 invalid_request: the body is not a JSON object; payment_details is missing, empty or not text; it is over 500 characters.
  • 404 not_found: the business does not exist or is not visible to this key.

Daily sales

List daily sales

GET/v1/businesses/{business}/daily-sales

Lists the current figures for the latest 90 days that have sales reported, newest first. Replaced figures are left out.

Path

businessThe business id.

Returns

200 with data: days with date, cash, card, total, closed, reported_by.

Errors

  • 404 not_found: the business is not yours or is in the other mode

Record a day's sales

POST/v1/businesses/{business}/daily-sales

Records the day's cash and card totals, for example from a till system, as two approved cash sales: cash into Cash (1000) and card takings into Card payments on the way (1150). Sending figures again for the same day voids the earlier ones and replaces them. Zero cash and zero card means the business was closed that day.

Path

businessThe business id.

Body

datedateThe day, YYYY-MM-DD. Defaults to today in the business's time zone. Can't be in the future.
cashintegerCash sales in the smallest currency unit (1,200 QAR = 120000), 0 or more. Defaults to 0.
cardintegerCard sales in the smallest currency unit, 0 or more. Defaults to 0.
reported_bystringWho reported the figures. Defaults to api.

Example

{
  "date": "2026-11-15",
  "cash": 120000,
  "card": 340000,
  "reported_by": "Lulu Hypermarket till 3"
}

Returns

201 with id, date, cash, card, total, closed, documents (the numbers of the cash sale documents made), reported_by, replaced (true when earlier figures for the day were replaced).

Errors

  • 400 invalid_request: the body is not a JSON object; date is not YYYY-MM-DD; cash or card is not a whole number of 0 or more; the date is in the future; or the books refused the sale (for example its month is closed)
  • 404 not_found: the business is not yours or is in the other mode

Set the evening sales question

POST/v1/businesses/{business}/sales-checkin

Switches the daily question on or off and sets its time in the business's own time zone. When on, an outbox message asking the owner for the day's cash and card totals is prepared each evening at that time.

Path

businessThe business id.

Body

onbooleanrequiredtrue to ask every day, false to stop.
atstringTime to ask, HH:MM from 06:00 to 23:00. Leave out to keep the current time (21:00 unless changed).

Example

{
  "on": true,
  "at": "22:00"
}

Returns

200 with on and at (HH:MM).

Errors

  • 400 invalid_request: the body is not a JSON object, on is not true or false, at is not a time like 21:00, or at is before 06:00 or after 23:00
  • 404 not_found: the business is not yours or is in the other mode

Bank

List bank lines

GET/v1/businesses/{business}/bank-lines

Lists imported bank lines, newest first. Filter by status to find the lines that still need matching.

Path

businessThe business id. It must belong to you, and a test key only sees practice businesses.

Query

statusstringunmatched, matched or ignored.
accountstringOnly lines on this bank or cash account code.
limitintegerHow many lines, 1 to 500. Defaults to 100.

Returns

200 with data: a list of bank lines, each with id, account (code), date, amount (above zero is money in, below zero money out), description, reference, balance, status (unmatched, matched or ignored), ignored_reason, matched_journal_line_id, matched_entry_number, matched_by, imported_by, imported_at.

Errors

  • 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
  • 400 invalid_request when "status" is not unmatched, matched or ignored

Get a bank line with suggestions

GET/v1/businesses/{business}/bank-lines/{line}

Returns one bank line. While it is unmatched, it also lists lines in the books it could be (same account, same amount, not matched yet, within seven days, closest date first) and the accounts it most likely belongs to, from the owner's rules first and then from how similar lines were recorded before.

Path

businessThe business id. It must belong to you, and a test key only sees practice businesses.
lineThe bank line id.

Returns

200 with id, account (code), date, amount (above zero is money in, below zero money out), description, reference, balance, status (unmatched, matched or ignored), ignored_reason, matched_journal_line_id, matched_entry_number, matched_by, imported_by, imported_at, plus possible_matches [{journal_line_id, entry_id, entry_number, entry_date, memo, days_apart}] (up to 10) and suggested_accounts [{account, account_name, source (rule or past entries), rule_id, confidence (0 to 1)}] (up to 3). Both lists are empty unless the line is unmatched.

Errors

  • 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
  • 404 not_found when the bank line is not in this business

Set a bank line aside

POST/v1/businesses/{business}/bank-lines/{line}/ignore

Marks an unmatched bank line as one that should never be matched, such as a duplicate the bank later corrected. Set-aside lines are counted separately in the bank reconciliation report.

Path

businessThe business id. It must belong to you, and a test key only sees practice businesses.
lineThe bank line id.

Body

reasonstringrequiredWhy the line is set aside.
bystringrequiredWho set it aside.

Example

{
  "reason": "Duplicate of the 3 November transfer; QNB reversed it the next day",
  "by": "Fatima Al-Kuwari"
}

Returns

200 with the bank line (id, account (code), date, amount (above zero is money in, below zero money out), description, reference, balance, status (unmatched, matched or ignored), ignored_reason, matched_journal_line_id, matched_entry_number, matched_by, imported_by, imported_at), now ignored, with ignored_reason.

Errors

  • 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
  • 404 not_found when the bank line is not in this business
  • 400 invalid_request when the body is not a JSON object
  • 400 invalid_request when "reason" or "by" is missing
  • 422 rejected when the bank line is not unmatched

Match a bank line to the books

POST/v1/businesses/{business}/bank-lines/{line}/match

Links an unmatched bank line to the line in the books for the same money, such as a payment already recorded. Matching never changes the books and can be undone. Take the journal_line_id from the bank line's possible_matches.

Path

businessThe business id. It must belong to you, and a test key only sees practice businesses.
lineThe bank line id.

Body

journal_line_idstringrequiredId of the journal line on the same bank account, with exactly the same amount.
bystringrequiredWho confirmed the match.

Example

{
  "journal_line_id": "01934f6e-2b7a-7c41-9d3e-5a8f0c2e7b19",
  "by": "Fatima Al-Kuwari"
}

Returns

200 with the bank line (id, account (code), date, amount (above zero is money in, below zero money out), description, reference, balance, status (unmatched, matched or ignored), ignored_reason, matched_journal_line_id, matched_entry_number, matched_by, imported_by, imported_at), now matched.

Errors

  • 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
  • 404 not_found when the bank line is not in this business
  • 400 invalid_request when the body is not a JSON object
  • 400 invalid_request when "journal_line_id" is not an id or "by" is missing
  • 422 rejected when the bank line is already matched or set aside
  • 422 rejected when the journal line is not in this business's books or its entry was reversed, is on a different account, has a different amount, or is already matched to another bank line

Record a bank line in the books

POST/v1/businesses/{business}/bank-lines/{line}/record

For a bank line with nothing behind it in the books, such as a bank fee, records an entry between the bank account and the account you name, dated the bank line's date, and matches the line to it. Money in is credited to that account; money out is debited to it.

Path

businessThe business id. It must belong to you, and a test key only sees practice businesses.
lineThe bank line id.

Body

accountstringrequiredCode of the account the money was for, for example 6300 for bank fees. Not the bank account itself.
memostringReason for the entry. Defaults to the bank line's description.
created_bystringrequiredWho prepared the entry.
approved_bystringrequiredWho approved the entry. Also saved as who matched the line.

Example

{
  "account": "6300",
  "memo": "QNB monthly account fee",
  "created_by": "Fatima Al-Kuwari",
  "approved_by": "Khalid Al-Thani"
}

Returns

201 with the bank line (id, account (code), date, amount (above zero is money in, below zero money out), description, reference, balance, status (unmatched, matched or ignored), ignored_reason, matched_journal_line_id, matched_entry_number, matched_by, imported_by, imported_at), now matched to the new entry (matched_entry_number).

Errors

  • 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
  • 404 not_found when the bank line is not in this business
  • 400 invalid_request when the body is not a JSON object
  • 400 invalid_request when "account", "created_by" or "approved_by" is missing
  • 422 rejected when the account is not a switched-on account of this business, or is the bank account itself
  • 422 rejected when the bank line is already matched or set aside
  • 422 rejected when the bank line's month is closed

Undo a match or set-aside

POST/v1/businesses/{business}/bank-lines/{line}/unmatch

Puts a matched or set-aside bank line back to unmatched and removes its match. An entry that was recorded from the bank line stays in the books; reverse it separately if it was wrong.

Path

businessThe business id. It must belong to you, and a test key only sees practice businesses.
lineThe bank line id.

Body

bystringrequiredWho undid it.

Example

{
  "by": "Fatima Al-Kuwari"
}

Returns

200 with the bank line (id, account (code), date, amount (above zero is money in, below zero money out), description, reference, balance, status (unmatched, matched or ignored), ignored_reason, matched_journal_line_id, matched_entry_number, matched_by, imported_by, imported_at), now unmatched.

Errors

  • 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
  • 404 not_found when the bank line is not in this business
  • 400 invalid_request when the body is not a JSON object
  • 400 invalid_request when "by" is missing

Import bank statement lines

POST/v1/businesses/{business}/bank-lines/import

Adds lines from a bank statement to one of the business's bank or cash accounts. Importing the same statement again adds nothing twice: a line is recognised by the bank's own id, or by its date, amount, description, reference and position when there is no id.

Path

businessThe business id. It must belong to you, and a test key only sees practice businesses.

Body

accountstringrequiredCode of the bank or cash account (an asset account that is switched on), for example 1010.
bystringrequiredWho imported the statement.
linesarrayrequiredThe statement lines, 1 to 2,000 at a time.
lines[].datedaterequiredDate the bank shows for the line.
lines[].amountintegerrequiredAmount in the smallest currency unit, not zero: above zero for money in, below zero for money out.
lines[].descriptionstringThe bank's wording. Stored as "(no description)" when left out.
lines[].referencestringThe bank's reference for the line.
lines[].balanceintegerThe statement's running balance after this line. The latest one is used as the statement balance in the bank reconciliation report.
lines[].idstringThe bank's own id for the line, if it gives one. Used to skip lines already imported.

Example

{
  "account": "1010",
  "by": "Fatima Al-Kuwari",
  "lines": [
    {
      "date": "2026-11-02",
      "amount": 525000,
      "description": "TRANSFER FROM AL MEERA TRADING",
      "reference": "FT2611020045",
      "balance": 4997500,
      "id": "QNB-88213401"
    },
    {
      "date": "2026-11-03",
      "amount": -38500,
      "description": "KAHRAMAA BILL PAYMENT 40123456",
      "balance": 4959000,
      "id": "QNB-88213422"
    },
    {
      "date": "2026-11-03",
      "amount": -2500,
      "description": "BANK CHARGES",
      "balance": 4956500,
      "id": "QNB-88213423"
    }
  ]
}

Returns

201 with received (lines sent), added (new lines saved) and already_imported (lines skipped because they were imported before).

Errors

  • 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
  • 400 invalid_request when the body is not a JSON object
  • 400 invalid_request when "lines" is missing, empty or longer than 2,000
  • 400 invalid_request when a line's "amount" is not a whole number or is zero, its "balance" is not a whole number, or its "date" is not a date
  • 400 invalid_request when "account" or "by" is missing
  • 422 rejected when "account" is not a switched-on asset account of this business

Compare a bank account with the statement

GET/v1/businesses/{business}/reports/bank-reconciliation

For one bank or cash account up to a date, shows the balance in the books, what is on the statement but not matched in the books, and what is in the books but not matched to a statement line. The expected statement balance is the books balance plus the unmatched bank lines less the unmatched book lines.

Path

businessThe business id. It must belong to you, and a test key only sees practice businesses.

Query

accountstringBank or cash account code. Defaults to 1010.
as_ofdateUp to and including this date. Defaults to today (UTC).

Returns

200 with account, as_of, currency, books_balance, on_statement_not_in_books {count, total}, in_books_not_on_statement {count, total}, set_aside (count of ignored lines), expected_statement_balance, statement_balance (the latest running balance imported on or before as_of, or null) and difference (statement_balance less expected_statement_balance, or null).

Errors

  • 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
  • 400 invalid_request when "as_of" is not a date like 2026-11-05

Bank statements

Record card machine payouts

POST/v1/businesses/{business}/bank-lines/card-payouts

Records the chosen bank lines as card machine payouts, clearing them against account 1150 (Card payments on the way), where the day's card sales went. Use the ids in card_payouts from a statement import once the owner confirms them. Lines that are already matched or are money out are skipped.

Path

businessId of the business. Test keys only see practice businesses; live keys only see live ones.

Body

line_idsarrayrequiredIds of the bank lines to record as payouts.
approved_bystringWho approved recording them. Defaults to api.

Example

{
  "line_ids": [
    "01938b22-4d5e-7f60-8172-93a4b5c6d7e8",
    "01938b22-4d5e-7f60-8172-93a4b5c6d7e9"
  ],
  "approved_by": "owner@gulfcafe.qa"
}

Returns

200 with recorded: how many lines were recorded.

Errors

  • 400 invalid_request: line_ids is missing or is not a list of text.
  • 400 invalid_request: an id in line_ids is not a valid id (A value had the wrong format).
  • 404 not_found: the business does not exist or is not visible to this key.
  • 422 rejected: a line's month is closed; the business is read-only.

Import a bank statement

POST/v1/businesses/{business}/statements

Upload a bank statement as JSON {"file": base64, "media_type": ...}: a CSV export (text/csv, text/comma-separated-values, application/csv or text/plain) is read directly; a PDF or a photo of a page (application/pdf, image/jpeg, image/png, image/webp, image/gif) is read by AI. Up to 20 MB; Excel files are refused. The lines are checked against the statement's own opening, closing and running balances, imported onto the bank account (sending the same statement twice adds nothing), matched where there is exactly one possible match in the books, and passed through the business's auto-recording rules; card machine payouts are picked out for the owner to clear.

Path

businessId of the business. Test keys only see practice businesses; live keys only see live ones.

Body

filestringrequiredThe statement file, base64-encoded. A data: URL prefix is allowed.
media_typestringrequiredThe file's media type, from the lists in the description.
accountstringCode of the bank account the statement belongs to, such as 1010. Needed when the business has more than one bank account and the bank's name doesn't pick one out.
imported_bystringWho imported it. Defaults to api.

Returns

201 with account, bank_name, from, to (the statement period), lines (lines read), added (new lines imported), matched (lines matched automatically), recorded_by_rules, card_payouts [{id, amount, date, description}] (unmatched money in that looks like card machine payouts), still_open (other unmatched lines left for review) and adds_up (true when the balances were checked and agree, null when the statement prints none).

Errors

  • 400 invalid_request: the body is not JSON; file or media_type is missing; the file is an Excel file; file is not valid base64; the file is empty or over 20 MB.
  • 400 invalid_request: no account was given and one couldn't be chosen; the account is not one of the business's bank or cash accounts.
  • 404 not_found: the business does not exist or is not visible to this key.
  • 422 unreadable: a CSV's columns weren't recognised and AI reading is off, or the reader could not read the file.
  • 422 not_a_statement: the file doesn't look like a bank statement.
  • 422 does_not_add_up: the lines don't follow the statement's running balances or don't add up from opening to closing balance; nothing was imported.
  • 502 reader_unavailable: the reading service is not answering; try again.
  • 503 reader_off: statement reading for PDFs and images is not switched on for this service.
  • 400 invalid_request: the business has no bank account to import into.

Coding rules

List coding rules

GET/v1/businesses/{business}/rules

Lists every rule, switched on or off, in the order they are tried: lowest priority number first, then oldest.

Path

businessThe business id. It must belong to you, and a test key only sees practice businesses.

Returns

200 with data: a list of rules, each with id, name, contains_text, direction (in, out or any), min_amount, max_amount, account (code), memo, auto_record, priority, is_active, approved_by, created_at.

Errors

  • 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)

Add a coding rule

POST/v1/businesses/{business}/rules

Saves an owner-approved rule that says what a recurring bank line is, for example any line containing "KAHRAMAA" is the electricity and water bill. A rule only suggests the account unless auto_record is true, in which case running the rules records matching lines on their own. When several rules fit a line, the lowest priority number wins.

Path

businessThe business id. It must belong to you, and a test key only sees practice businesses.

Body

namestringrequiredA name for the rule.
containsstringrequiredText to look for in the bank line's description or reference. Case does not matter.
accountstringrequiredCode of the account the money is for. Not a bank account that has statement lines.
approved_bystringrequiredWho approved the rule. Entries the rule records are approved in this name.
directionstringin (money in only), out (money out only) or any. Defaults to any.
min_amountintegerOnly lines of at least this size (money in or out), in the smallest currency unit. Above zero.
max_amountintegerOnly lines of at most this size, in the smallest currency unit. Above zero and not below min_amount.
memostringReason written on entries the rule records. Defaults to the bank line's description.
auto_recordbooleanRecord matching lines without a person. Defaults to false.
priorityintegerLower numbers are tried first. Defaults to 100.

Example

{
  "name": "Kahramaa electricity and water",
  "contains": "KAHRAMAA",
  "account": "6200",
  "approved_by": "Khalid Al-Thani",
  "direction": "out",
  "max_amount": 100000,
  "memo": "Kahramaa bill, Al Sadd shop",
  "auto_record": true,
  "priority": 10
}

Returns

201 with the rule: id, name, contains_text, direction (in, out or any), min_amount, max_amount, account (code), memo, auto_record, priority, is_active, approved_by, created_at.

Errors

  • 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
  • 400 invalid_request when the body is not a JSON object
  • 400 invalid_request when "name", "contains", "account" or "approved_by" is missing
  • 400 invalid_request when "direction" is not in, out or any, "min_amount" or "max_amount" is not a whole number above zero, "auto_record" is not true or false, or "priority" is not a whole number
  • 422 rejected when the account is not a switched-on account of this business, or is a bank account with statement lines
  • 422 rejected when min_amount is above max_amount

Switch a rule off

POST/v1/businesses/{business}/rules/{rule}/switch-off

Stops a rule from suggesting or recording. The rule is kept so past auto-coding can still be traced to it. No request body is needed.

Path

businessThe business id. It must belong to you, and a test key only sees practice businesses.
ruleThe rule id.

Returns

200 with the rule (id, name, contains_text, direction (in, out or any), min_amount, max_amount, account (code), memo, auto_record, priority, is_active, approved_by, created_at), with is_active false.

Errors

  • 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
  • 404 not_found when the rule is not in this business

Run auto-record rules now

POST/v1/businesses/{business}/rules/apply

Goes through the unmatched bank lines, oldest first, and records each one whose best-fitting rule has auto_record switched on. A line that already has a possible match in the books is left for a person to match. The same run also happens on its own each day.

Path

businessThe business id. It must belong to you, and a test key only sees practice businesses.

Body

bystringWho to name as preparing the entries. Defaults to auto-coding.

Example

{
  "by": "Fatima Al-Kuwari"
}

Returns

200 with lines_recorded: how many bank lines were recorded and matched.

Errors

  • 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
  • 400 invalid_request when the body is not a JSON object
  • 422 rejected when a line to be recorded falls in a closed month or its rule's account has been switched off

Reconciliation

List reconciliations

GET/v1/businesses/{business}/reconciliations

Lists every reconciliation, latest statement date first, including finished and undone ones.

Path

businessThe business id. It must belong to you, and a test key only sees practice businesses.

Returns

200 with data: a list, each with id, account, statement_date, statement_balance, status (open, finished or undone), finished_by and finished_at.

Errors

  • 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)

Start a reconciliation

POST/v1/businesses/{business}/reconciliations

Starts reconciling a bank, cash or card account against a statement balance on a date. It starts from where the last finished reconciliation ended, and book lines already matched to imported bank lines are ticked to begin with. Only one reconciliation per account can be open at a time.

Path

businessThe business id. It must belong to you, and a test key only sees practice businesses.

Body

accountstringrequiredCode of the asset or liability account (bank, cash or card).
statement_datedaterequiredDate of the statement balance. Must be after the last finished reconciliation of this account.
statement_balanceintegerrequiredThe balance the statement shows, in the smallest currency unit. May be negative.
bystringrequiredWho started it.

Example

{
  "account": "1010",
  "statement_date": "2026-11-30",
  "statement_balance": 4956500,
  "by": "Fatima Al-Kuwari"
}

Returns

201 with the reconciliation: id, account (code), statement_date, statement_balance, opening_balance (where the last finished reconciliation ended), status (open, finished or undone), started_by, finished_by, finished_at, cleared_balance (opening balance plus the ticked lines), difference (statement balance less cleared balance), lines [{id, entry_number, date, description, amount (debit less credit), ticked}]. lines are the account's book lines up to the statement date not ticked by an earlier finished reconciliation.

Errors

  • 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
  • 400 invalid_request when the body is not a JSON object
  • 400 invalid_request when "statement_balance" is not a whole number, "statement_date" is not a date, or "account" or "by" is missing
  • 422 rejected when the account is not an asset or liability account of this business
  • 422 rejected when a reconciliation of the account is already open
  • 422 rejected when the account is already reconciled to that date or later

Get a reconciliation

GET/v1/businesses/{business}/reconciliations/{rec}

Returns one reconciliation with its lines, which are ticked, and how far the ticked lines are from the statement balance.

Path

businessThe business id. It must belong to you, and a test key only sees practice businesses.
recThe reconciliation id.

Returns

200 with id, account (code), statement_date, statement_balance, opening_balance (where the last finished reconciliation ended), status (open, finished or undone), started_by, finished_by, finished_at, cleared_balance (opening balance plus the ticked lines), difference (statement balance less cleared balance), lines [{id, entry_number, date, description, amount (debit less credit), ticked}].

Errors

  • 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
  • 404 not_found when the reconciliation is not in this business

Finish a reconciliation

POST/v1/businesses/{business}/reconciliations/{rec}/finish

Closes the reconciliation once the ticked lines come exactly to the statement balance. Its ticked lines then count as reconciled, and the next reconciliation of the account starts from this statement balance.

Path

businessThe business id. It must belong to you, and a test key only sees practice businesses.
recThe reconciliation id.

Body

bystringrequiredWho finished it.

Example

{
  "by": "Fatima Al-Kuwari"
}

Returns

200 with the reconciliation (id, account (code), statement_date, statement_balance, opening_balance (where the last finished reconciliation ended), status (open, finished or undone), started_by, finished_by, finished_at, cleared_balance (opening balance plus the ticked lines), difference (statement balance less cleared balance), lines [{id, entry_number, date, description, amount (debit less credit), ticked}]), with status finished.

Errors

  • 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
  • 404 not_found when the reconciliation is not in this business
  • 400 invalid_request when the body is not a JSON object
  • 400 invalid_request when "by" is missing
  • 422 rejected when the reconciliation is not open
  • 422 rejected when the ticked lines are still some amount away from the statement balance (difference is not 0)

Tick or untick lines

POST/v1/businesses/{business}/reconciliations/{rec}/tick

Ticks the book lines the statement also shows, or unticks them. Only lines of the reconciled account, dated up to the statement date and not reconciled before, can be ticked.

Path

businessThe business id. It must belong to you, and a test key only sees practice businesses.
recThe reconciliation id.

Body

line_idsarrayrequiredIds of the lines, from the reconciliation's lines.
tickedbooleanfalse to untick. Defaults to true.

Example

{
  "line_ids": [
    "01934f6e-2b7a-7c41-9d3e-5a8f0c2e7b19",
    "01934f6e-2b7b-7d02-8a6f-1c3e5b7d9f20"
  ],
  "ticked": true
}

Returns

200 with the reconciliation (id, account (code), statement_date, statement_balance, opening_balance (where the last finished reconciliation ended), status (open, finished or undone), started_by, finished_by, finished_at, cleared_balance (opening balance plus the ticked lines), difference (statement balance less cleared balance), lines [{id, entry_number, date, description, amount (debit less credit), ticked}]).

Errors

  • 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
  • 404 not_found when the reconciliation is not in this business
  • 400 invalid_request when the body is not a JSON object
  • 400 invalid_request when "line_ids" is not a list of ids
  • 422 rejected when the reconciliation is not open
  • 422 rejected when a line is not on this account, is dated after the statement date, or was reconciled before

Undo a reconciliation

POST/v1/businesses/{business}/reconciliations/{rec}/undo

Undoes the latest reconciliation of an account, open or finished, so its lines can be reconciled again. Its ticks are kept for the record but no longer count.

Path

businessThe business id. It must belong to you, and a test key only sees practice businesses.
recThe reconciliation id.

Body

bystringrequiredWho undid it.

Example

{
  "by": "Khalid Al-Thani"
}

Returns

200 with the reconciliation (id, account (code), statement_date, statement_balance, opening_balance (where the last finished reconciliation ended), status (open, finished or undone), started_by, finished_by, finished_at, cleared_balance (opening balance plus the ticked lines), difference (statement balance less cleared balance), lines [{id, entry_number, date, description, amount (debit less credit), ticked}]), with status undone.

Errors

  • 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
  • 404 not_found when the reconciliation is not in this business
  • 400 invalid_request when the body is not a JSON object
  • 400 invalid_request when "by" is missing
  • 422 rejected when it is already undone
  • 422 rejected when a later reconciliation of the same account exists

Revalue foreign-currency balances

POST/v1/businesses/{business}/revaluations

At a month end, restates what customers owe and what the business owes on open invoices, bills and credits in other currencies at that day's rate. The difference goes to exchange gains and losses and is turned back the next day, so later payments settle against the original amounts. Nothing is recorded when nothing changed.

Path

businessThe business id. It must belong to you, and a test key only sees practice businesses.

Body

as_ofdaterequiredThe day to revalue at, usually a month end.
created_bystringrequiredWho prepared it.
approved_bystringrequiredWho approved the entry and its turning back.

Example

{
  "as_of": "2026-11-30",
  "created_by": "Fatima Al-Kuwari",
  "approved_by": "Khalid Al-Thani"
}

Returns

201 with as_of, entry_id (the revaluation entry) and changed true when an entry was recorded; 200 with entry_id null and changed false when nothing needed restating.

Errors

  • 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
  • 400 invalid_request when the body is not a JSON object
  • 400 invalid_request when "as_of" is not a date, or "created_by" or "approved_by" is missing
  • 422 rejected when there is no exchange rate for one of the currencies on that day
  • 422 rejected when the month of as_of, or of the day after, is closed

Quotes and purchase orders

List quotes and purchase orders

GET/v1/businesses/{business}/orders

Lists up to 200 quotes and purchase orders, newest issue date first.

Path

businessThe business id. It must belong to you, and a test key only sees practice businesses.

Query

kindstringquote or purchase_order.
statusstringopen, accepted, declined, converted or cancelled.

Returns

200 with data: a list, each with id, kind (quote or purchase_order), number (QUO-000001 or PO-000001), status (open, accepted, declined, converted or cancelled), contact {id, name}, issue_date, valid_until, reference, memo, currency, lines, total (with tax, in the smallest unit), document_id (the invoice or bill it became), created_by, created_at, status_by, status_at.

Errors

  • 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
  • 400 invalid_request when "kind" or "status" is not one of the allowed values

Create a quote or purchase order

POST/v1/businesses/{business}/orders

Saves a quote for a customer or a purchase order to a supplier. Quotes and orders are promises, not money, so they never touch the books. Each kind is numbered in turn (QUO-000001, PO-000001) and the total is worked out from the lines, with tax.

Path

businessThe business id. It must belong to you, and a test key only sees practice businesses.

Body

kindstringrequiredquote or purchase_order.
contact_idstringrequiredThe customer (for a quote) or supplier (for a purchase order).
issue_datedaterequiredDate of the quote or order.
valid_untildateWhen a quote expires, or when a purchase order is expected. Not before issue_date.
referencestringYour or the contact's reference.
memostringA note.
created_bystringrequiredWho prepared it.
currencystringThree-letter currency code. Defaults to the business's own currency.
linesarrayrequiredAt least one line, in the same shape a draft invoice or bill takes.
lines[].accountstringAccount code the line goes to (for example 4000 for sales). Needed when the line has no "item".
lines[].itemstringStock item code, instead of an account. The item must be in the business's stock list and switched on.
lines[].descriptionstringWhat the line is for.
lines[].quantitynumberHow many. Defaults to 1 and must be above zero.
lines[].unit_priceintegerrequiredPrice of one, in the smallest currency unit (12.50 QAR is 1250). Must be above zero.
lines[].discountintegerDiscount off the line as an amount. It must be below the line's price.
lines[].discount_percentnumberDiscount off the line as a percentage, from 0 up to (not including) 100. Use this or "discount", not both.
lines[].taxstringTax code for the line. Leave the field out to use the contact's default tax code; send null for no tax.
lines[].branchstringBranch name or id for the line.
lines[].projectstringProject name or id for the line.

Example

{
  "kind": "quote",
  "contact_id": "01934f6e-0c11-7a52-8e4b-2f6d9a1c3e70",
  "issue_date": "2026-11-16",
  "valid_until": "2026-11-30",
  "reference": "Majlis fit-out, Al Waab villa",
  "memo": "Price includes delivery within Doha",
  "created_by": "Noora Al-Mannai",
  "lines": [
    {
      "account": "4000",
      "description": "Majlis seating, 8 seats",
      "quantity": 1,
      "unit_price": 1850000
    },
    {
      "account": "4000",
      "description": "Installation",
      "quantity": 2,
      "unit_price": 75000,
      "discount_percent": 10
    }
  ]
}

Returns

201 with the quote or order: id, kind (quote or purchase_order), number (QUO-000001 or PO-000001), status (open, accepted, declined, converted or cancelled), contact {id, name}, issue_date, valid_until, reference, memo, currency, lines, total (with tax, in the smallest unit), document_id (the invoice or bill it became), created_by, created_at, status_by, status_at.

Errors

  • 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
  • 400 invalid_request when the body is not a JSON object
  • 400 invalid_request when "kind" is not quote or purchase_order, "contact_id" is not an id, "issue_date" or "valid_until" is not a date, or "created_by" is missing
  • 400 invalid_request when "lines" is missing or an empty list
  • 422 rejected when the contact is not in this business, a quote is for a supplier, or a purchase order is to a customer
  • 422 rejected when a line names an account or item not in the books, a tax code that is not set up or is for the other side (sales or purchases), a quantity or price of zero or less, or a discount as big as the line
  • 422 rejected when valid_until is before issue_date

Get a quote or purchase order

GET/v1/businesses/{business}/orders/{order}

Returns one quote or purchase order with its lines and, once converted, the id of the invoice or bill it became.

Path

businessThe business id. It must belong to you, and a test key only sees practice businesses.
orderThe quote or purchase order id.

Returns

200 with id, kind (quote or purchase_order), number (QUO-000001 or PO-000001), status (open, accepted, declined, converted or cancelled), contact {id, name}, issue_date, valid_until, reference, memo, currency, lines, total (with tax, in the smallest unit), document_id (the invoice or bill it became), created_by, created_at, status_by, status_at.

Errors

  • 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
  • 404 not_found when the quote or order is not in this business

Change an open quote or order

PUT/v1/businesses/{business}/orders/{order}

Replaces the lines, expiry, reference and memo of a quote or order that is still open, and works the total out again. Fields you leave out are cleared, so send them all. The contact, kind and date cannot change.

Path

businessThe business id. It must belong to you, and a test key only sees practice businesses.
orderThe quote or purchase order id.

Body

valid_untildateNew expiry or expected date. Cleared if left out.
referencestringNew reference. Cleared if left out.
memostringNew note. Cleared if left out.
linesarrayrequiredThe full new set of lines.
lines[].accountstringAccount code the line goes to (for example 4000 for sales). Needed when the line has no "item".
lines[].itemstringStock item code, instead of an account. The item must be in the business's stock list and switched on.
lines[].descriptionstringWhat the line is for.
lines[].quantitynumberHow many. Defaults to 1 and must be above zero.
lines[].unit_priceintegerrequiredPrice of one, in the smallest currency unit (12.50 QAR is 1250). Must be above zero.
lines[].discountintegerDiscount off the line as an amount. It must be below the line's price.
lines[].discount_percentnumberDiscount off the line as a percentage, from 0 up to (not including) 100. Use this or "discount", not both.
lines[].taxstringTax code for the line. Leave the field out to use the contact's default tax code; send null for no tax.
lines[].branchstringBranch name or id for the line.
lines[].projectstringProject name or id for the line.

Example

{
  "valid_until": "2026-12-07",
  "reference": "Majlis fit-out, Al Waab villa",
  "memo": "Revised after site visit",
  "lines": [
    {
      "account": "4000",
      "description": "Majlis seating, 10 seats",
      "quantity": 1,
      "unit_price": 2200000
    },
    {
      "account": "4000",
      "description": "Installation",
      "quantity": 2,
      "unit_price": 75000
    }
  ]
}

Returns

200 with the updated quote or order: id, kind (quote or purchase_order), number (QUO-000001 or PO-000001), status (open, accepted, declined, converted or cancelled), contact {id, name}, issue_date, valid_until, reference, memo, currency, lines, total (with tax, in the smallest unit), document_id (the invoice or bill it became), created_by, created_at, status_by, status_at.

Errors

  • 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
  • 404 not_found when the quote or order is not in this business
  • 400 invalid_request when the body is not a JSON object
  • 400 invalid_request when "valid_until" is not a date
  • 400 invalid_request when "lines" is missing or an empty list
  • 422 rejected when the quote or order is not open (accepted, declined, converted or cancelled ones can no longer change)
  • 422 rejected when a line names an account or item not in the books, a tax code that is not set up or is for the other side (sales or purchases), a quantity or price of zero or less, or a discount as big as the line
  • 422 rejected when valid_until is before the issue date

Turn into a draft invoice or bill

POST/v1/businesses/{business}/orders/{order}/convert

Makes a draft invoice from a quote, or a draft bill from a purchase order, with the same contact, lines, currency and memo, and marks it converted. The draft still needs approving before it reaches the books.

Path

businessThe business id. It must belong to you, and a test key only sees practice businesses.
orderThe quote or purchase order id.

Body

bystringrequiredWho prepared the draft.
issue_datedateDate of the invoice or bill. Defaults to today in the business's time zone.
due_datedateWhen it is due. Defaults to the issue date.

Example

{
  "by": "Noora Al-Mannai",
  "issue_date": "2026-11-20",
  "due_date": "2026-12-20"
}

Returns

201 with order (the quote or order, now converted: id, kind (quote or purchase_order), number (QUO-000001 or PO-000001), status (open, accepted, declined, converted or cancelled), contact {id, name}, issue_date, valid_until, reference, memo, currency, lines, total (with tax, in the smallest unit), document_id (the invoice or bill it became), created_by, created_at, status_by, status_at) and document_id (the new draft).

Errors

  • 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
  • 404 not_found when the quote or order is not in this business
  • 400 invalid_request when the body is not a JSON object
  • 400 invalid_request when "by" is missing, or "issue_date" or "due_date" is not a date
  • 422 rejected when the quote or order is declined, converted or cancelled
  • 422 rejected when a line no longer passes the draft's checks (an account, item or tax code switched off), or there is no exchange rate for a foreign currency

Set where a quote or order stands

POST/v1/businesses/{business}/orders/{order}/status

Notes that a quote was accepted or declined, or that a quote or order was cancelled, or puts it back to open. A purchase order stays open until the bill comes, so it cannot be accepted. To mark one converted, use convert.

Path

businessThe business id. It must belong to you, and a test key only sees practice businesses.
orderThe quote or purchase order id.

Body

statusstringrequiredaccepted, declined, cancelled or open.
bystringrequiredWho changed it.

Example

{
  "status": "accepted",
  "by": "Noora Al-Mannai"
}

Returns

200 with the quote or order (id, kind (quote or purchase_order), number (QUO-000001 or PO-000001), status (open, accepted, declined, converted or cancelled), contact {id, name}, issue_date, valid_until, reference, memo, currency, lines, total (with tax, in the smallest unit), document_id (the invoice or bill it became), created_by, created_at, status_by, status_at).

Errors

  • 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
  • 404 not_found when the quote or order is not in this business
  • 400 invalid_request when the body is not a JSON object
  • 400 invalid_request when "status" is not accepted, declined, cancelled or open, or "by" is missing
  • 422 rejected when it is already converted or cancelled
  • 422 rejected when accepting a purchase order

Repeating documents

List repeating documents

GET/v1/businesses/{business}/recurring

Lists every template, the next one due first. A template that failed when it ran shows the reason in last_error and is switched off.

Path

businessThe business id. It must belong to you, and a test key only sees practice businesses.

Returns

200 with data: a list of templates, each with id, name, kind, contact_id, money_account, lines, reference, memo, currency, every, every_n, next_date, end_date, due_days, auto_record, approved_by, is_active, last_error, created_by, created_at.

Errors

  • 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)

Set up a repeating document

POST/v1/businesses/{business}/recurring

Saves a template that makes an invoice, bill, expense or cash sale on a regular date, such as monthly rent. Each time it makes a draft, or records it straight away when auto_record is true and someone approved that once here. The template is checked now with the same rules a draft uses.

Path

businessThe business id. It must belong to you, and a test key only sees practice businesses.

Body

namestringrequiredA name for the template, for example "Shop rent, Souq Waqif".
kindstringrequiredinvoice, bill, expense or cash_sale.
contact_idstringThe customer or supplier. Needed for invoices and bills.
everystringrequiredweek, month, quarter or year.
every_nintegerRepeat every this many weeks, months, quarters or years, 1 to 12. Defaults to 1.
start_datedaterequiredDate of the first document.
end_datedateNo documents after this date. Not before start_date.
due_daysintegerDays from the document date to its due date, 0 to 365. Defaults to 0.
money_accountstringFor an expense or cash sale: the bank or cash account code it is paid from or into (an expense may also use the owner's equity account). Leave out for invoices and bills.
referencestringReference put on each document.
memostringMemo put on each document. Defaults to the template name.
currencystringThree-letter currency code. Defaults to the business's own currency.
auto_recordbooleanRecord each document without waiting for approval. Defaults to false.
approved_bystringWho agreed that documents are recorded on their own. Needed when auto_record is true.
created_bystringrequiredWho set the template up.
linesarrayrequiredAt least one line, in the same shape a draft takes.
lines[].accountstringAccount code the line goes to (for example 4000 for sales). Needed when the line has no "item".
lines[].itemstringStock item code, instead of an account. The item must be in the business's stock list and switched on.
lines[].descriptionstringWhat the line is for.
lines[].quantitynumberHow many. Defaults to 1 and must be above zero.
lines[].unit_priceintegerrequiredPrice of one, in the smallest currency unit (12.50 QAR is 1250). Must be above zero.
lines[].discountintegerDiscount off the line as an amount. It must be below the line's price.
lines[].discount_percentnumberDiscount off the line as a percentage, from 0 up to (not including) 100. Use this or "discount", not both.
lines[].taxstringTax code for the line. Leave the field out to use the contact's default tax code; send null for no tax.
lines[].branchstringBranch name or id for the line.
lines[].projectstringProject name or id for the line.

Example

{
  "name": "Shop rent, Souq Waqif",
  "kind": "bill",
  "contact_id": "01934f6e-41d2-7f08-b3a6-7c90e15d2a44",
  "every": "month",
  "start_date": "2026-12-01",
  "end_date": "2027-11-01",
  "due_days": 5,
  "reference": "Lease SW-114",
  "auto_record": true,
  "approved_by": "Khalid Al-Thani",
  "created_by": "Fatima Al-Kuwari",
  "lines": [
    {
      "account": "6000",
      "description": "Monthly rent",
      "unit_price": 1200000,
      "tax": null
    }
  ]
}

Returns

201 with the template: id, name, kind, contact_id, money_account, lines, reference, memo, currency, every, every_n, next_date, end_date, due_days, auto_record, approved_by, is_active, last_error, created_by, created_at. next_date is the date of the next document.

Errors

  • 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
  • 400 invalid_request when the body is not a JSON object
  • 400 invalid_request when "name", "start_date" or "created_by" is missing, "kind" or "every" is not one of the allowed values, "every_n" is not 1 to 12, "due_days" is not 0 to 365, "auto_record" is not true or false, "contact_id" is not an id, or a date is malformed
  • 400 invalid_request when "lines" is missing or an empty list
  • 422 rejected when end_date is before start_date, or auto_record is true without approved_by
  • 422 rejected when an invoice or bill has no contact, the contact is not in this business, or it is on the wrong side (a supplier on a sale, a customer on a purchase)
  • 422 rejected when a money account is given for an invoice or bill, or it is not a switched-on bank or cash account
  • 422 rejected when a line names an account or item not in the books, a tax code that is not set up or is for the other side (sales or purchases), a quantity or price of zero or less, or a discount as big as the line

Switch a repeating document off

POST/v1/businesses/{business}/recurring/{template}/switch-off

Stops a template from making any more documents. Documents it already made are not touched. No request body is needed.

Path

businessThe business id. It must belong to you, and a test key only sees practice businesses.
templateThe repeating document (template) id.

Returns

200 with id and is_active (false).

Errors

  • 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
  • 404 not_found when the repeating document is not in this business

Make repeating documents due now

POST/v1/businesses/{business}/recurring/run

Makes every document due up to a date from the switched-on templates, catching up on any missed dates, and never makes the same date twice. A template that fails (an account switched off, a month closed) keeps the error, is switched off, and the others carry on. This also runs on its own each morning from 6:00.

Path

businessThe business id. It must belong to you, and a test key only sees practice businesses.

Body

datedateMake documents dated up to this day. Defaults to today (UTC).

Example

{
  "date": "2026-12-01"
}

Returns

200 with documents_made: how many documents were made.

Errors

  • 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
  • 400 invalid_request when the body is not a JSON object
  • 400 invalid_request when "date" is not a date like 2026-11-05

Spread costs and income

List schedules

GET/v1/businesses/{business}/schedules

Lists every schedule, earliest start first, with how many months have been recorded and how much has moved.

Path

businessThe business id. It must belong to you, and a test key only sees practice businesses.

Returns

200 with data: a list of schedules, each with id, kind (prepaid or deferred), description, total, starts_on (first of the month), months, holding_account, target_account, document_id, status (active, done or stopped), created_by, approved_by, months_done, moved (how much has been moved so far).

Errors

  • 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)

Spread an amount over months

POST/v1/businesses/{business}/schedules

Sets up a schedule that moves an amount a share at a time from a holding account to where it belongs. A prepaid cost (a year's rent paid upfront) moves from an asset account to an expense; deferred income (a year's service paid in advance by a customer) moves from a liability account to income. It only moves the amount; record the payment itself separately.

Path

businessThe business id. It must belong to you, and a test key only sees practice businesses.

Body

kindstringrequiredprepaid (a cost paid in advance) or deferred (income received in advance).
descriptionstringrequiredWhat is being spread. Each month's entry is named "<description>, month N of M".
totalintegerrequiredThe whole amount, in the smallest currency unit. Above zero. The monthly shares add up to exactly this.
start_monthdaterequiredAny day in the first month. The schedule starts on the first of that month.
monthsintegerrequiredHow many months, 1 to 120.
target_accountstringrequiredCode of the account each share moves to: an expense account for prepaid, an income account for deferred.
holding_accountstringCode of the account the amount waits in: an asset for prepaid, a liability for deferred. Defaults to 1300 (paid in advance) for prepaid, and to 2150 Income received in advance for deferred, which is added the first time it is needed.
document_idstringThe bill or invoice the amount came from, for reference.
created_bystringrequiredWho set it up.
approved_bystringrequiredWho approved it. Each month is recorded on its own in this name.

Example

{
  "kind": "prepaid",
  "description": "Warehouse rent, Industrial Area, 2027",
  "total": 14400000,
  "start_month": "2027-01-01",
  "months": 12,
  "target_account": "6000",
  "document_id": "01934f6e-6e0a-7b93-a1c4-0d2b8f5e9c13",
  "created_by": "Fatima Al-Kuwari",
  "approved_by": "Khalid Al-Thani"
}

Returns

201 with the schedule: id, kind (prepaid or deferred), description, total, starts_on (first of the month), months, holding_account, target_account, document_id, status (active, done or stopped), created_by, approved_by, months_done, moved (how much has been moved so far).

Errors

  • 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
  • 400 invalid_request when the body is not a JSON object
  • 400 invalid_request when "kind" is not prepaid or deferred, "months" is not 1 to 120, "total" is not a whole number above zero, "start_month" is not a date, "document_id" is not an id, or "description", "target_account", "created_by" or "approved_by" is missing
  • 422 rejected when either account is not in the books or is switched off (including a prepaid schedule with no holding account given and no account 1300)
  • 422 rejected when the accounts are the wrong types: prepaid needs an asset and an expense account, deferred a liability and an income account
  • 422 rejected when document_id is not a document of this business

Stop a schedule

POST/v1/businesses/{business}/schedules/{schedule}/stop

Stops a running schedule so no more months are recorded. Months already recorded stay in the books, and what has not moved stays in the holding account.

Path

businessThe business id. It must belong to you, and a test key only sees practice businesses.
scheduleThe schedule id.

Body

bystringrequiredWho stopped it.

Example

{
  "by": "Khalid Al-Thani"
}

Returns

200 with the schedule (id, kind (prepaid or deferred), description, total, starts_on (first of the month), months, holding_account, target_account, document_id, status (active, done or stopped), created_by, approved_by, months_done, moved (how much has been moved so far)), with status stopped.

Errors

  • 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
  • 404 not_found when the schedule is not in this business
  • 400 invalid_request when the body is not a JSON object
  • 400 invalid_request when "by" is missing
  • 422 rejected when the schedule is not running (already done or stopped)

Record schedule shares up to a month

POST/v1/businesses/{business}/schedules/run

Records each running schedule's share for every month up to and including the given month that is not recorded yet. Each share is dated the last day of its month. A schedule whose months are all recorded becomes done. This also runs on its own once a month has turned.

Path

businessThe business id. It must belong to you, and a test key only sees practice businesses.

Body

through_monthdaterequiredAny day in the last month to record.
bystringWho to name as preparing the entries. Defaults to api.

Example

{
  "through_month": "2027-01-31",
  "by": "Fatima Al-Kuwari"
}

Returns

200 with entries_recorded: how many monthly entries were recorded.

Errors

  • 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
  • 400 invalid_request when the body is not a JSON object
  • 400 invalid_request when "through_month" is not a date like 2026-11-05
  • 422 rejected when a share falls in a closed month or one of the schedule's accounts has been switched off

Branches and projects

List branches

GET/v1/businesses/{business}/branches

Lists the business's branches in name order, switched on or off.

Path

businessThe business id. It must belong to you, and a test key only sees practice businesses.

Returns

200 with data: a list of branches, each with id, name, name_ar, contact_id and is_active.

Errors

  • 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)

Add a branch

POST/v1/businesses/{business}/branches

Adds a branch, such as a second shop or kitchen, so lines can be tagged with it and profit seen for each one. Tags do not change how the books balance.

Path

businessThe business id. It must belong to you, and a test key only sees practice businesses.

Body

namestringrequiredBranch name. Must be unique among the business's branches, ignoring case.
name_arstringName in Arabic.

Example

{
  "name": "The Pearl",
  "name_ar": "اللؤلؤة"
}

Returns

201 with id, name, name_ar, contact_id (always null for a branch) and is_active.

Errors

  • 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
  • 400 invalid_request when the body is not a JSON object
  • 400 invalid_request when "name" is missing
  • 422 rejected when there is already a branch with that name

Set a draft's branch and project

POST/v1/businesses/{business}/documents/{document}/tags

Sets the branch and project of a draft document, used for its lines that do not name their own. Both are set on every call, so a field you leave out is cleared.

Path

businessThe business id. It must belong to you, and a test key only sees practice businesses.
documentThe draft document id.

Body

branchstringBranch name or id. Cleared if left out.
projectstringProject name or id. Cleared if left out.

Example

{
  "branch": "The Pearl",
  "project": "Lusail villa fit-out"
}

Returns

200 with id, branch (name or null) and project (name or null).

Errors

  • 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
  • 404 not_found when the document is not in this business
  • 400 invalid_request when the body is not a JSON object
  • 422 rejected when the document is not a draft
  • 422 rejected when no branch or project has that name or id, or it is switched off

List projects

GET/v1/businesses/{business}/projects

Lists the business's projects in name order, switched on or off.

Path

businessThe business id. It must belong to you, and a test key only sees practice businesses.

Returns

200 with data: a list of projects, each with id, name, name_ar, contact_id and is_active.

Errors

  • 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)

Add a project

POST/v1/businesses/{business}/projects

Adds a project, such as a fit-out or an event, so its income and costs can be tagged and seen together. A project can name the customer it is for.

Path

businessThe business id. It must belong to you, and a test key only sees practice businesses.

Body

namestringrequiredProject name. Must be unique among the business's projects, ignoring case.
name_arstringName in Arabic.
contact_idstringThe customer the project is for, one of this business's contacts.

Example

{
  "name": "Lusail villa fit-out",
  "name_ar": "تجهيز فيلا لوسيل",
  "contact_id": "01934f6e-0c11-7a52-8e4b-2f6d9a1c3e70"
}

Returns

201 with id, name, name_ar, contact_id and is_active.

Errors

  • 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
  • 400 invalid_request when the body is not a JSON object
  • 400 invalid_request when "name" is missing or "contact_id" is not an id
  • 422 rejected when there is already a project with that name
  • 422 rejected: contact_id is not one of this business's contacts.

Budgets

List budgets

GET/v1/businesses/{business}/budgets

Lists the business's budgets in name order.

Path

businessThe business id. It must belong to you, and a test key only sees practice businesses.

Returns

200 with data: a list of budgets, each with id, name, created_by and created_at.

Errors

  • 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)

Create a budget

POST/v1/businesses/{business}/budgets

Creates an empty, named budget: what the owner expects to earn and spend. Add the figures with the budget lines endpoint.

Path

businessThe business id. It must belong to you, and a test key only sees practice businesses.

Body

namestringrequiredBudget name, unique in the business, for example "2027 plan".
created_bystringrequiredWho made it.

Example

{
  "name": "2027 plan",
  "created_by": "Khalid Al-Thani"
}

Returns

201 with id and name.

Errors

  • 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
  • 400 invalid_request when the body is not a JSON object
  • 400 invalid_request when "name" or "created_by" is missing
  • 409 conflict when the business already has a budget with that name

Set budget figures

PUT/v1/businesses/{business}/budgets/{budget}/lines

Sets the budgeted amount for an income or expense account in a month, optionally for one branch. Each figure replaces any earlier one for the same account, month and branch; an amount of null clears it. Figures you do not send are left as they are.

Path

businessThe business id. It must belong to you, and a test key only sees practice businesses.
budgetThe budget id.

Body

linesarrayrequired1 to 600 figures.
lines[].accountstringrequiredCode of an income or expense account.
lines[].monthdaterequiredAny day in the month. Saved as the first of the month.
lines[].amountintegerrequiredExpected income or spending for the month, in the smallest currency unit, or null to clear the figure.
lines[].branchstringBranch name or id, for a branch's own figure.

Example

{
  "lines": [
    {
      "account": "4000",
      "month": "2027-01-01",
      "amount": 15000000
    },
    {
      "account": "6000",
      "month": "2027-01-01",
      "amount": 1200000
    },
    {
      "account": "4000",
      "month": "2027-01-01",
      "amount": 4500000,
      "branch": "The Pearl"
    }
  ]
}

Returns

200 with id, name and lines: every figure in the budget, each with account, month, branch and amount.

Errors

  • 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
  • 404 not_found when the budget is not in this business
  • 400 invalid_request when the body is not a JSON object
  • 400 invalid_request when "lines" is not a list of 1 to 600 figures, an amount is not a whole number or null, a month is not a date, or an account is missing
  • 422 rejected when an account is not in the books or is not an income or expense account
  • 422 rejected when a branch does not exist or is switched off

Compare a budget with what happened

GET/v1/businesses/{business}/budgets/{budget}/vs-actual

For each income and expense account with a budget figure or actual activity, compares the budget for the months in the period with what the books show. Income is shown as credits less debits and expenses as debits less credits, so both are normally positive.

Path

businessThe business id. It must belong to you, and a test key only sees practice businesses.
budgetThe budget id.

Query

fromdateFirst day of the period. Defaults to the first day of the month that "to" falls in.
todateLast day of the period, included. Defaults to today (UTC).
branchstringBranch name or id, to compare one branch only.

Returns

200 with budget (name), from, to, currency and accounts [{code, name, type (income or expense), budget, actual, difference (actual less budget)}], income accounts first.

Errors

  • 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
  • 404 not_found when the budget is not in this business
  • 400 invalid_request when "from" or "to" is not a date like 2026-11-05, or "from" is after "to"
  • 422 rejected when the branch does not exist or is switched off

Stock

List stock items

GET/v1/businesses/{business}/items

Lists every item of the business, including switched-off ones, sorted by code, with how many are on hand and what they are worth.

Path

businessThe business id.

Returns

200 with data: an array of items, each with id, code, name, name_ar, unit, is_active, stock_account, sales_account, cost_account, on_hand, value, average_cost and created_at.

Errors

  • 404 not_found when the business does not exist or is not visible to this key

Add a stock item

POST/v1/businesses/{business}/items

Adds an item the business buys and sells. Stock is valued at weighted average cost and moves when a bill, receipt, invoice or cash sale with this item on a line is approved, and through counts and opening stock. The item starts with nothing on hand.

Path

businessThe business id.

Body

codestringrequiredUp to 40 letters, numbers, dots, dashes or underscores. Document lines refer to the item by this code.
namestringrequiredThe item's name.
name_arstringThe name in Arabic.
unitstringThe unit it is counted in, like box or kg. Defaults to each.
stock_accountstringCode of the asset account that holds its value. Defaults to 1200.
sales_accountstringCode of the income account sales go to. Defaults to 4000.
cost_accountstringCode of the expense account the cost of what is sold goes to. Defaults to 5000.

Example

{
  "code": "RICE-5KG",
  "name": "Basmati rice 5 kg",
  "name_ar": "أرز بسمتي 5 كغ",
  "unit": "bag"
}

Returns

201 with the item: id, code, name, name_ar, unit, is_active, stock_account, sales_account, cost_account, on_hand, value, average_cost (null when nothing is on hand) and created_at.

Errors

  • 400 invalid_request when the body is not a JSON object
  • 400 invalid_request when "code" or "name" is missing or not text
  • 400 invalid_request when the code is not up to 40 letters, numbers, dots, dashes or underscores
  • 409 conflict when an item with this code already exists
  • 422 rejected when an account code is not in this business's books, or is not the right type (asset for stock, income for sales, expense for cost)
  • 404 not_found when the business does not exist or is not visible to this key

Get a stock item

GET/v1/businesses/{business}/items/{item}

Returns one item with what is on hand and its latest 100 stock movements, newest first.

Path

businessThe business id.
itemThe item id (not its code).

Returns

200 with the item fields (id, code, name, unit, on_hand, value, average_cost and the rest) and movements, each with date, reason (purchase, sale, count, opening or void), quantity (negative when stock went out), value, document_number, created_by and created_at.

Errors

  • 404 not_found when the business does not exist or is not visible to this key
  • 404 not_found when the item does not exist in this business

Record a stock count

POST/v1/businesses/{business}/items/{item}/count

Sets what is on hand to the number counted and records the difference in the books. A shortfall is taken out at average cost and charged to the cost account; extra stock found is added at average cost, or at unit_cost when none was on hand. A count that matches what is on hand changes nothing.

Path

businessThe business id.
itemThe item id.

Body

datedaterequiredThe day of the count.
countednumberrequiredHow many were counted, zero or more. Fractions are allowed.
bystringrequiredWho counted.
reasonstringA note added to the entry, like damaged in storage.
unit_costintegerCost of one unit in the smallest currency unit, above zero. Needed when stock is found and none was on hand.

Example

{
  "date": "2026-11-30",
  "counted": 46,
  "by": "Fatima Al-Kuwari",
  "reason": "Four bags torn in the store room"
}

Returns

200 with the item after the count: on_hand, value, average_cost and the other item fields.

Errors

  • 400 invalid_request when the body is not a JSON object
  • 400 invalid_request when "date" is not a date like 2026-11-05
  • 400 invalid_request when "counted" is not a number of zero or more
  • 400 invalid_request when "by" is missing
  • 400 invalid_request when "unit_cost" is given but is not a whole number above zero
  • 422 rejected when stock was found, none was on hand and no unit_cost was given
  • 422 rejected when the month of the date is closed
  • 404 not_found when the business or item does not exist

Record opening stock

POST/v1/businesses/{business}/items/{item}/opening

Puts the stock a business already had into the books when it starts using BasePipe, against the opening balances account (3900). Only allowed before the item has any stock movements; after that, use a stock count.

Path

businessThe business id.
itemThe item id.

Body

datedaterequiredThe day the opening stock is recorded on.
quantitynumberrequiredHow many were on hand, above zero.
unit_costintegerrequiredCost of one unit in the smallest currency unit, above zero.
bystringrequiredWho recorded it.

Example

{
  "date": "2026-11-01",
  "quantity": 50,
  "unit_cost": 2850,
  "by": "Fatima Al-Kuwari"
}

Returns

201 with the item: on_hand, value, average_cost and the other item fields.

Errors

  • 400 invalid_request when the body is not a JSON object
  • 400 invalid_request when "date" is not a date like 2026-11-05
  • 400 invalid_request when "quantity" is not a number above zero
  • 400 invalid_request when "unit_cost" is not a whole number above zero
  • 400 invalid_request when "by" is missing
  • 422 rejected when the item already has stock movements
  • 422 rejected when the business has no opening balances account (3900)
  • 422 rejected when the month of the date is closed
  • 404 not_found when the business or item does not exist

Get stock on hand

GET/v1/businesses/{business}/reports/stock-on-hand

Returns what is on the shelf now, item by item at average cost, and the total value. It also checks each stock account in the books against the value of the stock on hand and lists any that differ. This report returns JSON only.

Path

businessThe business id.

Returns

200 with currency, total_value, items (each with code, name, unit, on_hand, value and average_cost) and mismatches (each with account, in_books and on_hand; empty when the books agree with the shelf).

Errors

  • 404 not_found when the business does not exist or is not visible to this key

Equipment

List equipment

GET/v1/businesses/{business}/equipment

Lists all the business's equipment, active and sold or scrapped, oldest purchase first, with wear and tear to date and book value.

Path

businessThe business id.

Returns

200 with data: an array of equipment, each with the same fields as a single piece of equipment (id, name, status, cost, monthly_amount, worn, book_value, months_recorded and the rest).

Errors

  • 404 not_found when the business does not exist or is not visible to this key

Register equipment

POST/v1/businesses/{business}/equipment

Registers a piece of equipment and approves its straight-line wear and tear schedule. Nothing is posted to the books until the monthly run records each month's wear and tear. Wear and tear starts the month after purchase unless start_month says otherwise.

Path

businessThe business id.

Body

namestringrequiredWhat the equipment is.
purchase_datedaterequiredThe day it was bought.
costintegerrequiredWhat it cost, in the smallest currency unit, above zero.
useful_life_monthsintegerrequiredHow many months it will be used, from 1 to 600.
approved_bystringrequiredWho approved the schedule.
residualintegerWhat it will be worth at the end, in the smallest currency unit. Defaults to 0.
start_monthstringFirst month of wear and tear, like 2026-12. Defaults to the month after purchase.
opening_wornintegerWear and tear already counted before BasePipe, in the smallest currency unit. Defaults to 0.
purchase_document_idstringId of the recorded bill or receipt it was bought on.
asset_accountstringCode of the asset account for its cost. Defaults to 1500.
worn_accountstringCode of the asset account for wear and tear to date. Defaults to 1510.
expense_accountstringCode of the expense account for monthly wear and tear. Defaults to 6800.

Example

{
  "name": "Toyota Hiace delivery van",
  "purchase_date": "2026-11-10",
  "cost": 12000000,
  "useful_life_months": 60,
  "residual": 2400000,
  "approved_by": "Khalid Al-Thani"
}

Returns

201 with the equipment: id, name, status (active), purchase_date, cost, residual, opening_worn, useful_life_months, start_month, end_month, monthly_amount, worn, book_value, months_recorded, last_month_recorded, asset_account, worn_account, expense_account, purchase_document_id, approved_by, created_at, and the disposal fields (null).

Errors

  • 400 invalid_request when the body is not a JSON object
  • 400 invalid_request when "useful_life_months" is not a whole number from 1 to 600
  • 400 invalid_request when "name" or "approved_by" is missing
  • 400 invalid_request when "purchase_date" is not a date like 2026-11-05
  • 400 invalid_request when "cost", "residual" or "opening_worn" is not a whole number above zero in the smallest currency unit
  • 400 invalid_request when "start_month" is not a month like 2026-11
  • 400 invalid_request when "purchase_document_id" is not an id
  • 422 rejected when the purchase document is not a recorded bill or receipt of this business
  • 422 rejected when residual plus opening_worn is not less than cost
  • 422 rejected when an account code is not in this business's books or is not the right type
  • 404 not_found when the business does not exist or is not visible to this key

Get a piece of equipment

GET/v1/businesses/{business}/equipment/{asset}

Returns one piece of equipment with every month of wear and tear recorded so far, oldest first.

Path

businessThe business id.
assetThe equipment id.

Returns

200 with the equipment fields (status is active or disposed; book_value is 0 once disposed) and wear_and_tear, each with month (like 2026-12), month_no, amount and entry_id.

Errors

  • 404 not_found when the business does not exist or is not visible to this key
  • 404 not_found when the equipment does not exist in this business

Sell or scrap equipment

POST/v1/businesses/{business}/equipment/{asset}/dispose

Records that equipment was sold or scrapped and posts the gain or loss. Wear and tear is brought up to date to the month before; none is counted for the month it goes. Leave out proceeds, or send 0, when it was scrapped for nothing.

Path

businessThe business id.
assetThe equipment id.

Body

datedaterequiredThe day it was sold or scrapped. Must be on or after the purchase date.
bystringrequiredWho approved it.
proceedsintegerMoney received, in the smallest currency unit. Defaults to 0.
money_accountstringCode of the asset account the money went into. Needed when proceeds is above zero.
memostringA note for the entry.

Example

{
  "date": "2026-11-20",
  "proceeds": 350000,
  "money_account": "1010",
  "by": "Khalid Al-Thani",
  "memo": "Sold old espresso machine to Souq Waqif cafe"
}

Returns

200 with the equipment after disposal: status disposed, disposed_on, disposed_by, disposal_proceeds, book_value 0 and the other equipment fields.

Errors

  • 400 invalid_request when the body is not a JSON object
  • 400 invalid_request when "proceeds" is not a whole number above zero in the smallest currency unit
  • 400 invalid_request when "money_account" is missing and proceeds is above zero
  • 400 invalid_request when "date" is not a date like 2026-11-05, or "by" is missing
  • 422 rejected when the equipment has already been sold or scrapped
  • 422 rejected when the date is before the purchase date
  • 422 rejected when "money_account" is not an asset account in this business's books
  • 422 rejected when the month of the date is closed
  • 404 not_found when the business or equipment does not exist

Record wear and tear due

POST/v1/businesses/{business}/equipment/run-wear-and-tear

Records every month of wear and tear due on active equipment up to and including the given month that is not recorded yet, oldest first, each dated the last day of its month. BasePipe's scheduler calls this at each month end. It is safe to call again: months already recorded are skipped.

Path

businessThe business id.

Body

through_monthstringrequiredThe last month to record, like 2026-11.
bystringWho ran it. Defaults to scheduler.

Example

{
  "through_month": "2026-11",
  "by": "Khalid Al-Thani"
}

Returns

200 with through_month and entries_recorded (how many monthly entries were posted; 0 when nothing was due).

Errors

  • 400 invalid_request when the body is not a JSON object
  • 400 invalid_request when "through_month" is not a month like 2026-11
  • 400 invalid_request when "by" is not text
  • 422 rejected when a month that needs an entry is closed
  • 404 not_found when the business does not exist or is not visible to this key

Currencies

Get an exchange rate

GET/v1/exchange-rates

Returns the rate used for a currency on a date: your own rate if you have set one, otherwise BasePipe's fixed pegs for the Gulf currencies tied to the US dollar (USD, SAR, AED, BHD, OMR and JOD against QAR). The rate is how many base units one unit of the currency is worth. Rates belong to your partner account, not to one business.

Query

currencystringrequiredThree-letter code of the currency, like USD.
basestringThree-letter code of the currency the rate is in. Defaults to QAR.
datedateThe day the rate applies to. Defaults to today (UTC). The latest rate valid on or before this day is used.

Returns

200 with base, currency, date and rate (for example 3.64 for USD against QAR), or rate null when no rate is known for that date.

Errors

  • 400 invalid_request when "currency" is missing or is not a three-letter code
  • 400 invalid_request when "date" is not a date like 2026-11-05

Set an exchange rate

POST/v1/exchange-rates

Sets your own rate for a currency from a date on, for currencies without a fixed peg such as EUR or KWD. Your rate is used before BasePipe's fixed pegs. Setting a rate again for the same currencies and date replaces it.

Body

currencystringrequiredThree-letter code of the currency, like EUR.
ratenumberrequiredHow many base units one unit of the currency is worth, above zero.
basestringThree-letter code of the currency the rate is in. Defaults to QAR.
valid_fromdateThe first day the rate applies. Defaults to today (UTC).
bystringWho set it. Defaults to partner.

Example

{
  "currency": "EUR",
  "base": "QAR",
  "rate": 3.9512,
  "valid_from": "2026-11-01",
  "by": "Finance team"
}

Returns

201 with base, currency, rate and valid_from.

Errors

  • 400 invalid_request when the body is not a JSON object
  • 400 invalid_request when "currency" is missing or not text
  • 400 invalid_request when "rate" is not a number above zero
  • 400 invalid_request when "valid_from" is not a date like 2026-11-05
  • 422 rejected when the currency or base is not one BasePipe knows yet

Tax

Update the business's tax details

POST/v1/businesses/{business}/details

Sets the details an electronic invoice will need and the share of the business owned by non-Qatari, non-GCC owners, which the income tax estimate uses. Only the fields you send change; leaving a field out keeps its current value.

Path

businessThe business id.

Body

legal_namestringThe registered legal name.
tax_numberstringThe tax number from the General Tax Authority.
commercial_registrationstringThe commercial registration (CR) number.
addressstringThe business address.
foreign_ownership_pctnumberPercentage owned by non-Qatari, non-GCC owners, from 0 to 100. Defaults to 0.

Example

{
  "legal_name": "Al Waab Trading W.L.L.",
  "tax_number": "5000123456",
  "commercial_registration": "145678",
  "address": "Building 12, Street 340, Al Waab, Doha, Qatar",
  "foreign_ownership_pct": 49
}

Returns

200 with name, legal_name, tax_number, commercial_registration, address and foreign_ownership_pct.

Errors

  • 400 invalid_request when the body is not a JSON object
  • 400 invalid_request when a text field is not text
  • 400 invalid_request when "foreign_ownership_pct" is not a number from 0 to 100
  • 404 not_found when the business does not exist or is not visible to this key

Get the tax report

GET/v1/businesses/{business}/reports/tax

Returns the tax charged, paid and withheld by tax code over a period, the withholding owed by month with its due date (the 16th of the next month), what the books show as still owed to the tax authority on the end date, and a rough income tax estimate. The estimate is 10% of this financial year's profit so far on the foreign-owned share; it is a guide, not a return. This report returns JSON only.

Path

businessThe business id.

Query

fromdateFirst day of the period. Defaults to the first day of the month that "to" falls in.
todateLast day of the period. Defaults to today (UTC).

Returns

200 with from, to, currency, codes (each with code, name, kind, rate, documents, taxable and tax, from recorded documents issued in the period), withholding_by_month (each with month as the first day of the month, withheld, due_by and documents), still_owed (withholding and sales_tax) and income_tax_estimate (year_starts, profit_so_far, foreign_ownership_pct and estimate).

Errors

  • 400 invalid_request when "from" or "to" is not a date like 2026-11-05
  • 400 invalid_request when "from" is after "to"
  • 404 not_found when the business does not exist or is not visible to this key

List tax codes

GET/v1/businesses/{business}/tax-codes

Lists the business's tax codes, sorted by kind and then code. A kind is output (tax charged on sales), input (tax paid on purchases that can be reclaimed) or withholding (tax kept back from a supplier's payment and owed to the authority).

Path

businessThe business id.

Returns

200 with data: an array of tax codes, each with code, name, name_ar, kind, rate (a percentage, like 5), account (the account code the tax goes to) and is_active.

Errors

  • 404 not_found when the business does not exist or is not visible to this key

Add a tax code

POST/v1/businesses/{business}/tax-codes

Adds a tax code that invoice, bill and receipt lines can carry. Without an account, the tax goes to 2300 Withholding tax owed, 2310 Sales tax owed or 1310 Sales tax to reclaim, depending on the kind; the account is added to the books the first time it is needed. The code is stored in capital letters.

Path

businessThe business id.

Body

codestringrequiredUp to 20 capital letters, numbers, dashes or underscores, like WHT5. Lower case is turned into capitals.
namestringrequiredWhat the code is called.
kindstringrequiredoutput, input or withholding.
ratenumberrequiredA percentage above 0 and below 100, like 5.
name_arstringThe name in Arabic.
accountstringCode of an active account in this business's books to post the tax to. Defaults by kind as described above.

Example

{
  "code": "WHT5",
  "name": "Withholding tax 5% (non-resident services)",
  "name_ar": "ضريبة الاستقطاع 5% (خدمات غير المقيمين)",
  "kind": "withholding",
  "rate": 5
}

Returns

201 with code, name, kind, rate and account.

Errors

  • 400 invalid_request when the body is not a JSON object
  • 400 invalid_request when "code" or "name" is missing or not text
  • 400 invalid_request when "kind" is not output, input or withholding
  • 400 invalid_request when "rate" is not a number above 0 and below 100
  • 400 invalid_request when the code is not up to 20 capital letters, numbers, dashes or underscores
  • 409 conflict when a tax code with this code already exists for the business
  • 422 rejected when "account" is not an active account in this business's books
  • 404 not_found when the business does not exist or is not visible to this key

Set up Qatar tax codes

POST/v1/businesses/{business}/tax/setup-qatar

Adds the WHT5 tax code for Qatar's 5% withholding tax on payments to non-residents for services, posting to 2300 Withholding tax owed. Qatar has no VAT in force, so no sales tax code is added. Safe to call again: an existing WHT5 is left as it is.

Path

businessThe business id.

Returns

201 with codes: ["WHT5"].

Errors

  • 404 not_found when the business does not exist or is not visible to this key

Reports

Get the balance sheet

GET/v1/businesses/{business}/reports/balance-sheet

Returns what the business owns, owes and the owner's equity on a date, and whether the two sides balance. Send ?format=html for a printable page and ?lang=ar for Arabic.

Path

businessThe business id.

Query

as_ofdateThe date to report on. Defaults to today (UTC).
formatstringjson (default) or html.
langstringen (default) or ar.

Returns

200 with report, title, business, currency, lang, as_of, assets (sections for cash and bank, other current assets and equipment, plus total), liabilities (sections owed within a year and after a year, plus total), equity (sections and total), total_liabilities_and_equity and balanced (true when assets equal liabilities plus equity). With format=html, a 200 HTML page instead.

Errors

  • 400 invalid_request when "as_of" is not a date like 2026-11-05
  • 400 invalid_request when "format" is not json or html, or "lang" is not en or ar
  • 404 not_found when the business does not exist or is not visible to this key

List bills still to pay

GET/v1/businesses/{business}/reports/bills-to-pay

Lists recorded bills still unpaid on a date, grouped into age bands by how late they are, plus supplier credits not yet used. Payments and credits dated on or before as_of count.

Path

businessId of the business. Test keys only see practice businesses; live keys only see live ones.

Query

as_ofdateThe date to report on, YYYY-MM-DD. Defaults to today.

Returns

200 with the same shape as who-owes-us: as_of, currency, total_outstanding, by_age, items (bills), unused_credits and credits (supplier credits).

Errors

  • 400 invalid_request: as_of is not YYYY-MM-DD.
  • 404 not_found: the business does not exist or is not visible to this key.

Get the cash flow

GET/v1/businesses/{business}/reports/cash-flow

Returns cash at the start of a period, the money that came in and went out from running the business, from equipment bought or sold, and from the owner and lenders, and cash at the end. Send ?format=html for a printable page and ?lang=ar for Arabic.

Path

businessThe business id.

Query

fromdateFirst day of the period. Defaults to the first day of the month that "to" falls in.
todateLast day of the period. Defaults to today (UTC).
formatstringjson (default) or html.
langstringen (default) or ar.

Returns

200 with report, title, business, currency, lang, from, to, opening_cash, sections (operating, investing and financing, each with lines and total), net_change, closing_cash and adds_up (true when opening cash plus the change equals closing cash). With format=html, a 200 HTML page instead.

Errors

  • 400 invalid_request when "from" or "to" is not a date like 2026-11-05
  • 400 invalid_request when "from" is after "to"
  • 400 invalid_request when "format" is not json or html, or "lang" is not en or ar
  • 404 not_found when the business does not exist or is not visible to this key

Get the profit and loss

GET/v1/businesses/{business}/reports/profit-and-loss

Returns income and costs for a period, grouped into sales, cost of sales, running costs, other income and other costs, with gross, operating and net profit. Send ?format=html for a printable page with no BasePipe branding (a browser can save it as PDF) and ?lang=ar for Arabic wording and a right-to-left page.

Path

businessThe business id.

Query

fromdateFirst day of the period. Defaults to the first day of the month that "to" falls in.
todateLast day of the period. Defaults to today (UTC).
formatstringjson (default) or html.
langstringen (default) or ar. Changes section labels and uses Arabic account names where they are set.

Returns

200 with report, title, business, currency, lang, from, to, sections (each with key, label, lines of code, name and amount, and total), gross_profit, operating_profit and net_profit. All amounts are in the business's own currency in the smallest unit. With format=html, a 200 HTML page instead.

Errors

  • 400 invalid_request when "from" or "to" is not a date like 2026-11-05
  • 400 invalid_request when "from" is after "to"
  • 400 invalid_request when "format" is not json or html, or "lang" is not en or ar
  • 404 not_found when the business does not exist or is not visible to this key

List what customers owe

GET/v1/businesses/{business}/reports/who-owes-us

Lists recorded invoices with money still owed on a date, grouped into age bands by how late they are, plus credit notes not yet used. Payments and credits dated on or before as_of count.

Path

businessId of the business. Test keys only see practice businesses; live keys only see live ones.

Query

as_ofdateThe date to report on, YYYY-MM-DD. Defaults to today.

Returns

200 with as_of; currency (the business's); total_outstanding; by_age [{band, outstanding}] for 'not yet due', '1-30 days late', '31-60 days late', '61-90 days late', 'over 90 days late'; items [{document_id, number, contact {id, name}, issue_date, due_date, total, outstanding, days_overdue, age_band, currency, outstanding_base}]; unused_credits; credits [{document_id, number, contact, issue_date, unused, currency, unused_base}]. Totals are in the business's currency; each item's total and outstanding are in its own currency.

Errors

  • 400 invalid_request: as_of is not YYYY-MM-DD.
  • 404 not_found: the business does not exist or is not visible to this key.

Ledger reports

Get the audit trail

GET/v1/businesses/{business}/reports/audit-log

Who did what and when over a period: documents prepared, approved and voided, payments recorded and voided, and events in the books such as entries recorded. Newest first, up to 1,000 events.

Path

businessThe business id. It must belong to you, and a test key only sees practice businesses.

Query

fromdateFirst day of the period. Defaults to the first day of the month that "to" falls in.
todateLast day of the period, included. Defaults to today (UTC).

Returns

200 with from, to and events [{at, actor, action, subject, subject_id, detail}].

Errors

  • 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
  • 400 invalid_request when "from" or "to" is not a date like 2026-11-05, or "from" is after "to"

Get changes in equity

GET/v1/businesses/{business}/reports/changes-in-equity

What the owners' stake was at the start of the period, what they put in and took out, the profit, and the stake at the end.

Path

businessThe business id. It must belong to you, and a test key only sees practice businesses.

Query

fromdateFirst day of the period. Defaults to the first day of the month that "to" falls in.
todateLast day of the period, included. Defaults to today (UTC).

Returns

200 with from, to, currency and rows [{line, amount}] in this order: Owners' stake at the start, Put in by owners, Taken out by owners (negative), Profit for the period, Owners' stake at the end.

Errors

  • 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
  • 400 invalid_request when "from" or "to" is not a date like 2026-11-05, or "from" is after "to"

Get the general ledger

GET/v1/businesses/{business}/reports/general-ledger

Every line in each account over a period, with the balance before the period and a running balance. Balances are shown the natural way round: assets and expenses as debits, the rest as credits. Accounts with no balance and no lines are left out.

Path

businessThe business id. It must belong to you, and a test key only sees practice businesses.

Query

fromdateFirst day of the period. Defaults to the first day of the month that "to" falls in.
todateLast day of the period, included. Defaults to today (UTC).
accountstringOnly this account code.

Returns

200 with from, to, currency and accounts [{code, name, opening, closing, lines [{entry_id, entry_number, date, memo, description, debit, credit, balance, branch, project}]}].

Errors

  • 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
  • 400 invalid_request when "from" or "to" is not a date like 2026-11-05, or "from" is after "to"

Get profit and loss in columns

GET/v1/businesses/{business}/reports/profit-and-loss-by

Income and expenses per account over a period, split into columns by month, branch or project. Lines with no branch or project go under "Not tagged".

Path

businessThe business id. It must belong to you, and a test key only sees practice businesses.

Query

fromdateFirst day of the period. Defaults to the first day of the month that "to" falls in.
todateLast day of the period, included. Defaults to today (UTC).
bystringrequiredmonth, branch or project.

Returns

200 with from, to, by, currency, columns (column names in order, such as 2026-10 and 2026-11, or branch names), accounts [{code, name, group, amounts {column: amount}}] and profit {column: income less expenses}.

Errors

  • 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
  • 400 invalid_request when "from" or "to" is not a date like 2026-11-05, or "from" is after "to"
  • 400 invalid_request when "by" is missing or not month, branch or project

Get purchases by supplier

GET/v1/businesses/{business}/reports/purchases-by-supplier

Net spending per supplier over a period: recorded bills and expenses less supplier credits, before tax, in the business's own currency. Largest first.

Path

businessThe business id. It must belong to you, and a test key only sees practice businesses.

Query

fromdateFirst day of the period. Defaults to the first day of the month that "to" falls in.
todateLast day of the period, included. Defaults to today (UTC).

Returns

200 with from, to, currency and rows [{contact_id, contact_name, documents, spent}]. An expense with no contact uses the party name saved on the document, or "No supplier named".

Errors

  • 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
  • 400 invalid_request when "from" or "to" is not a date like 2026-11-05, or "from" is after "to"

Get sales by customer

GET/v1/businesses/{business}/reports/sales-by-customer

Net sales per customer over a period: recorded invoices and cash sales less credit notes, before tax, in the business's own currency. Largest first.

Path

businessThe business id. It must belong to you, and a test key only sees practice businesses.

Query

fromdateFirst day of the period. Defaults to the first day of the month that "to" falls in.
todateLast day of the period, included. Defaults to today (UTC).

Returns

200 with from, to, currency and rows [{contact_id, contact_name, documents (how many), sales}]. Sales with no customer are under "No customer named".

Errors

  • 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
  • 400 invalid_request when "from" or "to" is not a date like 2026-11-05, or "from" is after "to"

Get sales by item

GET/v1/businesses/{business}/reports/sales-by-item

Net quantity and sales per item or service over a period, from recorded invoices and cash sales less credit notes, before tax. Lines without an item are grouped under their account. Largest first.

Path

businessThe business id. It must belong to you, and a test key only sees practice businesses.

Query

fromdateFirst day of the period. Defaults to the first day of the month that "to" falls in.
todateLast day of the period, included. Defaults to today (UTC).

Returns

200 with from, to, currency and rows [{item_code (null for lines without an item), name, quantity, sales}].

Errors

  • 404 not_found when the business is not one of yours, or is live and you used a test key (or the other way round)
  • 400 invalid_request when "from" or "to" is not a date like 2026-11-05, or "from" is after "to"

Financial years

Set the financial year start

POST/v1/businesses/{business}/settings/year-start

Chooses the month the business's financial year starts in. It can't change once any year has been closed.

Path

businessThe business id.

Body

monthintegerrequiredFrom 1 (January) to 12 (December).
bystringrequiredWho made the change.

Example

{
  "month": 4,
  "by": "Fatima Al-Kuwari"
}

Returns

200 with starts_in_month.

Errors

  • 400 invalid_request: the body is not a JSON object, month is not a whole number, or by is missing
  • 404 not_found: the business is not yours or is in the other mode
  • 422 rejected: month is not from 1 to 12, or a year has already been closed

List financial years

GET/v1/businesses/{business}/years

Shows which month the financial year starts in, and every year that has been closed or reopened, oldest first.

Path

businessThe business id.

Returns

200 with starts_in_month (1 to 12) and data: years with starts_on, ends_on, status (closed or reopened), profit (income minus costs for the year, smallest currency unit), closed_by, closed_at, reopened_by, reopened_at, reopen_reason.

Errors

  • 404 not_found: the business is not yours or is in the other mode

Close a financial year

POST/v1/businesses/{business}/years/{year_end}/close

Closes the financial year ending on the given date: every month in it is closed and the year's profit is noted. Earlier years with entries must be closed first. The response also counts draft documents and unmatched bank lines left in the year, which can no longer be recorded there.

Path

businessThe business id.
year_endLast day of the financial year, YYYY-MM-DD, e.g. 2026-12-31.

Body

bystringrequiredWho closed the year.

Example

{
  "by": "Fatima Al-Kuwari"
}

Returns

201 with the year (starts_on, ends_on, status closed, profit, closed_by, closed_at, reopened_by, reopened_at, reopen_reason) and still_waiting with drafts and unmatched_bank_lines.

Errors

  • 400 invalid_request: year_end is not YYYY-MM-DD, the body is not a JSON object, or by is missing
  • 404 not_found: the business is not yours or is in the other mode
  • 422 rejected: year_end is not the last day of a financial year (the message gives the right date), the year is already closed, or the year before has entries and is not closed yet

Reopen the latest closed year

POST/v1/businesses/{business}/years/{year_end}/reopen

Reopens the latest closed financial year so a correction can be recorded; all its months open again. The reopening and its reason are logged. Close the year again when the correction is done.

Path

businessThe business id.
year_endLast day of the closed financial year, YYYY-MM-DD.

Body

bystringrequiredWho reopened the year.
reasonstringrequiredWhy it is reopened.

Example

{
  "by": "Fatima Al-Kuwari",
  "reason": "Lulu Hypermarket invoice for December was missed"
}

Returns

200 with the year: starts_on, ends_on, status reopened, profit, closed_by, closed_at, reopened_by, reopened_at, reopen_reason.

Errors

  • 400 invalid_request: year_end is not YYYY-MM-DD, the body is not a JSON object, or by or reason is missing
  • 404 not_found: the business is not yours or is in the other mode
  • 422 rejected: the year ending on that date isn't closed, or a later year is closed (only the latest closed year can be reopened)

AI bookkeeper

Get the AI bookkeeper's status

GET/v1/businesses/{business}/bookkeeper

Shows whether the AI bookkeeper is working for a business, the questions it is waiting on the owner to answer, and the latest 50 things it did. It works only when the business's plan includes it, it is not paused, and the business is not read-only.

Path

businessrequiredThe business's id.

Returns

200 with on, plan_has, paused, auto_limit; questions (open ones, oldest first: id, kind of draft or bank_line, subject_id, question_en, question_ar, asked_at, sent, options [{key, en, ar, action, account, paid_from}]); and log (newest first: id, action, subject_id, summary, at, undone, undone_by, can_undo).

Errors

  • 404 not_found when the business is not yours or belongs to the other mode

Undo a bookkeeper action

POST/v1/businesses/{business}/bookkeeper/log/{entry}/undo

Undoes something the AI bookkeeper did: a recorded receipt or bill is voided, and a recorded bank line is unmatched and its entry reversed. Only log entries with action approved or recorded can be undone (can_undo is true).

Path

businessrequiredThe business's id.
entryrequiredThe id of the log entry, from the log in the bookkeeper status.

Body

bystringrequiredWho undid it.

Example

{
  "by": "Khalid Al-Thani"
}

Returns

200 with the bookkeeper status (on, plan_has, paused, auto_limit, questions) and the latest 20 log entries.

Errors

  • 400 invalid_request when by is missing, or the entry is not an approval or a recorded bank line
  • 404 not_found when the business is not yours or the log entry is not found
  • 409 already_undone when the entry has already been undone
  • 422 rejected when the books refuse to void or reverse it

Pause the AI bookkeeper

POST/v1/businesses/{business}/bookkeeper/pause

Stops the AI bookkeeper working on a business until you resume it. Pausing an already paused business changes nothing.

Path

businessrequiredThe business's id.

Body

bystringrequiredWho paused it.

Example

{
  "by": "Khalid Al-Thani"
}

Returns

200 with on, plan_has, paused and auto_limit.

Errors

  • 400 invalid_request when by is missing
  • 404 not_found when the business is not yours or belongs to the other mode

Answer a bookkeeper question

POST/v1/businesses/{business}/bookkeeper/questions/{question}/answer

Answers one of the AI bookkeeper's open questions on the owner's behalf, by choosing one of its options. Depending on the option, the draft is recorded, the bank line is recorded (and a rule is learned so similar lines are recorded on their own next time), or the item is left as it is.

Path

businessrequiredThe business's id.
questionrequiredThe question's id.

Body

optionstringrequiredThe key of one of the question's options, such as "1". A number is also accepted.
bystringrequiredWho answered.

Example

{
  "option": "1",
  "by": "Khalid Al-Thani"
}

Returns

200 with message: a short confirmation of what was done, such as the number of the document recorded.

Errors

  • 400 invalid_request when option is missing or is not one of the answers given, or by is missing
  • 404 not_found when the business is not yours or the question is not found
  • 409 already_answered when the question has already been answered
  • 409 gone when the draft or bank line the question is about is no longer waiting
  • 422 rejected when the books refuse to record it

Resume the AI bookkeeper

POST/v1/businesses/{business}/bookkeeper/resume

Lets the AI bookkeeper work on a business again after a pause. Send a JSON object as the body; an empty one is fine.

Path

businessrequiredThe business's id.

Example

{}

Returns

200 with on, plan_has, paused and auto_limit.

Errors

  • 400 invalid_request when the body is not a JSON object
  • 404 not_found when the business is not yours or belongs to the other mode

Run the AI bookkeeper now

POST/v1/businesses/{business}/bookkeeper/run

Runs one pass of the AI bookkeeper straight away instead of waiting for its daily run. It records receipts and bills it is sure of, matches and records bank lines, asks the owner about the rest (at most five new questions a pass), and closes last month when nothing is left open.

Path

businessrequiredThe business's id.

Returns

200 with drafts_checked, approved, asked, held, bank_matched, bank_recorded, bank_asked, month_closed (the first day of the month closed, YYYY-MM-DD, or null) and ai_calls.

Errors

  • 404 not_found when the business is not yours or belongs to the other mode
  • 409 bookkeeper_off when the plan does not include the AI bookkeeper, it is paused, or the business is read-only

Owner screens and branding

Set your branding

POST/v1/branding

Sets the name and colour shown on the owner dashboard and the accountant screen. Both are replaced on every call, so a field you leave out is cleared and BasePipe's defaults are shown instead.

Body

brand_namestringYour name as owners and accountants should see it.
brand_colourstringA hex colour like #0F5E59.

Example

{
  "brand_name": "SouqPay Books",
  "brand_colour": "#8A1538"
}

Returns

200 with brand_name and brand_colour.

Errors

  • 400 invalid_request when brand_colour does not look like #0F5E59

Make an owner dashboard link

POST/v1/businesses/{business}/dashboard-links

Makes a sign-in link to the owner dashboard for one business, to send to its owner. The link works once and expires 15 minutes after it is made; signing in lasts 7 days.

Path

businessrequiredThe business's id.

Body

owner_namestringThe owner's name, shown on the dashboard and on approvals they make there.
langstringen or ar. Defaults to en.

Example

{
  "owner_name": "Hamad Al-Marri",
  "lang": "ar"
}

Returns

201 with url (https://app.basepipe.io/dashboard/sign-in?token=...) and expires_at (UTC time, 15 minutes from now).

Errors

  • 400 invalid_request when the body is not a JSON object or lang is not en or ar
  • 404 not_found when the business is not yours or belongs to the other mode

Accountants

List your accountants

GET/v1/reviewers

Lists your accountants by name, each with the ids of the businesses they have been given. Your own admins and BasePipe staff are not included.

Returns

200 with data: an array of accountants, each with id, name, email, is_active and businesses (an array of business ids).

Add an accountant

POST/v1/reviewers

Adds an outside accountant who can review the books of the businesses you give them, on the accountant screen. Accountants belong to your partner account, not to a mode.

Body

namestringrequiredThe accountant's name.
emailstringThe accountant's email address.

Example

{
  "name": "Fatima Al-Sulaiti",
  "email": "fatima@doha-audit.qa"
}

Returns

201 with id, name, email, is_active and businesses (an empty array).

Errors

  • 400 invalid_request when name is missing
  • 403 accountant_screen_off when the accountant screen is switched off for your partner account (switch it on in the admin screen, under Accountants)

Give an accountant a business

POST/v1/reviewers/{reviewer}/businesses

Lets an accountant see and review one of your businesses. Giving the same business twice changes nothing. A test key can only give practice businesses.

Path

reviewerrequiredThe accountant's id.

Body

business_idstringrequiredThe id of the business to give them.

Example

{
  "business_id": "01936f2b-1d0a-7c55-8e21-3f4a9b6c7d80"
}

Returns

201 with reviewer_id and business_id.

Errors

  • 400 invalid_request when business_id is not an id
  • 404 not_found when the accountant is not yours, or the business is not yours or belongs to the other mode

Take a business from an accountant

DELETE/v1/reviewers/{reviewer}/businesses/{business}

Stops an accountant seeing one business. It succeeds even if they did not have it.

Path

reviewerrequiredThe accountant's id.
businessrequiredThe business's id.

Returns

200 with reviewer_id, business_id and removed: true.

Errors

  • 400 invalid_request when the business id is not in the right format
  • 404 not_found when the accountant is not yours

Make an accountant sign-in link

POST/v1/reviewers/{reviewer}/sign-in-links

Makes a sign-in link to send to an accountant. The link works once and expires 15 minutes after it is made; it signs them in to the accountant screen for 12 hours, covering only the businesses they have been given. It does not work for an accountant who has been switched off.

Path

reviewerrequiredThe accountant's id.

Body

langstringen or ar, the language the screen opens in. Defaults to en.

Example

{
  "lang": "ar"
}

Returns

201 with url (https://app.basepipe.io/review/sign-in?token=...) and expires_at (UTC time, 15 minutes from now).

Errors

  • 400 invalid_request when lang is not en or ar
  • 403 accountant_screen_off when the accountant screen is switched off for your partner account
  • 404 not_found when the accountant is not yours

Partner admins

Add a partner admin

POST/v1/admins

Adds an admin for your partner admin screen and makes their first sign-in link. The link works once and expires 15 minutes after it is made; signing in lasts 12 hours. Admins can then invite other admins from the screen itself.

Body

namestringrequiredThe admin's name.
emailstringThe admin's email address.

Example

{
  "name": "Noor Al-Mannai",
  "email": "noor@souqpay.qa"
}

Returns

201 with id and url (https://app.basepipe.io/admin/sign-in?token=..., valid for 15 minutes).

Errors

  • 400 invalid_request when name is missing

Sign-ups

Get your sign-up link

GET/v1/signup-page

Returns your sign-up link for the key's mode, where business owners sign up for your product in your brand. A test key gives the practice link, whose businesses are practice ones. The link is made the first time you ask.

Returns

200 with url (https://app.basepipe.io/start/<code>), enabled, livemode.

Switch your sign-up link on or off

POST/v1/signup-page

Opens or closes your sign-up link for the key's mode. While it is off, owners who open the link are told it is not open. The link itself stays the same.

Body

enabledbooleanrequiredtrue to accept sign-ups, false to stop them.

Example

{
  "enabled": false
}

Returns

200 with url, enabled, livemode.

Errors

  • 400 invalid_request: the body is not a JSON object, or enabled is not true or false

List sign-ups

GET/v1/signups

Lists the latest 100 sign-ups through your link in the key's mode, newest first, including ones not finished. Use it to see where owners stop or get stuck.

Returns

200 with data: sign-ups with id, step (the page reached: language, you, whatsapp, business, about, money, opening, invoices, ready), name, business, phone, problem (number_taken when the WhatsApp number already has a business with you, otherwise null), business_id (set once finished), started_at, whatsapp_at (when the number was confirmed), finished_at.

Plans and billing

Get your monthly billing statement

GET/v1/billing/statement

Shows, for one month, what you collected from your businesses, BasePipe's revenue share of it, and the charge for WhatsApp messages and receipts read above each business's monthly fair-use allowance. With a test key it covers your practice businesses only.

Query

monthstringThe month, YYYY-MM. Defaults to the current month (UTC).

Returns

200 with month, currency, businesses, on_trial, active, overdue (overdue and cancelled), collected, share_percent, share, usage_charge, owed, and lines: one per business with business_id, business, plan, state, collected, wa_messages, receipts, wa_over, receipts_over and usage_charge. share_percent and share are null until a revenue share is agreed. Amounts are in the smallest currency unit.

Errors

  • 400 invalid_request when month does not look like 2026-11

Get a business's subscription

GET/v1/businesses/{business}/subscription

Shows which plan a business is on, where it stands and this month's usage against its limits. A business whose trial or paid period has run out, or whose plan you cancelled, is read-only: the owner can still see and print everything, but nothing new can be recorded.

Path

businessrequiredThe business's id.

Returns

200 with state (none, trial, active, overdue or cancelled), read_only, plan ({id, name} or null), trial_ends_on, paid_until, and usage: {wa_messages, wa_limit, receipts, receipt_limit} (a null limit means no limit).

Errors

  • 404 not_found when the business is not yours or belongs to the other mode

Put a business on a plan

PUT/v1/businesses/{business}/subscription

Puts a business on one of your plans. A business new to plans starts the plan's free trial today; a business already on a plan just switches plan, and a cancelled one is started again. You can also move the trial's end date to give more time or end it early.

Path

businessrequiredThe business's id.

Body

plan_idstringrequiredThe id of one of your active plans in the same mode as the business.
trial_ends_onstringLast day of the free trial, YYYY-MM-DD.

Example

{
  "plan_id": "01936f2a-7c4e-7b10-9a3d-5e8f1c2b4a60",
  "trial_ends_on": "2026-12-31"
}

Returns

200 with the subscription: state, read_only, plan, trial_ends_on, paid_until and usage.

Errors

  • 400 invalid_request when plan_id is not an id or trial_ends_on is not a date
  • 404 not_found when the business is not yours or belongs to the other mode
  • 422 rejected when the plan is not one of yours in this mode, or the plan is switched off

Cancel a business's plan

POST/v1/businesses/{business}/subscription/cancel

Stops a business's plan. The business becomes read-only straight away, until you put it on a plan again or record a payment.

Path

businessrequiredThe business's id.

Returns

200 with the subscription, now with state cancelled and read_only true.

Errors

  • 404 not_found when the business is not yours or belongs to the other mode
  • 422 rejected when the business has no running plan

Record a subscription payment

POST/v1/businesses/{business}/subscription/payments

Records that a business paid you for its plan, and until when that payment covers it. The business is paid up to the latest covers_until you have recorded, and a cancelled plan starts running again. The amount is in the plan's currency and counts towards that month's billing statement.

Path

businessrequiredThe business's id.

Body

amountintegerrequiredWhat was paid, in the smallest currency unit, above zero (99 QAR is 9900).
covers_untilstringrequiredLast day the payment covers, YYYY-MM-DD. Not before paid_on.
paid_onstringWhen it was paid, YYYY-MM-DD. Defaults to today (UTC).
referencestringYour own reference, such as a receipt or transfer number.
recorded_bystringrequiredWho recorded the payment.

Example

{
  "amount": 9900,
  "paid_on": "2026-11-16",
  "covers_until": "2026-12-15",
  "reference": "QNB-TRF-448812",
  "recorded_by": "Mariam Al-Kuwari"
}

Returns

201 with the subscription: state, read_only, plan, trial_ends_on, paid_until and usage.

Errors

  • 400 invalid_request when amount is not a whole number above zero, paid_on or covers_until is not a date, or recorded_by is missing
  • 404 not_found when the business is not yours or belongs to the other mode
  • 422 rejected when the business is not on a plan yet, or covers_until is before paid_on

List your plans

GET/v1/plans

Lists the plans you sell to your businesses, active plans first and then by price. A test key sees only its practice plans; a live key sees only live plans.

Returns

200 with data: an array of plans, each with id, name, name_ar, price, currency, period, trial_days, wa_limit, receipt_limit, is_default, is_active, ai_bookkeeper, ai_auto_limit and created_at.

Create a plan

POST/v1/plans

Creates a plan with your own price, billing period, free trial and optional monthly limits. BasePipe never charges your businesses; you collect the money and record payments. Marking a plan as the default makes new businesses start on it, and takes the default away from your other plans.

Body

namestringrequiredThe plan's name. Must be unique among your active plans.
name_arstringThe plan's name in Arabic.
priceintegerrequiredThe price in the smallest currency unit, zero or more (99 QAR is 9900).
currencystringThree-letter currency code. Defaults to QAR.
periodstringmonth or year. Defaults to month.
trial_daysintegerLength of the free trial, 0 to 90 days. Defaults to 14.
wa_limitintegerMost WhatsApp messages a month, 1 to 1000000. Leave out for no limit. During a trial BasePipe's own trial limit (150) also applies.
receipt_limitintegerMost receipts read a month, 1 to 1000000. Leave out for no limit. During a trial BasePipe's own trial limit (30) also applies.
is_defaultbooleanNew businesses start on this plan and its trial. Defaults to false.
ai_bookkeeperbooleanWhether the plan includes the AI bookkeeper. Defaults to false.
ai_auto_limitintegerThe largest receipt or bill the AI bookkeeper may record on its own, in the smallest currency unit. Defaults to 100000 (1,000 QAR).

Example

{
  "name": "Dukkan Monthly",
  "name_ar": "دكان شهري",
  "price": 9900,
  "currency": "QAR",
  "period": "month",
  "trial_days": 14,
  "wa_limit": 400,
  "receipt_limit": 100,
  "is_default": true,
  "ai_bookkeeper": true,
  "ai_auto_limit": 50000
}

Returns

201 with the new plan: id, name, name_ar, price, currency, period, trial_days, wa_limit, receipt_limit, is_default, is_active, ai_bookkeeper, ai_auto_limit, created_at.

Errors

  • 400 invalid_request when name is missing, price is not a whole number of zero or more, period is not month or year, currency is not three letters, trial_days is outside 0 to 90, wa_limit or receipt_limit is outside 1 to 1000000, or ai_auto_limit is not a whole number of zero or more
  • 409 conflict when you already have an active plan with that name

Replace a plan

PUT/v1/plans/{plan}

Replaces every setting of a plan, so send all the fields you would send to create it; anything left out goes back to its default. Send is_active false to switch a plan off: businesses already on it keep it, but no business can be newly put on it, and a switched-off plan is never the default.

Path

planrequiredThe plan's id.

Body

namestringrequiredThe plan's name.
name_arstringThe plan's name in Arabic.
priceintegerrequiredThe price in the smallest currency unit (99 QAR is 9900).
currencystringThree-letter currency code. Defaults to QAR.
periodstringmonth or year. Defaults to month.
trial_daysinteger0 to 90. Defaults to 14.
wa_limitintegerWhatsApp messages a month, 1 to 1000000, or leave out for no limit.
receipt_limitintegerReceipts read a month, 1 to 1000000, or leave out for no limit.
is_defaultbooleanMake this the plan new businesses start on. Ignored when is_active is false.
is_activebooleanfalse switches the plan off. Defaults to true.
ai_bookkeeperbooleanWhether the plan includes the AI bookkeeper. Defaults to false.
ai_auto_limitintegerThe largest receipt or bill the AI bookkeeper may record on its own. Defaults to 100000.

Example

{
  "name": "Dukkan Monthly",
  "name_ar": "دكان شهري",
  "price": 12900,
  "currency": "QAR",
  "period": "month",
  "trial_days": 30,
  "wa_limit": 500,
  "receipt_limit": 150,
  "is_default": true,
  "is_active": true,
  "ai_bookkeeper": true,
  "ai_auto_limit": 75000
}

Returns

200 with the updated plan, in the same shape as when it was created.

Errors

  • 400 invalid_request when a field fails the same checks as when creating a plan
  • 404 not_found when the plan is not one of yours in this mode
  • 409 conflict when another active plan already has that name

WhatsApp

List a business's WhatsApp owners

GET/v1/businesses/{business}/whatsapp-owners

Lists the phones linked to a business, oldest first.

Path

businessrequiredThe business's id.

Returns

200 with data: an array of owners, each with id, phone, name, lang and is_active.

Errors

  • 404 not_found when the business is not yours or belongs to the other mode

Link an owner's WhatsApp phone

POST/v1/businesses/{business}/whatsapp-owners

Links an owner's phone to a business, so messages from that phone to your WhatsApp number are kept in that business's books. A phone can belong to only one of your businesses.

Path

businessrequiredThe business's id.

Body

phonestringrequiredThe owner's full international number, like +97455500000. Spaces are removed.
namestringThe owner's name.
langstringen or ar, the language replies are sent in. Defaults to ar.

Example

{
  "phone": "+97455512345",
  "name": "Hamad Al-Marri",
  "lang": "ar"
}

Returns

201 with id, phone, name, lang and is_active.

Errors

  • 400 invalid_request when phone is missing or not a full international number, or lang is not en or ar
  • 404 not_found when the business is not yours or belongs to the other mode
  • 409 conflict when that phone is already linked to one of your businesses

List your WhatsApp numbers

GET/v1/whatsapp-numbers

Lists your WhatsApp numbers, oldest first.

Returns

200 with data: an array of numbers, each with id, number, label and is_active.

Add a WhatsApp number

POST/v1/whatsapp-numbers

Adds a WhatsApp number of yours, set up on Twilio, that owners message to keep their books. Messages to the number tell BasePipe which partner they are for. Numbers belong to your partner account, not to a mode.

Body

numberstringrequiredThe full international number, like +97444001234. Spaces are removed.
labelstringA name for the number, for your own use.
twilio_account_sidstringThe Twilio account the number is on.

Example

{
  "number": "+97444001234",
  "label": "SouqPay Books main line",
  "twilio_account_sid": "AC0123456789abcdef0123456789abcdef"
}

Returns

201 with id, number, label and is_active.

Errors

  • 400 invalid_request when number is missing or is not a full international number
  • 409 conflict when that number is already set up

List your WhatsApp templates

GET/v1/whatsapp-templates

Lists the WhatsApp templates you have set, by kind and language.

Returns

200 with data: an array of templates, each with kind, lang and content_sid.

Set a WhatsApp template

POST/v1/whatsapp-templates

Sets the approved Twilio message template used for one kind of message in one language, so it can be sent outside WhatsApp's 24-hour reply window. For now only the evening sales check-in can use a template. Setting the same kind and language again replaces the template.

Body

kindstringrequiredThe kind of message. Must be sales_checkin.
langstringen or ar. Defaults to ar.
content_sidstringrequiredThe Twilio content id: HX followed by 32 lowercase letters and numbers.

Example

{
  "kind": "sales_checkin",
  "lang": "ar",
  "content_sid": "HX4f2a9c1e7b3d5a8f0e6c2b9d1a7f3e5c"
}

Returns

201 with kind, lang and content_sid.

Errors

  • 400 invalid_request when kind is not sales_checkin, lang is not en or ar, or content_sid is missing or not a Twilio content id

Background jobs

List background jobs for a business

GET/v1/businesses/{business}/jobs

Lists the background work run for a business, newest first, such as monthly wear and tear, applying bank rules, invoice reminders, the weekly summary, recurring documents and the daily sales question. Use it when something you expected didn't happen.

Path

businessThe business id.

Query

limitintegerHow many to return, 1 to 200. Defaults to 50.

Returns

200 with data: jobs with id, kind (e.g. wear_and_tear, apply_rules, invoice_reminders, weekly_summary, recurring, schedules, sales_checkin, bookkeeper), status (queued, running, done or failed), attempts, last_error, result, run_at, created_at, finished_at.

Errors

  • 404 not_found: the business is not yours or is in the other mode

List a business's messages

GET/v1/businesses/{business}/outbox

Lists the messages prepared for one business's owner, newest first. Without status it lists all of them, whatever their status.

Path

businessThe business id.

Query

statusstringpending, sent or cancelled. Leave out for all.
limitintegerHow many to return, 1 to 200. Defaults to 50.

Returns

200 with data: messages with id, business_id, kind, audience, body_en, body_ar, data, status, created_at, sent_at, sent_via.

Errors

  • 400 invalid_request: status is not pending, sent or cancelled
  • 404 not_found: the business is not yours or is in the other mode

List messages waiting to be sent

GET/v1/outbox

Lists messages BasePipe has prepared for owners across all your businesses in the key's mode, oldest first: invoice reminders, the weekly summary and the evening daily sales question. Deliver each one yourself, for example on WhatsApp, then mark it sent.

Query

statusstringpending, sent or cancelled. Defaults to pending.
limitintegerHow many to return, 1 to 200. Defaults to 50.

Returns

200 with data: messages with id, business_id, kind (e.g. invoice_reminder, weekly_summary, sales_checkin), audience, body_en, body_ar, data (details such as the date), status, created_at, sent_at, sent_via.

Errors

  • 400 invalid_request: status is not pending, sent or cancelled

Mark a message as sent

POST/v1/outbox/{message}/sent

Tells BasePipe you have delivered a waiting message, so it is not listed as pending again. Only pending messages can be marked.

Path

messageThe message id from the outbox.

Body

viastringrequiredHow it was delivered, e.g. whatsapp or sms.

Example

{
  "via": "whatsapp"
}

Returns

200 with the message, now with status sent, sent_at and sent_via.

Errors

  • 400 invalid_request: the body is not a JSON object, or via is missing
  • 404 not_found: the id is not a valid id, or no pending message with this id belongs to your partner account
  • 404 not_found: the message belongs to the other mode (a test key marking a live message, or the other way round).