Invoices

An Axowl invoice is a statement of what was charged and whether the ledger accepted it — not a demand for payment.

Axowl runs on prepaid credit. Charges are taken from your balance as they are billed, so there is no due date, no overdue state, no late fee, and no receivable. An invoice never asks you to pay; it records what already happened.

The invoice does not compute prices. It records the debits the billing worker actually attempted, and each line carries the ledger reference (refId) it was charged under — so you can verify any amount against the credit ledger independently of this API.

Authentication

All endpoints take an org API key:

X-Api-Key: ah_live_…

The key identifies the org; there is no org path parameter.

List invoices

GET /api/public/v1/invoices?limit=24

limit defaults to 24, max 120. Newest period first.

[
  {
    "id": "3f2a…",
    "number": "INV-202607-0007",
    "period": "202607",
    "periodStart": "2026-07-01T00:00:00Z",
    "periodEnd": "2026-08-01T00:00:00Z",
    "status": "Issued",
    "settlement": "settled",
    "currency": "USD",
    "subtotal": 45.00,
    "settled": 45.00,
    "unsettled": 0.00,
    "issuedAt": "2026-08-01T00:12:03Z",
    "lines": [
      {
        "category": "plan",
        "memo": "plan pro (2026-07)",
        "amount": 25.00,
        "refId": "plan:3f2a…:202607",
        "outcome": "ok"
      },
      {
        "category": "addon",
        "memo": "add-on addon.ai_console (2026-07)",
        "amount": 20.00,
        "refId": "addon:3f2a…:addon.ai_console:202607",
        "outcome": "ok"
      }
    ],
    "seal": {
      "selfHash": "9c1f…",
      "recordHash": "0a44…",
      "sealedAt": "2026-08-01T00:12:03Z"
    }
  }
]

Get one invoice

GET /api/public/v1/invoices/{id}

Same shape as a list element. 404 if the invoice does not belong to the calling org.

Fields

Field	Meaning
`number`	`INV-{yyyyMM}-{seq}`. `null` while the period is still open — a number is assigned only at issue. The sequence counts your org’s invoices, so it reveals nothing about anyone else.
`period`	`yyyyMM`. The billing month.
`status`	`Open` (still accruing) · `Issued` (closed and sealed, immutable) · `Superseded` (a corrected invoice replaced this one).
`settlement`	See below.
`subtotal`	Total charged this period.
`settled`	How much the ledger accepted.
`unsettled`	`subtotal − settled`. This is not a debt — see below.
`lines[].category`	`plan` · `proration` · `addon` · `sso` · `usage` · `other`. Derived from the `refId` prefix.
`lines[].refId`	The credit-ledger reference this line was charged under. Your verification handle.
`lines[].outcome`	`ok` · `insufficient` · `error`.
`seal.selfHash`	Document hash, sealed into the integrity chain. `null` until issued.
`seal.recordHash`	Row-level integrity hash.

`settlement` — “did the ledger accept it”, not “did you pay”

Because charges are drawn from prepaid credit at billing time, an invoice has no payment step. What varies is whether your balance covered the charge:

Value	Meaning
`settled`	Every line was taken from your credit.
`partial`	Some lines went through, others did not — usually a large line failed while smaller ones succeeded.
`awaiting_credit`	Nothing could be taken; your balance was empty at billing time.
`none`	Nothing was charged this period.

A line marked insufficient is retried while its billing period is still open. It is not a debt and it accrues nothing — no interest, no late fee, no collections.

Staying unpaid downgrades the plan

An unpaid balance does not accrue, but it does not sit forever either. Once a paid plan’s charge cannot be taken:

When	What happens
First failed attempt	Grace period opens. Owners get an in-app notification and an email naming the exact deadline.
During the 3-day grace	Retries continue every cycle. Nothing else changes — the plan stays active and no further notices are sent.
Still unpaid after 3 days	The plan is downgraded to Free and paid features stop. Owners get a second notification and email.
Topped up at any point	The grace period is cleared. A later shortfall starts a fresh 3-day clock.

Your data is never touched by a downgrade — only plan-gated features turn off. Top up and re-select a plan to restore them.

Two exemptions: Free organizations have nothing to downgrade, and Enterprise agreements are settled contractually rather than by this clock. Add-ons are not disabled by a downgrade; their charges keep retrying on their own lines.

Verifying an invoice

Three independent checks, in increasing depth:

The document is unmodified — seal.selfHash exists in the integrity chain. Any change to a line, an amount, or an outcome produces a different hash.
Each amount really moved — look up lines[].refId in the credit ledger and compare the amount. A line that claims outcome: "ok" has a matching ledger entry; one that does not, does not.
The ledger entry itself is unmodified — each ledger row carries its own seal and chain anchor.

An Open invoice has no selfHash yet; only step 2 applies to it.

Prepaid balance — top-ups and withdrawals

Your prepaid balance is two books, never one:

Cash — real money you topped up. Refundable and withdrawable.
Credit — welcome and volume bonuses. Non-refundable; usage always burns credit first, so your refundable cash survives as long as possible.

Withdrawals are self-service (dashboard → Billing → Axowl Credit → Withdraw) and go back as a refund to the original card payment — no bank onboarding. Two deductions apply, both recorded as their own ledger lines so the statement shows exactly what moved:

Deduction	Amount	Why
Cost recovery fee	2.9% + $0.30 of the withdrawn amount	The payment processor does not return its processing fee on refunds; this recovers that cost — at cost, no margin. Recorded as a separate `Fee` line.
Bonus clawback	Proportional to the refunded top-up	Volume bonus credit rides back out with the top-up it came with.

Card refunds usually land within 5–10 business days. Cash that did not arrive via a refundable card payment (or whose payment was already refunded) returns not_refundable_via_original_payment and is handled manually. Full terms: the Refund Policy.

Corrections

Issued invoices are never edited. A correction is a new invoice for the same period; the old one moves to Superseded and stays readable as history. If you cache invoices, key them by id and treat status as mutable.

Not included

PDF download — the pdf path is not yet populated.
Payment operations — there are none. To add credit, use the dashboard’s top-up flow.