Knowledge center

Run billing with Floatless.

Product guides, billing concepts, operational playbooks, developer references, and security notes for teams running subscription revenue.

Invoices API

Invoices expose issued billing amounts, balances, tax amounts, billing periods, and line items for external systems.

Endpoints

Method Endpoint Description
GET /invoices List invoices
GET /invoices/{invoice_id} Retrieve an invoice
GET /invoices/{invoice_id}/html Retrieve printable invoice HTML
GET /invoices/{invoice_id}/pdf Download invoice PDF
GET /invoices/{invoice_id}/transactions List invoice payment and credit memo transactions

The Invoice object

{
  "id": "5b4c33b4-6a86-4e5d-9fd9-2d3a7f09d874",
  "object": "invoice",
  "invoice_number": "INV-0001",
  "customer_id": 123,
  "subscription_id": 456,
  "invoice_date": "2026-07-07",
  "period_start": "2026-07-01",
  "period_end": "2026-07-31",
  "due_date": "2026-08-06",
  "status": "POSTED",
  "total": "99.00000000",
  "amount_paid": "0.00000000",
  "amount_refunded": "0.00000000",
  "balance": "99.00000000",
  "tax_amount": "0.00000000",
  "currency": "USD",
  "items": [
    {
      "id": 1,
      "product_id": 42,
      "description": "Pro Plan - Monthly",
      "quantity": "1.0000",
      "unit_price": "99.00000000",
      "line_total_pre_tax": "99.00000000",
      "tax_amount": "0.00000000",
      "tax_type": null
    }
  ],
  "created_at": "2026-07-07T10:00:00Z",
  "updated_at": "2026-07-07T10:00:00Z"
}

Amounts are returned as decimal strings to preserve financial precision.

Invoice transaction enums are uppercase: type PAYMENT | CREDIT_MEMO | REFUND, method CARD | BANK_TRANSFER | STRIPE | PAYPAL | EXTERNAL, status PENDING | COMPLETED | FAILED | REFUNDED.

List invoices

curl https://api.floatless.com/api/public/v1/invoices?customer_id=123 \
  -H "Authorization: Bearer sk_live_..."

Query parameters

Parameter Type Description
customer_id integer Filter by customer
status string Filter by invoice status
limit integer Number of results, 1 to 100
offset integer Pagination offset

Retrieve an invoice

curl https://api.floatless.com/api/public/v1/invoices/5b4c33b4-6a86-4e5d-9fd9-2d3a7f09d874 \
  -H "Authorization: Bearer sk_live_..."

Retrieve invoice HTML

Use this endpoint when an external portal or CRM needs a printable invoice document.

curl https://api.floatless.com/api/public/v1/invoices/5b4c33b4-6a86-4e5d-9fd9-2d3a7f09d874/html \
  -H "Authorization: Bearer sk_live_..."

The response content type is text/html.

Download invoice PDF

curl https://api.floatless.com/api/public/v1/invoices/5b4c33b4-6a86-4e5d-9fd9-2d3a7f09d874/pdf \
  -H "Authorization: Bearer sk_live_..." \
  --output invoice.pdf

The response content type is application/pdf. The Content-Disposition header includes the invoice PDF filename.

List invoice transactions

Invoice transactions provide the financial timeline behind the invoice balance, including payments, credit memos, and legacy refunds.

curl https://api.floatless.com/api/public/v1/invoices/5b4c33b4-6a86-4e5d-9fd9-2d3a7f09d874/transactions \
  -H "Authorization: Bearer sk_live_..."

Query parameters

Parameter Type Description
limit integer Number of results, 1 to 100
offset integer Pagination offset

Response

{
  "data": [
    {
      "id": "876f5f8e-6f6a-47ce-9b95-46a0aa2bff34",
      "object": "invoice_transaction",
      "invoice_id": "5b4c33b4-6a86-4e5d-9fd9-2d3a7f09d874",
      "type": "PAYMENT",
      "amount": "99.00000000",
      "method": "EXTERNAL",
      "status": "COMPLETED",
      "reference": "pay_external_123",
      "note": null,
      "created_at": "2026-07-07T10:15:00Z"
    }
  ],
  "pagination": {
    "limit": 25,
    "offset": 0,
    "total": 1,
    "has_more": false
  }
}

Invoice statuses

Invoice statuses are uppercase:

Status Description
DRAFT Invoice is being prepared; not yet issued
POSTED Invoice has been issued and is collectible
PAID Invoice has been fully paid
PARTIALLY_PAID Some amount is collected; balance remains
WITHDRAWN Invoice was withdrawn before collection
REFUNDED Invoice was fully refunded
PARTIALLY_REFUNDED Part of the paid amount was refunded
ℹ️
There are no `OVERDUE` or `VOID` statuses. Overdue state is derived: an invoice is overdue when `status` is `POSTED` or `PARTIALLY_PAID` and `due_date` has passed and `balance` is greater than zero.

Balance semantics

balance is computed as total − amount_paid; refunds are tracked separately in amount_refunded and in the invoice's transaction history, so reconcile refunds through the transactions endpoint rather than the balance field alone.

Next steps

PreviousCustomers APINextSubscriptions API