ToAPIsToAPIs
Billing

Get invoice

Read an invoice by ID

GET
/api/v1/billing/stripe/invoices/{invoice_id}

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 a single Stripe invoice by invoice ID. 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.

The invoice fields in the response match the list items, with data.meta additionally returning the read source, Customer coverage, and read time. Every fetch revalidates that the invoice belongs to the current Customer. Invoices owned by others or missing return 404.

hosted_invoice_url, invoice_pdf, and Customer IDs are not returned. See List invoices for field meanings.

Authentication

Authorizationstringheaderrequired

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

Request parameters

invoice_idstringpathrequired

Stripe invoice ID starting with in_.

Constraints: maxLength=255; pattern=^in_[A-Za-z0-9_]+$.

Request examples

requestExample

curl --request GET \
  --url 'https://api.toapis.com/api/v1/billing/stripe/invoices/in_example_01' \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN'
import requests

response = requests.get(
    "https://api.toapis.com/api/v1/billing/stripe/invoices/in_example_01",
    headers={"Authorization": "Bearer YOUR_SYSTEM_ACCESS_TOKEN"},
    timeout=30,
)
response.raise_for_status()
print(response.json())
const url = new URL("https://api.toapis.com/api/v1/billing/stripe/invoices/in_example_01");

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.

codeinteger

Numeric result code; 0 means success.

messagestring

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

dataobject

Result object for this query.

data.idstring

Stripe invoice ID used to retrieve invoice details.

data.providerstring

Payment service provider. Fixed value: "stripe".

data.numberstring | null

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

data.statusstring

Invoice status returned by Stripe.

data.created_atstring | null

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

data.currencystring

Original currency used by the amounts.

data.subtotalstring

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

data.totalstring

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

data.amount_duestring

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

data.amount_paidstring

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

data.amount_remainingstring

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

data.paid_atstring | null

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

data.platform_trade_nonull

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

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. Fixed value: "stripe".

data.meta.coveragestring

Invoice coverage: only the currently verified Stripe Customer, not all history. Fixed value: "current_customer_only".

data.meta.scopestring

Ownership scope of the query: the authenticated account itself. Fixed value: "self".

data.meta.fetched_atstring

Time this query fetched invoice data from Stripe, not the invoice creation time. RFC 3339 timestamp with a timezone.

Response examples

responseExample

{
  "code": 0,
  "message": "",
  "data": {
    "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,
    "meta": {
      "source": "stripe",
      "coverage": "current_customer_only",
      "scope": "self",
      "fetched_at": "2026-11-02T01:00:00Z"
    }
  }
}