Purchase Vouchers

Returns Tally Purchase vouchers for approved expenses and inventory purchases. Both kinds of voucher appear in the same data array. They share vouchertypename: "Purchase" but use slightly different voucherid formats and vouchernumber prefixes so you can tell them apart.

Endpoint

Method	URL
GET	/tally/purchase

No query parameters. Returns every unrecorded purchase voucher in one response.

Filtering rules

• Pending and rejected source records are excluded.
• Already-recorded purchase vouchers are excluded.

There is no date range filter and no pagination.

Multi-supplier purchases

A single purchase that involves items from multiple suppliers produces one voucher per supplier. Recording one supplier's voucher leaves the other suppliers' vouchers untouched.

Response schema

The response envelope is { status, data, message } (see Overview). The data field is an array of purchase voucher objects.

Top-level fields

Field	Type	Description
voucherid	string	Stable unique ID for the voucher
vouchernumber	string	Display number. Single-supplier vouchers use the PR- prefix, multi-supplier vouchers use the PC- prefix
vouchertypename	string	Always "Purchase"
date	string	ISO 8601 timestamp
reference	string	Bill reference
reference_date	string	ISO 8601 timestamp, same as date
narration	string	Auto-generated description
address	string	Supplier address, or ""
vatregistrationtype	string	"Regular" if VAT is present, "Unregistered" otherwise
statename	string	Supplier region name, or ""
country	string	Always "Tanzania"
supplierledger	string	Supplier name
supplieralias	string	Always ""
mailingname	string	Supplier name
salestaxno	string	Supplier VAT registration number, or ""
PIN	string	Supplier tax ID, or ""
bills	Bill[]	Always exactly one entry. See Bill Object
ledgers	Ledger[]	One or more entries. See Ledger Object
_internalMetadata	string	Opaque base64 blob. Pass back to POST /tally/record to mark this voucher as recorded

Ledger object

PR- prefixed vouchers contain a single expense ledger plus an optional VAT ledger. PC- prefixed vouchers contain one ledger per item plus an optional VAT ledger.

Field	Type	Description
ledgername	string	Expense category or item name. The VAT ledger uses "VAT - OUTPUT 18%"
amount	number	Ledger amount
costcentes	CostCenter[]	Cost centers attached to this ledger. Truck name when applicable, otherwise []. The VAT ledger always has []

No counter-credit ledger

Purchase vouchers do not include a credit-side ledger for the supplier. The supplier is identified via the top-level supplierledger field and the bill reference. Tally constructs the credit posting from those during import.

Cost center object

Field	Type	Description
name	string	Cost center name
amount	number	Same as the parent ledger amount

Bill object

The top-level bills array always contains exactly one entry:

Field	Type	Description
name	string	Bill reference
amount	number	Total bill amount for this voucher

Example response

This example shows two vouchers in the same response. The first uses the PR- prefix, the second uses the PC- prefix.

{
  "status": "success",
  "data": [
    {
      "voucherid": "65f1a2b3c4d5e6f7a8b9c0e1",
      "vouchernumber": "PR-218",
      "vouchertypename": "Purchase",
      "date": "2026-03-28T08:00:00.000Z",
      "reference": "PR-PR-2026-03-018",
      "reference_date": "2026-03-28T08:00:00.000Z",
      "narration": "Purchase PR-PR-2026-03-018 - Workshop labour for T 827 EEX clutch overhaul",
      "address": "Industrial Area, Dar es Salaam",
      "vatregistrationtype": "Regular",
      "statename": "Dar es Salaam",
      "country": "Tanzania",
      "supplierledger": "Mwananchi Auto Workshop",
      "supplieralias": "",
      "mailingname": "Mwananchi Auto Workshop",
      "salestaxno": "40-009876-X",
      "PIN": "987-654-321",
      "bills": [
        { "name": "PR-PR-2026-03-018", "amount": 826000 }
      ],
      "ledgers": [
        {
          "ledgername": "Repairs & Maintenance",
          "amount": 700000,
          "costcentes": [
            { "name": "T 827 EEX", "amount": 700000 }
          ]
        },
        {
          "ledgername": "VAT - OUTPUT 18%",
          "amount": 126000,
          "costcentes": []
        }
      ],
      "_internalMetadata": "eyJ0IjoicHVyY2hhc2UiLCJzIjoicHIiLCJpZCI6IjY1ZjFhMmIzYzRkNWU2ZjdhOGI5YzBlMSJ9"
    },
    {
      "voucherid": "65f1a2b3c4d5e6f7a8b9c0f0-65f1a2b3c4d5e6f7a8b9c0f1",
      "vouchernumber": "PC-PROC-2026-005-acmesupplies",
      "vouchertypename": "Purchase",
      "date": "2026-04-02T10:30:00.000Z",
      "reference": "PC-PROC-2026-005-acmesupplies",
      "reference_date": "2026-04-02T10:30:00.000Z",
      "narration": "Procurement PROC-2026-005 for T 827 EEX",
      "address": "Plot 18, Kariakoo",
      "vatregistrationtype": "Regular",
      "statename": "Dar es Salaam",
      "country": "Tanzania",
      "supplierledger": "Acme Supplies",
      "supplieralias": "",
      "mailingname": "Acme Supplies",
      "salestaxno": "40-001234-X",
      "PIN": "123-456-789",
      "bills": [
        { "name": "PC-PROC-2026-005-acmesupplies", "amount": 472000 }
      ],
      "ledgers": [
        {
          "ledgername": "Brake Pads",
          "amount": 200000,
          "costcentes": [
            { "name": "T 827 EEX", "amount": 200000 }
          ]
        },
        {
          "ledgername": "Air Filter",
          "amount": 200000,
          "costcentes": [
            { "name": "T 827 EEX", "amount": 200000 }
          ]
        },
        {
          "ledgername": "VAT - OUTPUT 18%",
          "amount": 72000,
          "costcentes": []
        }
      ],
      "_internalMetadata": "eyJ0IjoicHVyY2hhc2UiLCJzIjoicHJvY3VyZW1lbnQiLCJpZCI6IjY1ZjFhMmIzYzRkNWU2ZjdhOGI5YzBmMCIsInN1cCI6IjY1ZjFhMmIzYzRkNWU2ZjdhOGI5YzBmMSJ9"
    }
  ],
  "message": "Purchase vouchers fetched successfully"
}

Example request

curl

curl -H "x-api-key: your-api-key-here" \
  https://api.example.com/tally/purchase

Node.js

const res = await fetch("https://api.example.com/tally/purchase", {
  headers: {
    "x-api-key": process.env.TALLY_API_KEY,
  },
});
const { data: vouchers } = await res.json();

Common mistakes

Treating PR and PC vouchers identically

Both kinds share vouchertypename: "Purchase", but they have different ledger structures. PR vouchers have a single expense ledger, PC vouchers have one ledger per item. Iterate the array, do not assume a fixed length.

Recording all of a multi-supplier purchase at once

A purchase that involves items from multiple suppliers produces multiple separate vouchers, each with its own _internalMetadata. Recording one supplier's voucher does not record the others.

Stripping the PR- or PC- prefix from the vouchernumber

Both prefixes are intentional and they are how Tally tells the two kinds apart inside a single ledger view. Keep them.

Related pages

• Overview
• Payment Vouchers
• Recording Vouchers