---
title: "Invoices"
description: "What you were charged, and what you are about to be."
url: "https://saved.sh/docs/billing/invoices"
---

Invoices are issued monthly, in arrears, against metered usage.

Both endpoints need `billing:read`, which is **human-only**.

## Past invoices [#past-invoices]

```bash
curl -fsS "https://api.saved.sh/v1/workspaces/$WID/invoices" \
  -H "Authorization: Bearer $TOKEN"
```

```json
{
  "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://..."
    }
  ]
}
```

<Callout type="warn">
  **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.
</Callout>

| 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 [#the-upcoming-invoice]

```bash
curl -fsS "https://api.saved.sh/v1/workspaces/$WID/invoices/upcoming" \
  -H "Authorization: Bearer $TOKEN"
```

```json
{
  "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](/docs/billing/credit).

<Callout>
  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.
</Callout>

## Reconciling against usage [#reconciling-against-usage]

The two views answer different questions and will not match line for line.

|                    | [Usage](/docs/billing/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](/docs/billing/pricing), 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.

<Callout type="warn">
  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.
</Callout>

## When an invoice fails [#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](/docs/billing/payment-methods#failed-payments).

## Tax and details [#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.

## Next [#next]

<Cards>
  <Card href="/docs/billing/usage" title="Usage" description="The quantities behind the number." />

  <Card href="/docs/billing/pricing" title="Pricing" description="The rates applied to them." />

  <Card href="/docs/billing/payment-methods" title="Payment methods" description="Making sure it can be paid." />
</Cards>