# Invoices

Your invoices, with totals, payments and line items. Needs the `read_billing` permission, which is ticked separately when a key is made. Without it these endpoints answer `403 permission_denied`.

## List invoices

`GET /invoices` returns the account's invoices, newest first. Draft invoices are not shown. Paged with `limit` (1 to 100, default 50) and `cursor` (`inv_…`).

```bash
curl -sS "https://api.redswitches.com/v1/invoices?limit=10" \
  -H "Authorization: Bearer $REDSWITCHES_API_KEY"
```

```ts
const page = await rs.invoices.list({ limit: 10 });
const unpaid = page.data.filter((i) => i.status === "unpaid");
```

```python
page = client.invoices.list(limit=10)
unpaid = [i for i in page.data if i.status == "unpaid"]
```

```go
page, err := client.Invoices.List(ctx, &redswitches.ListOptions{Limit: 10})
```

```json
{
  "data": [
    {
      "id": "inv_789",
      "number": "INV-2026-11-0789",
      "status": "paid",
      "date": "2026-11-15",
      "due_date": "2026-11-15",
      "paid_at": "2026-11-15T09:30:12Z",
      "currency": "USD",
      "subtotal": "129.00",
      "tax": "25.80",
      "total": "154.80",
      "credit": "0.00",
      "balance": "0.00"
    }
  ],
  "next_cursor": "inv_789"
}
```

## Get an invoice

`GET /invoices/{id}` adds the line items.

```bash
curl -sS https://api.redswitches.com/v1/invoices/inv_789 \
  -H "Authorization: Bearer $REDSWITCHES_API_KEY"
```

```ts
const invoice = await rs.invoices.get("inv_789");
```

```python
invoice = client.invoices.get("inv_789")
```

```go
invoice, err := client.Invoices.Get(ctx, "inv_789")
```

```json
{
  "id": "inv_789",
  "number": "INV-2026-11-0789",
  "status": "paid",
  "date": "2026-11-15",
  "due_date": "2026-11-15",
  "paid_at": "2026-11-15T09:30:12Z",
  "currency": "USD",
  "subtotal": "129.00",
  "tax": "25.80",
  "total": "154.80",
  "credit": "0.00",
  "balance": "0.00",
  "items": [
    {
      "description": "Instant Dedicated Server E-2388G (15/11/2026 - 14/12/2026)",
      "amount": "129.00",
      "taxed": true,
      "service": "srv_123"
    }
  ]
}
```

## Fields

| Field | Type | Meaning |
|---|---|---|
| `id` | string | `inv_<n>`. |
| `number` | string | The invoice number as printed. |
| `status` | string | `paid`, `unpaid`, `cancelled`, `refunded`, `collections`, `payment_pending` or `other`. |
| `date` | string or null | Invoice date (`YYYY-MM-DD`). |
| `due_date` | string or null | Due date (`YYYY-MM-DD`). |
| `paid_at` | string or null | When it was paid (UTC). |
| `currency` | string | The account's currency. |
| `subtotal`, `tax`, `total` | string | Decimal strings. |
| `credit` | string | Account credit applied to this invoice. |
| `balance` | string | Still to pay. `"0.00"` unless the invoice is unpaid, payment pending or in collections. |
| `items` | array | On `GET /invoices/{id}` only. Each line: `description`, `amount`, `taxed` (boolean), and `service` (the server id, or null). |

Line descriptions are written by the API in a fixed form: the plan name and billing period for a server, a fixed phrase for credit and fees, and "Other charge" for anything else.