Track Invoice Status Over the API Without Logging In
· 5 min read
You sent 40 invoices this month and you do not want to open a dashboard 40 times to see which ones cleared. You want a script that tells you what changed since yesterday: who opened their invoice, who paid, and which one has been sitting on Sent for nine days with nobody looking at it.
That is a status-polling problem, and the lifecycle makes it a small one. Every invoice moves through four states: Draft, Sent, Viewed, Paid. Read the current state over the API, compare it to what you stored last time, and act on the difference. No webhooks required, no logging in. Here is how a real person wires that up.
Know the four states before you write any code
Each invoice carries a status field that only moves forward:
- Draft: created but not shared. No link is live yet.
- Sent: the private link exists and has gone to the recipient.
- Viewed: the recipient opened the link. This is the signal most people ignore, and it is the one that tells you a Net 30 invoice is actually in front of someone.
- Paid: payment is recorded, either by card through the sender's Stripe connection or because the sender marked a reported payment as received. Once an invoice is Paid, recipient edits stop.
Two things that are not statuses, and matter for your logic. There is no "approved" state. The recipient cannot approve an invoice for payment, so do not build a step that waits for one. And content edits create a new version (V1, V2) while a PO number or billing-address change is a tracked amendment on the current version, not a version bump. If you need the full breakdown, the six invoice statuses and what each one means covers the edge cases.
Poll the API and diff against what you stored
The pattern is boring on purpose. On a schedule (a cron job every hour is plenty for most billing), you pull the current state of your open invoices from the REST API and MCP server, compare it against the last state you saved, and emit an event for anything that moved.
Store the minimum you need to compute a transition: the invoice id, its last-seen status, its current version number, and a timestamp. When you fetch again, three questions answer everything:
- Did
statuschange? Sent to Viewed, Viewed to Paid, or a jump straight to Paid. - Did
versionincrement? That means line items, pricing, terms, or the due date changed since you last looked. - Did an amendment land? A new PO number or billing entity on the same version, usually because the recipient edited it themselves.
You do not need to monitor every invoice forever. Once an invoice hits Paid, drop it from the active poll set and archive the final record. Fewer invoices in the loop means a faster, cheaper job.
Decide what each transition triggers
Reading status is half the job. The point is to do something useful with each change, without a human watching a screen.
Sent, but still not Viewed after a few days. This is your early warning. The invoice may be in a spam folder or sitting with the wrong person. Queue a follow-up rather than waiting until the due date passes. The logic behind that call is laid out in checking if your invoice was opened before you chase it.
Viewed, no payment, past due. Someone saw it and did nothing. Now a nudge is warranted, and you can send it with confidence because you know it landed.
Version incremented. A content change happened, which means pricing or terms moved. Flag it for review so your records match the invoice the client is actually looking at. If you want the distinction spelled out, invoice versions versus amendments draws the line.
Amendment on the same version. The recipient added a PO number or fixed their billing address. Usually fine, sometimes not. You are notified, and you can revert it if it is wrong, so your script can log it and move on unless the change touches a field you care about.
Paid. Close the loop: record the payment date, stop polling that invoice, and trigger whatever comes next in your system, a receipt, a project unlock, a ledger entry.
Create invoices the same way you read them
Monitoring is more useful when creation is automated too. If your app bills clients on a schedule or on an event (a signed contract, a shipped milestone), you can generate the invoice over the API, capture the id it returns, and add it straight to your poll set. That way a new invoice is tracked from the moment it exists, with no manual step in between. The mechanics are in how developers create invoices with the REST API.
This end-to-end approach, create programmatically, track programmatically, act on transitions, is exactly what invoicing built for software developers is meant for. You keep your own billing logic and let the invoice link, the recipient collaboration, and the status tracking run on top of it.
Where the line is
JupiterInvoice tracks the invoice from issue to payment. It is not a payment processor and does not hold or move money. If you connect a Stripe account, card payments flow through that, and a Paid status reflects a real payment event or a payment you confirmed. If you read Paid in your poll, treat it as the money event for your downstream logic, but reconcile against your Stripe records for the accounting truth.
Start small. Point a script at a handful of live invoices, log every transition for a week, and you will see exactly which signals your business cares about. When you are ready to send through code, you can create an invoice by hand first to see the shape of the object, then build the loop around it.