List invoices
Page through invoices for the current Stripe Customer
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
AuthorizationstringheaderrequiredUse Bearer YOUR_SYSTEM_ACCESS_TOKEN. Model API keys are not accepted. X-User-Id is not required.
Request parameters
fromstringqueryInclusive start in RFC 3339 with a timezone. Provide together with to.
Constraints: date-time.
tostringqueryExclusive end in RFC 3339 with a timezone. Must be later than from.
Constraints: date-time.
cursorstringqueryPass the previous next_cursor unchanged and keep the same filters. Restart when filters change.
Constraints: maxLength=2048.
limitintegerquerydefault: 20Maximum 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.
codeintegerNumeric result code; 0 means success.
messagestringResponse message; empty on success. Error messages are localized.
dataobjectResult object for this query.
data.itemsobject[]Records on this page; [] when empty.
data.items[].idstringStripe invoice ID used to retrieve invoice details.
data.items[].providerstringPayment service provider. Fixed value: "stripe".
data.items[].numberstring | nullStripe invoice number, distinct from the invoice ID. null when unknown or inapplicable.
data.items[].statusstringInvoice status returned by Stripe.
data.items[].created_atstring | nullCreation time. RFC 3339 timestamp with a timezone. null when unknown or inapplicable.
data.items[].currencystringOriginal currency used by the amounts.
data.items[].subtotalstringInvoice subtotal in the original currency specified by currency. Returned as a decimal string to preserve precision.
data.items[].totalstringInvoice total in the original currency specified by currency. Returned as a decimal string to preserve precision.
data.items[].amount_duestringInvoice amount due in the original currency specified by currency. Returned as a decimal string to preserve precision.
data.items[].amount_paidstringInvoice amount paid in the original currency specified by currency. Returned as a decimal string to preserve precision.
data.items[].amount_remainingstringOutstanding invoice amount in the original currency specified by currency. Returned as a decimal string to preserve precision.
data.items[].paid_atstring | nullInvoice payment-completion time recorded by Stripe. RFC 3339 timestamp with a timezone. null when unknown or inapplicable.
data.items[].platform_trade_nonullReliably linked local top-up order number; null if the link cannot be confirmed.
data.has_morebooleanWhether another page is available.
data.next_cursorstring | nullPass this cursor unchanged with the same filters. It is null on the last page.
data.metaobjectMetadata describing the source, query scope, and accounting basis.
data.meta.sourcestringData source. Local configuration or ledger snapshots do not imply live Stripe state.
data.meta.coveragestringInvoice coverage: only the currently verified Stripe Customer, not all history.
data.meta.scopestringOwnership scope of the query: the authenticated account itself.
data.meta.fetched_atstringTime this query fetched invoice data from Stripe, not the invoice creation time.
data.meta.fromstringInclusive start of the query time range.
data.meta.tostringExclusive 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"
}
}
}