Get invoice API Reference

GET

/tenants/{tenant}/invoices/{name}

Retrieve a specific invoice by name. Invoice names are server-controlled: usually “{tenant}-{YYYYMMDD}” where the date is the billing period start (e.g. “acme-20260301” for the period beginning 1 March 2026), but variants exist. Final invoices — generated on tenant or subscription cancellation — carry a “-final” suffix (e.g. “acme-20260301-final”) and cover usage between the last regular invoice and the cancellation moment; a timestamp-suffixed form (“{tenant}-{YYYYMMDD-HHMMSS}”) is used when two billing periods start on the same date. Always look up the actual name via list first rather than constructing it. Response includes detailed line items with per-resource cost breakdowns. All amounts exclude VAT; tax is applied by Paddle at payment. Phase is one of Draft, Billed, Paid, or PastDue.

Authorizations

BearerAuth

Parameters

Path Parameters

tenant

required

string

Tenant name

name

required

string

Invoice name (server-controlled; usually {tenant}-{YYYYMMDD}, variants exist — take it from the list response)

Responses

200

Invoice details

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

message

string

severity

string