TallyPip
Start free

API reference

Expense

Money already spent from a bank, card or cash account (a purchase, a check).

The expense object

object string
Always "expense".
id id
The expense's id (a UUID). Use it to fetch it, or to refer to it from other things.
vendor_id id or null
Who was paid, if known.
date date
When.
paid_from_account_id id
The bank, card or cash account it came out of.
method string or null
How it was paid.
currency string
The business's currency: USD or CAD. All _cents amounts are in it.
total_cents integer
The total.
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 expense. Lines as on a bill.

Example

{
  "object": "expense",
  "id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708107",
  "vendor_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708102",
  "date": "2026-10-06",
  "paid_from_account_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708133",
  "method": "Card",
  "currency": "USD",
  "total_cents": 8950,
  "memo": null,
  "location_id": null,
  "created_at": "2026-10-06T14:30:00.000Z",
  "lines": [
    {
      "id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708170",
      "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": null,
      "class_id": null
    }
  ]
}

List expenses

GET /api/v1/expenses

Expenses (paid straight away), newest first.

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

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

Request

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

Answer: 200

{
  "object": "list",
  "url": "/api/v1/expenses",
  "has_more": false,
  "data": [
    {
      "object": "expense",
      "id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708107",
      "vendor_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708102",
      "date": "2026-10-06",
      "paid_from_account_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708133",
      "method": "Card",
      "currency": "USD",
      "total_cents": 8950,
      "memo": null,
      "location_id": null,
      "created_at": "2026-10-06T14:30:00.000Z",
      "lines": [
        {
          "id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708170",
          "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": null,
          "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 an expense

POST /api/v1/expenses

Record an expense paid from a bank, card or cash account.

Key: Read and change.

Body (JSON)

paid_from_account_id id
Required. A bank, card or cash account from /accounts.
lines, items list
As on a bill.
vendor_id, date, method, memo, location_id …
Optional. date defaults to today.

Answers 201 with the new expense. 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/expenses \
  -H "Authorization: Bearer tpk_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <a new id for each change>" \
  -d '{
    "paid_from_account_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708133",
    "vendor_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708102",
    "lines": [
      {
        "account_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708130",
        "amount_cents": 8950
      }
    ]
  }'

Answer: 201

{
  "object": "expense",
  "id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708107",
  "vendor_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708102",
  "date": "2026-10-06",
  "paid_from_account_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708133",
  "method": "Card",
  "currency": "USD",
  "total_cents": 8950,
  "memo": null,
  "location_id": null,
  "created_at": "2026-10-06T14:30:00.000Z",
  "lines": [
    {
      "id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708170",
      "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": null,
      "class_id": null
    }
  ]
}

Retrieve an expense

GET /api/v1/expenses/{id}

One expense with its lines.

Key: any (Read only works).

Request

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

Answer: 200

{
  "object": "expense",
  "id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708107",
  "vendor_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708102",
  "date": "2026-10-06",
  "paid_from_account_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708133",
  "method": "Card",
  "currency": "USD",
  "total_cents": 8950,
  "memo": null,
  "location_id": null,
  "created_at": "2026-10-06T14:30:00.000Z",
  "lines": [
    {
      "id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708170",
      "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": null,
      "class_id": null
    }
  ]
}

Try it

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