TallyPip API

The API lives at https://tallypip.com/api/v1. It takes and gives JSON over HTTPS. Building an app? Make a free sandbox business with sample books to try it against. For a real business, ask its owner or an admin to make you a key in TallyPip under Settings › Connected apps, then check it works:

curl https://tallypip.com/api/v1/me \
  -H "Authorization: Bearer tpk_your_key"

It answers with the business, the key and the person it acts for:

{
  "object": "connection",
  "business": { "id": "…", "name": "Oak Street Dental", "country": "US", "currency": "USD" },
  "key": { "id": "…", "name": "Zapier", "starts_with": "tpk_Ab12Cd", "access": "write" },
  "acting_as": { "name": "Jordan Lee", "role": "owner" }
}

• A key belongs to one business and acts as the person who made it, with their role there (Owner, Admin, Accountant or Standard). If they leave the team, the key stops working.
• Read only keys can only read. Read and change keys can also add things.
• Send it in the Authorization header as Bearer tpk_…. Keep it on a server: the API doesn't answer browsers on other sites, so a key never needs to be in a web page or an app people download.
• The key is shown once when it's made. TallyPip keeps only a fingerprint of it, so a lost key can't be shown again: revoke it and make a new one.
• A locked business (its trial or plan ended) or a closed one can still be read, not added to.
• Building an app many businesses will use? Skip the copying: let them connect it in one click with Connect to TallyPip (OAuth 2.0). Its access tokens (tpo_…) work everywhere a key does.

• Money is whole cents in the business's currency: "total_cents": 12550 is 125.50. Fields that are money end in _cents.
• Dates are YYYY-MM-DD; times are ISO 8601 in UTC (created_at).
• Tax rates are percentages (8.875); quantities are numbers with up to 3 decimals (2.5).
• Ids are UUIDs. Every object says what it is: "object": "invoice".
• An invoice's status is draft (not in the books yet), sent (in the books and owing), paid or void. A bill's is open, paid or void.
• Names you don't send are left out or take their usual default; names the endpoint doesn't know are refused, so a typo is never silently ignored.

All paths are under https://tallypip.com/api/v1.

Things are added through the API, not changed or deleted: corrections are made in TallyPip, where the books keep their history.

For example, an invoice for two cleanings at 50.00 each, in the books straight away:

curl https://tallypip.com/api/v1/invoices \
  -H "Authorization: Bearer tpk_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1d2c9e-order-1042" \
  -d '{
    "customer_id": "3f6c1e2a-8b4d-4c1e-9a7b-2d5e6f708192",
    "status": "sent",
    "lines": [{ "description": "Cleaning", "quantity": 2, "rate_cents": 5000, "taxable": true }]
  }'

The answer is 201 with the invoice, its number, due date, tax and lines. What each kind of thing takes, and what comes back, is on its page in the API reference:

• Create a customer
• Create a vendor
• Create a product or service
• Create a invoice
• Create a project
• Create a class
• Create a location
• Create a payment
• Create a bill
• Create a expense
• Add a webhook endpoint

Lists come newest first, 25 at a time (?limit= up to 100). When has_more is true, ask for the next page with ?starting_after= and the last id you got:

GET /invoices?limit=50&status=sent
{ "object": "list", "url": "/api/v1/invoices", "has_more": true, "data": [ … ] }

GET /invoices?limit=50&status=sent&starting_after=<last id>

To pick up new invoices, payments or customers, ask for the first page now and then and keep the ones you haven't seen.

Networks drop. To make sure a retried request can't make an invoice or payment twice, send an Idempotency-Key header with each change: any text up to 255 characters, new for each change (a UUID, or your own order number).

• Sent again within 24 hours with the same key and body, the request isn't repeated: you get the first answer, with Idempotent-Replayed: true.
• The same key with a different body is refused with 409.
• A refused request (400) changes nothing and isn't remembered, so fix it and send it again with the same key.

Instead of asking for new invoices every few minutes, an app can be told the moment something happens. A business adds an endpoint in Settings › Connected apps › Webhooks, or your app subscribes with its key:

curl https://tallypip.com/api/v1/webhooks \
  -H "Authorization: Bearer tpk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://hooks.example.com/tallypip", "events": ["invoice.paid", "payment.received"] }'

The answer includes the endpoint's secret (whsec_…), once: keep it to check messages. Endpoints an app adds stop when its key is revoked; unsubscribe with DELETE /webhooks/{id}.

The events

Things brought over from another app when a business switches (past transactions, starting balances) don't send events, and neither does writing off an invoice as a bad debt (no payment.received or invoice.paid: no money came in). Send a test in Settings sends a ping.

What arrives

A POST with a JSON body. data.object is the thing as the API shows it when the message is first sent (the same every time it's retried):

POST https://hooks.example.com/tallypip
TallyPip-Signature: t=1791288000,v1=5d41402abc4b2a76b9719d911017c592...
TallyPip-Event-Id: 0b48…
TallyPip-Event-Type: invoice.paid

{
  "id": "0b48…",
  "object": "event",
  "type": "invoice.paid",
  "created_at": "2026-10-06T14:30:00.000Z",
  "business_id": "…",
  "data": { "object": { "object": "invoice", "id": "…", "number": "INV-1042", "status": "paid", … } }
}

Check it came from TallyPip

1. From TallyPip-Signature, take t (the time it was signed) and v1.
2. Work out HMAC-SHA256 of t, a dot and the raw body (exactly as received), with your whsec_… secret as the key, in hex.
3. It must equal v1 (compare in constant time), and t must be within 5 minutes of now, so an old message can't be replayed.

const [t, v1] = header.split(",").map((p) => p.split("=")[1]);
const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1)) && Math.abs(Date.now() / 1000 - Number(t)) < 300;

Answering, and retries

• Answer with any 2xx within 10 seconds (do slow work afterwards). Anything else, a redirect or no answer is tried again: after 1 minute, 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours and a day (8 tries in all).
• A message can arrive more than once, and not always in order: use the event id to skip ones you've seen, and created_at to order them.
• An endpoint that hasn't answered properly for 48 hours is turned off and the business is told. They can turn it back on in Settings, where every message and its answer is listed.

Errors come with an HTTP status and a body your app can show people:

{ "error": { "type": "invalid_request", "message": "Check the quantity on item 2.", "field": "lines" } }

Every answer has an X-Request-Id; mention it when you write to us. Anything other than a success changes nothing: a request is all or nothing.

• /api/v1 stays as it is. We may add endpoints and fields (so ignore names you don't know), but we won't remove or rename any without a new version and plenty of notice.
• Questions: support@tallypip.com. Found a security problem? Please tell us there first (put “Security” in the subject), before anyone else.
• Using the API means following our Terms and keeping the business's data private, as our Privacy Policy describes.