ToAPIsToAPIs
Billing

List invoices

Page through invoices for the current Stripe Customer

GET
/api/v1/billing/stripe/invoices

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

See Access for authentication, pagination, and errors.

Behavior

Returns the account's Stripe invoices, for reviewing bills and payments. Only the main account can query its own billing; sub-accounts get HTTP 403, and a main account cannot use this endpoint to query member bills.

Returns invoices in the time range, defaulting to the last 31 days with a 366-day maximum.

Coverage is limited to the currently verified Stripe Customer (meta.coverage=current_customer_only), not the account’s full history, and once the Stripe Customer linked to the account changes, previously issued cursors become invalid and pagination must restart from the first page.

Amounts are decimal strings in the Stripe original currency: USD/CNY keep two decimals, JPY zero, KWD three, and ISK/UGX follow compatibility rules that keep two decimal places. subtotal/total are subtotal and total.

amount_due/amount_paid/amount_remaining are due, paid, and remaining amounts. platform_trade_no is null without a reliable local order link, and number and paid_at may also be null.

Customer IDs, email, addresses, invoice download URLs, and hosted links are not returned.

Error handling: no Customer returns 409 (code=15045), Stripe read failures return 503 (code=15046), and mapping conflicts return 503 (code=15047) rather than masking errors with an empty list.

Note that invoices live on the Stripe side and are not the same as local credit records.

Authentication

Authorizationstringheaderrequired

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

Request 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.

Request examples

requestExample

curl --request GET \
  --url 'https://api.toapis.com/api/v1/billing/stripe/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://api.toapis.com/api/v1/billing/stripe/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://api.toapis.com/api/v1/billing/stripe/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.

Response examples

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