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_…).

curlTypeScriptPythonGo

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

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

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

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

{
  "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.

curlTypeScriptPythonGo

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

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

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

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

{
  "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.