API overview

Base URL

http://localhost:4173/api/v1

v1 is the Balancely API. A new version comes only for a change that would break an existing integration. It would run beside v1.

Conventions

• Every operation is a resource.action key — sales_invoices.create, ledgers.search, vouchers.cancel — called at /api/v1/tally/{key}.

• Writes are POST with a JSON body. Reads are GET with query parameters; POST works for them too.

• Every field name, in and out, is snake_case. Dates are YYYY-MM-DD.

• A record says what it is in object, and a voucher's number is always number.

• Success is the HTTP status. There is no ok flag to check.

Response shape

One record, a list of records, or an error. Every one carries the request id.

HTTP/1.1 201 Created

{
  "data": {
    "object": "sales_invoice",
    "number": "INV-1042",
    "date": "2026-04-12",
    "customer": "Aurora Traders",
    "amount": 2950,
    "item_count": 1,
    "bill_reference_name": "INV-1042"
  },
  "meta": { "request_id": "req_8f2c…", "operation": "sales_invoices.create", "outcome": "created" }
}

meta.outcome says what a write did: created (status 201), updated, found — an existing record returned unchanged — or, for a cancel, cancelled and unchanged. meta.replayed is true when a retry was answered with the first result.

When TallyPrime saved the record but not every field as sent, data.warnings lists each one — { "code": "field_not_saved", "label": "PAN", "message": "…" }. The record is real either way, so a warning never fails the step. gst_assumed_local means GST was worked out as within your state because the party has no GSTIN or State in TallyPrime; set_by_tally means TallyPrime numbered the voucher itself. gst_uncertain means TallyPrime saved a sale or a note to a customer but lists it under Uncertain Transactions in its GSTR-1; the message names the likely reason and the fix.

Pagination

Search operations answer a page at a time. limit is 1 to 100 (default 50). When meta.has_more is true, send meta.next_cursor back as cursor for the next page; the last page has next_cursor: null.

http://localhost:4173/api/v1/tally/ledgers.search?search_text=traders&limit=50
http://localhost:4173/api/v1/tally/ledgers.search?search_text=traders&limit=50&cursor=eyJvIjo1MH0

A search reaches at most the first 1,000 matches. Add a filter to see past them.

Status codes

Tracing a request

Every response carries meta.request_id, also sent as the X-Request-Id header. Quote it when you report a problem. We can then find the exact request in our logs.

Endpoints