Invoices
What you were charged, and what you are about to be.
View as MarkdownInvoices are issued monthly, in arrears, against metered usage.
Both endpoints need billing:read, which is human-only.
Past invoices
curl -fsS "https://api.saved.sh/v1/workspaces/$WID/invoices" \
-H "Authorization: Bearer $TOKEN"{
"data": [
{
"id": "in_1A...",
"number": "ACME-0007",
"status": "paid",
"amount_due": 2140,
"amount_paid": 2140,
"currency": "usd",
"period_start": "2026-07-01T00:00:00Z",
"period_end": "2026-08-01T00:00:00Z",
"created": "2026-08-01T02:11:00Z",
"hosted_url": "https://...",
"pdf_url": "https://..."
}
]
}Amounts are in cents. 2140 is $21.40. Dividing by 100 is on you, and getting this wrong
in a finance integration is the classic way to be out by two orders of magnitude.
| Field | Notes |
|---|---|
number | The human-facing invoice number |
status | paid, open, void, uncollectible and similar |
amount_due | Cents |
amount_paid | Cents. Differs from amount_due on a partial or failed payment |
hosted_url | A receipt page you can open or send to finance |
pdf_url | The PDF |
hosted_url and pdf_url are the right things to hand to an accounts team. Do not rebuild an
invoice from the usage endpoint: usage reports raw quantities, before discounts and credit.
The upcoming invoice
curl -fsS "https://api.saved.sh/v1/workspaces/$WID/invoices/upcoming" \
-H "Authorization: Bearer $TOKEN"{
"amount_due": 1806,
"subtotal": 1806,
"currency": "usd",
"period_start": "2026-08-01T00:00:00Z",
"period_end": "2026-09-01T00:00:00Z"
}This is what the current period has accrued so far, not a forecast to the end of the month. It rises as usage accrues.
subtotal is before credit and adjustments; amount_due is what would actually be charged.
They differ while you still have signup credit.
The upcoming invoice is the fastest sanity check after changing a retention policy or turning on a second copy. Watch it for a day or two rather than waiting for the month to close.
Reconciling against usage
The two views answer different questions and will not match line for line.
| Usage | Invoice | |
|---|---|---|
| Reports | Raw quantities per meter | Money |
| Includes discounts | No | Yes |
| Includes credit | No | Yes |
| Period | Current | Any closed period |
To go from one to the other: multiply quantities by the rates, apply your discount percentage, then draw down remaining credit. Small differences in the last decimal are rounding, and a large difference is worth asking about.
Usage recorded more than 35 days late is dropped rather than billed, because the payment processor will not accept it. In normal operation nothing gets close. If you find a period where usage clearly happened and was not billed, tell us rather than reconciling around it.
When an invoice fails
A failed payment starts the ladder: warned immediately, stopped after 7 days, blocked
after 30. New runs stop at stopped; reads and downloads never stop.
Fix the card and the workspace returns to active. See
Payment methods.
Tax and details
Invoice details, including any tax identifier and billing address, are held by the payment processor and edited through the hosted invoice page. We do not hold a separate copy to keep in sync.