List invoices API Reference

GET

/tenants/{tenant}/invoices

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

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

Media type application/json

object

items

Array<object>

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

{
  "items": [
    {
      "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"
      }
    }
  ]
}

400

Invalid tenant 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"
}

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"
}