Get invoice API Reference

GET

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

curl --request GET \
  --url https://api.kupe.cloud/api/v1/tenants/acme/invoices/acme-20260301 \
  --header 'Authorization: <Authorization>'

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

Media type application/json

object

billingPeriod

object

end

string

start

string

createdAt

string

name

string

paddleTransactionID

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

string

resourceVersion

string

status

object

billedUntil

string

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

currency

string

issuedAt

string

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

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

subtotal

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

string

tax

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

string

total

Total is the final amount after credits and tax.

string

Example

{
  "billingPeriod": {
    "end": "2026-03-31T23:59:59Z",
    "start": "2026-03-01T00:00:00Z"
  },
  "createdAt": "2026-03-01T00:00:00Z",
  "name": "acme-20260301",
  "paddleTransactionID": "txn_01hv8wptq8987qeep44cyrewp9",
  "resourceVersion": "102934",
  "status": {
    "billedUntil": "2026-03-31T23:59:59Z",
    "creditsApplied": "20.00",
    "currency": "GBP",
    "issuedAt": "2026-03-31T23:59:59Z",
    "paddleInvoiceNumber": "325-10001",
    "phase": "Draft",
    "subtotal": "120.00",
    "tax": "20.00",
    "total": "100.00"
  }
}

Headers

ETag

string

Resource version

400

Invalid name

Media type application/json

object

code

string

error

string

field

string

message

string

severity

string

Example ^generated

{
  "code": "example",
  "error": "example",
  "field": "example",
  "message": "example",
  "severity": "example"
}

401

Missing or invalid authentication

Media type application/json

object

code

string

error

string

field

string

message

string

severity

string

Example ^generated

{
  "code": "example",
  "error": "example",
  "field": "example",
  "message": "example",
  "severity": "example"
}

403

Not a member of this tenant

Media type application/json

object

code

string

error

string

field

string

message

string

severity

string

Example ^generated

{
  "code": "example",
  "error": "example",
  "field": "example",
  "message": "example",
  "severity": "example"
}

404

Invoice not found

Media type application/json

object

code

string

error

string

field

string

message

string

severity

string

Example ^generated

{
  "code": "example",
  "error": "example",
  "field": "example",
  "message": "example",
  "severity": "example"
}

429

Rate limit exceeded

Media type application/json

object

code

string

error

string

field

string

message

string

severity

string

Example ^generated

{
  "code": "example",
  "error": "example",
  "field": "example",
  "message": "example",
  "severity": "example"
}