TallyPip
Start free

API reference

Bill

Something the business owes a vendor, to pay later (Accounts Payable).

The bill object

object string
Always "bill".
id id
The bill's id (a UUID). Use it to fetch it, or to refer to it from other things.
vendor_id id
Who it's from.
number string or null
The vendor's bill number.
status string
open, paid or void.
bill_date date
The bill's date.
due_date date
When it's due.
terms string
Payment terms.
currency string
Its currency: the business's (USD or CAD), or the customer's or vendor's when they're in another currency (Multicurrency, like EUR). All its _cents amounts are in it.
exchange_rate string or null
In another currency: what 1 unit of it was worth in the business's currency, as a decimal ("0.73215"). Null otherwise.
total_cents integer
The total.
paid_cents integer
Paid so far.
balance_cents integer
Still owing.
memo string or null
Memo.
location_id id or null
Its location (Locations), if any.
created_at timestamp
When it was added, in UTC.
lines list
Only when fetching one bill. Each line: id, account_id (its category), description, amount_cents, tax_cents (GST/HST paid, Canada), product_id, quantity, rate_cents (item lines), project_id (the project it's a cost of, or null), class_id (its class, or null).

Example

{
  "object": "bill",
  "id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708106",
  "vendor_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708102",
  "number": "H-5531",
  "status": "open",
  "bill_date": "2026-10-06",
  "due_date": "2026-10-21",
  "terms": "net_15",
  "currency": "USD",
  "exchange_rate": null,
  "total_cents": 8950,
  "paid_cents": 0,
  "balance_cents": 8950,
  "memo": null,
  "location_id": null,
  "created_at": "2026-10-06T14:30:00.000Z",
  "lines": [
    {
      "id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708160",
      "account_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708130",
      "description": "Gloves and masks",
      "amount_cents": 8950,
      "tax_cents": 0,
      "product_id": null,
      "quantity": null,
      "rate_cents": null,
      "project_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708108",
      "class_id": null
    }
  ]
}

List bills

GET /api/v1/bills

Bills, newest first (without their lines).

Key: any (Read only works).

Query

limit integer
How many, 1 to 100 (default 25).
starting_after id
The last id of the page before, for the next page (when has_more is true).
filters
vendor_id, status (open, paid, void)

Newest first. Answers a list: { object: "list", url, has_more, data }.

Request

curl https://tallypip.com/api/v1/bills?limit=3 \
  -H "Authorization: Bearer tpk_your_key"

Answer: 200

{
  "object": "list",
  "url": "/api/v1/bills",
  "has_more": false,
  "data": [
    {
      "object": "bill",
      "id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708106",
      "vendor_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708102",
      "number": "H-5531",
      "status": "open",
      "bill_date": "2026-10-06",
      "due_date": "2026-10-21",
      "terms": "net_15",
      "currency": "USD",
      "exchange_rate": null,
      "total_cents": 8950,
      "paid_cents": 0,
      "balance_cents": 8950,
      "memo": null,
      "location_id": null,
      "created_at": "2026-10-06T14:30:00.000Z",
      "lines": [
        {
          "id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708160",
          "account_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708130",
          "description": "Gloves and masks",
          "amount_cents": 8950,
          "tax_cents": 0,
          "product_id": null,
          "quantity": null,
          "rate_cents": null,
          "project_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708108",
          "class_id": null
        }
      ]
    }
  ]
}

Try it

With your own key (Settings › Connected apps). It stays in this page only, and reading can't change anything.

Create a bill

POST /api/v1/bills

Enter a bill to pay later.

Key: Read and change.

Body (JSON)

vendor_id id
Required.
lines list
Category lines: account_id (an expense or other category account), amount_cents, description, tax_cents (GST/HST paid, Canada), project_id (the project it's a cost of), class_id.
items list
Item lines: product_id, quantity, rate_cents (cost for 1), description, tax_cents, project_id, class_id. At least one line or item.
location_id id
Optional. An active location from /locations.
bill_date, terms, due_date, number, memo …
bill_date defaults to today; terms to the vendor's, else the business's.

Answers 201 with the new bill. Refused with 400 and the reason (nothing is saved); send an Idempotency-Key so a retry can't make it twice.

Request

curl https://tallypip.com/api/v1/bills \
  -H "Authorization: Bearer tpk_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <a new id for each change>" \
  -d '{
    "vendor_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708102",
    "number": "H-5531",
    "bill_date": "2026-10-06",
    "lines": [
      {
        "account_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708130",
        "amount_cents": 8950,
        "description": "Gloves and masks",
        "project_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708108"
      }
    ]
  }'

Answer: 201

{
  "object": "bill",
  "id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708106",
  "vendor_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708102",
  "number": "H-5531",
  "status": "open",
  "bill_date": "2026-10-06",
  "due_date": "2026-10-21",
  "terms": "net_15",
  "currency": "USD",
  "exchange_rate": null,
  "total_cents": 8950,
  "paid_cents": 0,
  "balance_cents": 8950,
  "memo": null,
  "location_id": null,
  "created_at": "2026-10-06T14:30:00.000Z",
  "lines": [
    {
      "id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708160",
      "account_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708130",
      "description": "Gloves and masks",
      "amount_cents": 8950,
      "tax_cents": 0,
      "product_id": null,
      "quantity": null,
      "rate_cents": null,
      "project_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708108",
      "class_id": null
    }
  ]
}

Retrieve a bill

GET /api/v1/bills/{id}

One bill with its lines.

Key: any (Read only works).

Request

curl https://tallypip.com/api/v1/bills/3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708106 \
  -H "Authorization: Bearer tpk_your_key"

Answer: 200

{
  "object": "bill",
  "id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708106",
  "vendor_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708102",
  "number": "H-5531",
  "status": "open",
  "bill_date": "2026-10-06",
  "due_date": "2026-10-21",
  "terms": "net_15",
  "currency": "USD",
  "exchange_rate": null,
  "total_cents": 8950,
  "paid_cents": 0,
  "balance_cents": 8950,
  "memo": null,
  "location_id": null,
  "created_at": "2026-10-06T14:30:00.000Z",
  "lines": [
    {
      "id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708160",
      "account_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708130",
      "description": "Gloves and masks",
      "amount_cents": 8950,
      "tax_cents": 0,
      "product_id": null,
      "quantity": null,
      "rate_cents": null,
      "project_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708108",
      "class_id": null
    }
  ]
}

Try it

With your own key (Settings › Connected apps). It stays in this page only, and reading can't change anything.