# Invoices

List and retrieve invoices this account has issued. Amounts are integer minor units
(cents). There is no public `POST /v1/invoices`.

`hosted_invoice_url` is the customer-facing page. It is `null` on a draft and stamped
when the invoice is finalized:

```
https://app.worthypayments.com/invoices/{id}/view?token=…
```

There is no `invoice.paygeyt.com` host. An empty `data` array is a successful list,
not a missing route.

A **CHARGE_AUTOMATICALLY** subscription (the default: we charge the saved card) writes a
**PAID** invoice on every successful **renewal**, including `POST
/v1/test/subscriptions/{id}/bill`. `hosted_invoice_url` is the receipt page. Opening `POST
/v1/subscriptions` still takes the charge without minting an invoice row in this release
(reconcile that first period against [charges](./03-charges.md). There is no
`invoice.payment_failed` webhook) a failed card renewal is `subscription.past_due`.

A **SEND_INVOICE** subscription writes an **OPEN** invoice on renewal and emails
it (`invoice.sent`). Opening create does not mint the first invoice today. Pay
it from the dashboard in this release.

An **incomplete** subscription (`payment_behavior=default_incomplete`, or no
card) has no listable invoice yet. The Element secret is on the create response
as `latest_invoice.payment_intent.client_secret`.

```
GET    https://api.worthypayments.com/v1/invoices
GET    https://api.worthypayments.com/v1/invoices/{id}
POST   https://api.worthypayments.com/v1/invoices/{id}/send
```

| Scope | Grants |
|-------|--------|
| `invoices:read` | List and fetch invoices |
| `invoices:write` | Send an invoice email, **server-only**, a `pk_` is refused |

```bash
curl "https://api.worthypayments.com/v1/invoices?limit=10" \
  -H "x-api-key: sk_test_xxx"
```

```json
{
  "object": "list",
  "data": [
    {
      "id": "in_7c1e0b2a-4d83-4f11-9c44-2a6f8d91e0b3",
      "object": "invoice",
      "status": "PAID",
      "total": 1999,
      "amount_due": 0,
      "currency": "usd",
      "hosted_invoice_url": "https://app.worthypayments.com/invoices/7c1e0b2a-4d83-4f11-9c44-2a6f8d91e0b3/view?token=…"
    }
  ],
  "has_more": false
}
```

Filter with `customer` (a `cus_…` id) and `status`. Page with `starting_after`.

## Send

`POST /v1/invoices/{id}/send` emails an **OPEN** (or later) invoice and emits
`invoice.sent`. A draft is refused (`finalize first`, finalize stays in the dashboard).
Re-sending is allowed. `invoices:write` is server-only. New secrets include it; an older
key must be granted it under **Developers → API keys**.

```bash
curl -X POST https://api.worthypayments.com/v1/invoices/in_7c1e0b2a-4d83-4f11-9c44-2a6f8d91e0b3/send \
  -H "x-api-key: sk_test_xxx"
```

There is **no `invoice.payment_failed` event**. A card renewal that declines is
`subscription.past_due`, subscribe to that. See [Subscriptions](./18b-subscriptions.md).

Finalize, pay and void stay in the dashboard in this release.

To run a renewal in test without waiting for the calendar, see [Testing, advance a test
subscription](./15-testing.md#advance-a-test-subscription).

Related: [Subscriptions](./18b-subscriptions.md).