List invoices | ToAPIs Documentation

GET

/api/v1/account/billing/invoices

Note for users in mainland China: Please use https://toapis.cn as the API endpoint (Base URL). Replace https://toapis.com with https://toapis.cn in the examples in this document.

See Getting started for authentication, pagination, and errors.

Behavior

Only a main account can read its own billing. Subaccounts receive HTTP 403. A main account cannot read member billing through this endpoint.

Defaults to 31 days with a 366-day maximum. Only the currently verified Customer is covered: meta.coverage=current_customer_only. A Customer mapping change invalidates old cursors. Amounts are decimal strings converted using Stripe currency rules: two decimals for USD/CNY, zero for JPY, three for KWD, and two for ISK/UGX compatibility. subtotal/total are invoice subtotal/total; amount_due/amount_paid/amount_remaining are due/paid/outstanding amounts. Without a reliable local order link, platform_trade_no=null; number and paid_at can also be null. No Customer ID, email, address, invoice download URL, or portal link is returned. Missing Customer mapping returns 409/15045, read failures 503/15046, and mapping conflicts 503/15047, rather than a fabricated empty list. Invoices are not local credit ledger entries.

Authentication

Authorizationstringheaderrequired

Use Bearer YOUR_SYSTEM_ACCESS_TOKEN. Model API keys are not accepted. X-User-Id is not required.

Parameters

fromstringquery

Inclusive start in RFC 3339 with a timezone. Provide together with to.

Constraints: date-time.

tostringquery

Exclusive end in RFC 3339 with a timezone. Must be later than from.

Constraints: date-time.

cursorstringquery

Pass the previous next_cursor unchanged and keep the same filters. Restart when filters change.

Constraints: maxLength=2048.

limitintegerquerydefault: 20

Maximum number of items per page.

Constraints: minimum=1; maximum=100; Default: 20.

requestExample

curl --request GET \
  --url 'https://toapis.com/api/v1/account/billing/invoices?from=2026-11-01T00:00:00Z&to=2026-11-02T00:00:00Z&limit=20' \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN'

import requests

response = requests.get(
    "https://toapis.com/api/v1/account/billing/invoices",
    headers={"Authorization": "Bearer YOUR_SYSTEM_ACCESS_TOKEN"},
    params={
        "from": "2026-11-01T00:00:00Z",
        "to": "2026-11-02T00:00:00Z",
        "limit": "20"
    },
    timeout=30,
)
response.raise_for_status()
print(response.json())

const url = new URL("https://toapis.com/api/v1/account/billing/invoices");
url.search = new URLSearchParams({
  "from": "2026-11-01T00:00:00Z",
  "to": "2026-11-02T00:00:00Z",
  "limit": "20"
}).toString();

const response = await fetch(url, {
  headers: { Authorization: "Bearer YOUR_SYSTEM_ACCESS_TOKEN" },
  signal: AbortSignal.timeout(30_000),
});

if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
console.log(await response.json());

Response fields

Examples use fictional data and assume credits_per_usd="100". Use the conversion rate returned by the API.

Results are in data.items. Paginate with has_more and next_cursor; the final cursor is null. No total count is returned.

codeinteger

Numeric result code; 0 means success.

messagestring

Response message; empty on success. Error messages are localized.

dataobject

Result object for this query.

data.itemsobject[]

Records on this page; [] when empty.

data.items[].idstring

Stripe invoice ID used to retrieve invoice details.

data.items[].providerstring

Payment service provider. Fixed value: "stripe".

data.items[].numberstring | null

Stripe invoice number, distinct from the invoice ID. null when unknown or inapplicable.

data.items[].statusstring

Invoice status returned by Stripe.

data.items[].created_atstring | null

Creation time. RFC 3339 timestamp with a timezone. null when unknown or inapplicable.

data.items[].currencystring

Original currency used by the amounts.

data.items[].subtotalstring

Invoice subtotal in the original currency specified by currency. Returned as a decimal string to preserve precision.

data.items[].totalstring

Invoice total in the original currency specified by currency. Returned as a decimal string to preserve precision.

data.items[].amount_duestring

Invoice amount due in the original currency specified by currency. Returned as a decimal string to preserve precision.

data.items[].amount_paidstring

Invoice amount paid in the original currency specified by currency. Returned as a decimal string to preserve precision.

data.items[].amount_remainingstring

Outstanding invoice amount in the original currency specified by currency. Returned as a decimal string to preserve precision.

data.items[].paid_atstring | null

Invoice payment-completion time recorded by Stripe. RFC 3339 timestamp with a timezone. null when unknown or inapplicable.

data.items[].platform_trade_nonull

Reliably linked local top-up order number; null if the link cannot be confirmed.

data.has_moreboolean

Whether another page is available.

data.next_cursorstring | null

Pass this cursor unchanged with the same filters. It is null on the last page.

data.metaobject

Metadata describing the source, query scope, and accounting basis.

data.meta.sourcestring

Data source. Local configuration or ledger snapshots do not imply live Stripe state.

data.meta.coveragestring

Invoice coverage: only the currently verified Stripe Customer, not all history.

data.meta.scopestring

Ownership scope of the query: the authenticated account itself.

data.meta.fetched_atstring

Time this query fetched invoice data from Stripe, not the invoice creation time.

data.meta.fromstring

Inclusive start of the query time range.

data.meta.tostring

Exclusive end of the query time range.

responseExample

{
  "code": 0,
  "message": "",
  "data": {
    "items": [
      {
        "id": "in_example_01",
        "provider": "stripe",
        "number": "EXAMPLE-0001",
        "status": "paid",
        "created_at": "2026-11-01T08:00:00Z",
        "currency": "USD",
        "subtotal": "10",
        "total": "10",
        "amount_due": "10",
        "amount_paid": "10",
        "amount_remaining": "0",
        "paid_at": "2026-11-01T08:01:00Z",
        "platform_trade_no": null
      }
    ],
    "has_more": false,
    "next_cursor": null,
    "meta": {
      "source": "stripe",
      "coverage": "current_customer_only",
      "scope": "self",
      "fetched_at": "2026-11-02T01:00:00Z",
      "from": "2026-11-01T00:00:00Z",
      "to": "2026-11-02T00:00:00Z"
    }
  }
}