TriportRPC
DashboardDocs

List invoices

GEThttps://api.triport.io/v1/billing/invoices?status=pending&limit=20

Return the authenticated user's billing invoices, optionally filtered by status and capped to a limit.

———

Lists the invoices that belong to the calling account, most-recent first. An invoice is the per-rail payment object in the Triport billing model: each one maps to exactly one channel, one rail, and (once created) one payment address. Use this endpoint to render a billing history table, to find a pending invoice to resume payment on, or to reconcile completed top-ups and subscription purchases.

When the request carries a valid session cookie the result is scoped to that user — you only ever see your own invoices. The response is always the shape { "invoices": [...] }; the array is empty (never null) when there is nothing to return.

This is a list view and returns the base Invoice object. It does not include the per-invoice payment address, qr_uri, or payments_received_micro — fetch a single invoice with GET /v1/billing/invoices/{id} for those fields.

Parameters

All parameters are query-string parameters; there is no request body.

statusstringoptional
Filter by invoice status. One of pending, paid, expired, cancelled. An unrecognized value returns 400. Omit to return all statuses.
limitintegeroptional
Maximum number of invoices to return. Omit (or 0) for the server default.
offsetintegeroptional
Number of invoices to skip before collecting limit results. Combine with limit for simple paging.

Response

Response fields

Each element of invoices is an Invoice object.

FieldTypeDescription
idstringUnique invoice identifier.
user_idstringOwner of the invoice.
amount_microintegerAmount due, in micro-units of USD (1000000 = 1.00).
statusstringOne of pending, paid, expired, cancelled.
descriptionstringHuman-readable line item for the invoice.
channelstringPayment channel: crypto-onchain or crypto-inapp.
railstringPayment rail, e.g. sol-spl-usdc, eth-usdc, polygon-usdt. One invoice = one rail.
bill_actionobjectWhat paying this invoice does — see below.
client_request_idstringCaller-supplied idempotency key from invoice creation.
fx_rate_micro_per_atomicintegerFX rate locked at creation, in micro-USD per atomic token unit (present for rails that require an FX rate).
created_atstringISO-8601 UTC timestamp of creation.
expires_atstringISO-8601 UTC timestamp after which a pending invoice can no longer be paid.
paid_atstringISO-8601 UTC timestamp the invoice was paid. Present once status is paid.
processed_atstringISO-8601 UTC timestamp the payment was applied (e.g. subscription activated). Present after post-payment processing.

The bill_action object describes the account effect of payment:

FieldTypeDescription
typestringsubscription_purchase, subscription_renew, or topup.
planstringPlan key for subscription actions, e.g. starter, growth, scale.
monthsintegerBilling duration: 1, 3, 6, or 12.

Errors

CodeMeaningWhen it happens
400bad status filterstatus is set to a value other than pending, paid, expired, or cancelled.
500server errorAn internal error occurred while loading invoices.

Errors are returned as { "error": "<message>" }. See the shared error reference for the full envelope.

Examples

JavaScript (fetch)

const params = new URLSearchParams({ status: "pending", limit: "20" });
const res = await fetch(
  `https://api.triport.io/v1/billing/invoices?${params}`,
  { credentials: "include" },
);
if (!res.ok) {
  const { error } = await res.json().catch(() => ({}));
  throw new Error(error ?? `HTTP ${res.status}`);
}
const { invoices } = await res.json();
console.log(`${invoices.length} invoice(s)`);

TypeScript SDK (@triport/sdk)

import { Triport } from "@triport/sdk";


const triport = new Triport({ session: process.env.TRIPORT_SESSION });


const { invoices } = await triport.billing.invoices.list({
  status: "pending",
  limit: 20,
});


for (const inv of invoices) {
  console.log(inv.id, inv.status, inv.amount_micro);
}

Python (triport-sdk)

from triport import Triport


triport = Triport(session=os.environ["TRIPORT_SESSION"])


result = triport.billing.invoices.list(status="pending", limit=20)
for inv in result["invoices"]:
    print(inv["id"], inv["status"], inv["amount_micro"])

Notes

  • Scope. Results are limited to the authenticated user's invoices. The list is intentionally lean — call GET /v1/billing/invoices/{id} for the payment address, QR URI, and received-amount details of a single invoice.
  • Amounts are micro-USD. Divide amount_micro and fx_rate_micro_per_atomic by 1_000_000 to get a USD value.
  • Paging. Combine limit and offset for basic pagination; there is no cursor on this endpoint. For balance ledger entries, the cursor-paginated GET /v1/balance/ledger endpoint is the counterpart.
  • Live updates. To react to invoice state changes in real time rather than polling this list, subscribe to the per-invoice SSE stream GET /v1/billing/invoices/{id}/events.
  • Related: Create invoice, Cancel invoice, Pay from balance.