List invoices API Reference

GET

/tenants/{tenant}/invoices

List all invoices for the tenant, ordered by billing period. Each invoice contains line items, totals, and applied credits. All amounts exclude VAT; tax is applied by Paddle at payment. Invoice phase is one of Draft, Billed, Paid, or PastDue. Names are server-controlled: usually “{tenant}-{YYYYMMDD}” (billing period start), but variants exist — names ending in “-final” are final invoices generated on tenant or subscription cancellation, covering usage between the last regular invoice and the cancellation moment, and a timestamp-suffixed form (“{tenant}-{YYYYMMDD-HHMMSS}”) is used when two billing periods start on the same date. The full invoice history is returned (no pagination; the server pages through the backing store internally).

Authorizations

BearerAuth

Parameters

Path Parameters

tenant

required

string

Tenant name

Responses

200

List of invoices

object

items

Array<object>

object

billingPeriod

object

end

string

Example

2026-03-31T23:59:59Z

start

string

Example

2026-03-01T00:00:00Z

createdAt

string

Example

2026-03-01T00:00:00Z

name

string

Example

acme-20260301

paddleTransactionID

PaddleTransactionID is the Paddle transaction that bills this invoice. Empty until the charge is created (Draft invoices).

string

Example

txn_01hv8wptq8987qeep44cyrewp9

resourceVersion

string

Example

status

object

billedUntil

string

Example

2026-03-31T23:59:59Z

conditions

Conditions are the latest observations of the invoice’s state (Kubernetes meta/v1 Condition shape). Notably, an ObservabilityDegraded condition with status “True” flags a partial invoice — observability usage data was incomplete for part of the period, so metered charges may be understated.

Array<object>

object

key

additional properties

creditsApplied

CreditsApplied is the promotional credit deducted from the subtotal; the net charge sent to Paddle is subtotal - creditsApplied.

string

Example

20.00

currency

string

Example

GBP

issuedAt

string

Example

2026-03-31T23:59:59Z

lineItems

Array<object>

object

key

additional properties

paddleInvoiceNumber

PaddleInvoiceNumber is Paddle’s customer-facing invoice number for the transaction that settled this invoice, set once the transaction completes. Display-only — use the invoice name and paddleTransactionID for correlation, never this number.

string

Example

325-10001

phase

Phase is the invoice lifecycle phase, aligned with Paddle transaction statuses: Draft (accruing, not yet charged), Billed (charge submitted to Paddle), Paid, PastDue (payment failed, in dunning).

string

Allowed values: Draft Billed Paid PastDue

Example

Paid

subtotal

Subtotal is the sum of all line items, excluding VAT.

string

Example

120.00

tax

Tax is the VAT amount calculated by Paddle at payment time.

string

Example

20.00

total

Total is the final amount after credits and tax.

string

Example

100.00

400

Invalid tenant name

object

code

string

error

string

field

string

message

string

severity

string

401

Missing or invalid authentication

object

code

string

error

string

field

string

message

string

severity

string

403

Not a member of this tenant

object

code

string

error

string

field

string

message

string

severity

string

429

Rate limit exceeded

object

code

string

error

string

field

string

message

string

severity

string