Diwaan Connect API

Build on the record every trading business runs on.

One REST API for sales, stock, customers, suppliers, payments and the books. Create a sale and Diwaan moves the stock and posts the entries, exactly as the till does.

Get API keys Partner with us

Coming Coming

curl https://api.diwaan.app/v1/sales \
  -H "Authorization: Bearer dk_test_4f9a2c81" \
  -H "Diwaan-Version: 2026-10-01" \
  -d branch="br_main_store" \
  -d "lines[0][item]"="RC-25" \
  -d "lines[0][quantity]"=2 \
  -d "payments[0][method]"="cash" \
  -d "payments[0][amount]"=76.00

import Diwaan from "@diwaan/node";

const diwaan = new Diwaan(process.env.DIWAAN_KEY);

const sale = await diwaan.sales.create({
  branch: "br_main_store",
  lines: [{ item: "RC-25", quantity: 2 }],
  payments: [{ method: "cash", amount: 76.00 }],
});

// The sale has already moved stock and posted to the books
console.log(sale.journal_entry.id); // "je_30419"

import diwaan

client = diwaan.Client(api_key="dk_test_4f9a2c81")

sale = client.sales.create(
    branch="br_main_store",
    lines=[{"item": "RC-25", "quantity": 2}],
    payments=[{"method": "cash", "amount": 76.00}],
)

# The sale has already moved stock and posted to the books
print(sale.journal_entry.id)  # "je_30419"

Quickstart

First sale through the API in five minutes.

Open a sandbox Coming

Create a key Coming

In Settings, then Connect, create a test key. Give it only the access your app needs.

Make a request

Create a sale. The response includes the stock movements and the journal entry it posted.

Every write returns its record

A sale created by the API is the same as a sale at the till. The response shows exactly what it did to stock and to the books, so your system and Diwaan never disagree.

Amounts are decimal strings or numbers with two places. Currency follows the business unless you set it.

{
  "id": "sale_10484",
  "branch": "br_main_store",
  "total": 76.00,
  "status": "paid",
  "stock_movements": [
    { "item": "RC-25", "quantity": -2, "location": "Main Store" }
  ],
  "journal_entry": {
    "id": "je_30419",
    "lines": [
      { "account": "Cash, Main Store", "debit": 76.00 },
      { "account": "Sales", "credit": 76.00 },
      { "account": "Cost of goods sold", "debit": 62.40 },
      { "account": "Stock", "credit": 62.40 }
    ]
  }
}

Reference

Resources

Base address https://api.diwaan.app/v1. JSON in, JSON out. Versioned by date in the Diwaan-Version header. Coming

Resource	What it holds	Methods
/v1/sales	Sales and receipts from any till or channel	GETPOST
/v1/invoices	Invoices, quotes and credit notes Coming	GETPOSTPATCH
/v1/items	Items, prices, barcodes and units	GETPOSTPATCH
/v1/stock-movements	Every change in quantity, by branch	GET
/v1/transfers	Stock moved between branches	GETPOST
/v1/customers	Customers, credit limits and balances	GETPOSTPATCH
/v1/suppliers	Suppliers and their bills	GETPOSTPATCH
/v1/payments	Money received and paid	GETPOST
/v1/journal-entries	The books, line by line	GETPOST
/v1/reports	Trial balance, profit and loss, money owed	GET

Webhooks

Know the moment it happens.

Subscribe to events and Diwaan sends a signed request to your address. Failed deliveries retry for 3 days.

// Verify every webhook with your signing secret
const event = diwaan.webhooks.verify(body, headers["diwaan-signature"], secret);

if (event.type === "payment.received") {
  markOrderPaid(event.data.invoice, event.data.amount);
}

Event	When it is sent
sale.created	A sale was completed at a till or by the API
invoice.sent	An invoice was sent to a customer
payment.received	Money came in against an invoice or sale
stock.below_minimum	An item fell below its minimum at a branch
transfer.received	A branch checked in a stock transfer
bill.approved	A supplier bill was approved for payment
day.closed	A till closed the day, with counted and expected cash
period.locked	An accountant locked a period

Access

Keys, apps and limits.

API keys for your own business Coming

Create keys in Settings, then Connect. Each key has its own permissions and can be revoked at once. Test keys start with dk_test_.

OAuth for partner apps Coming

Building for many Diwaan businesses? Register as an integration partner and let each business connect your app with OAuth.

600requests per minute, per key

3 daysof webhook retries

12 monthsnotice before a version is retired Coming

Official libraries Coming

JavaScriptnpm i @diwaan/node

Pythonpip install diwaan

PHPcomposer require diwaan/diwaan

Start building today.

Every developer account includes a sandbox business with a year of sample data. Coming

Get API keys Read the help centre