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": 124.00,
    "settled": 124.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.audit_analytics (2026-07)",
        "amount": 99.00,
        "refId": "addon:3f2a…:addon.audit_analytics: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.

How charges are computed — proration

The formulas live in one place (PricingConstants) and the invoice only records their output, but two rules are worth knowing because they change what your first line looks like:

Add-ons: the first month is prorated by remaining days. When you enable a monthly add-on mid-month, the first charge is

first month = monthly price × remaining days in month / days in month

with the enabling day counted, the result rounded down to the cent (minimum $0.01). Enabling on the 1st charges the full price. From the next month on, the monthly billing run charges the full price. Enabling a $99/mo add-on on January 30th therefore charges $6.38 (2/31), then $99.00 from February.

The prorated charge and that month’s billing run share the same ledger refId (addon:{org}:{key}:{yyyyMM}), so the same month is never collected twice — the run’s attempt lands as an idempotent replay, and the invoice keeps the prorated line. The rule is identical on both payment rails: the prepaid-credit rail and the KRW card rail (which converts the same prorated USD amount at the fixed display rate).

Plan changes mid-period are prorated too. An upgrade charges the new plan for the remainder of the current period minus a credit for the unused portion of what you already paid (never below zero); the result appears as a proration line. Downgrades charge nothing now — they take effect at the end of the period already paid for.

Staying unpaid turns paid things off

An unpaid balance does not accrue, but it does not sit forever either. The grace clock runs for any organization with something paid at stake — a paid plan, paid monthly add-ons (including on the Free plan), or managed databases:

When	What happens
First failed attempt	A 3-day grace period opens. Owners get an in-app notification and an email that names the exact deadline and exactly what stops — the plan, each paid add-on by name, managed databases.
During the 3-day grace	Retries continue every cycle. Nothing else changes — everything stays active and no further notices are sent.
Still unpaid after 3 days	Whatever was named is enforced: a paid plan is downgraded to Free, paid monthly add-ons are turned off (one-time purchases and complimentary grants are never touched), managed databases are suspended. Owners get a second notification and email saying what happened.
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 any of this — only paid features turn off. Top up to restore them; turned-off add-ons are re-enabled from Billing.

One exemption: Enterprise agreements are settled contractually rather than by this clock.

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.

PDF

When an invoice is issued, the statement email sent to Owners carries a PDF copy attached (INV-{period}-{seq}.pdf). The PDF mirrors the sealed document — amounts are recorded, not recomputed.

Not included

PDF download over the API — the pdf path on the resource is not yet populated; the PDF currently arrives only as the email attachment.
Payment operations — there are none. To add credit, use the dashboard’s top-up flow.