ToAPIsToAPIs
請求

請求書一覧の取得

現在の Stripe Customer の請求書をページング取得

GET
/api/v1/billing/stripe/invoices

中国本土のユーザー向け: 中国本土のユーザーは https://api.toapis.cn を API エンドポイント (Base URL)としてご利用ください. 本ドキュメント内の例では https://api.toapis.com を https://api.toapis.cn に置き換えてください.

認証, ページ分割, エラーは利用方法を参照してください.

動作

アカウントの Stripe 請求書一覧を返し, 請求と支払いの照合に使います. 自身の請求を照会できるのは主アカウントのみで, サブアカウントは HTTP 403, 主アカウントも本エンドポイントでメンバー請求は参照できません.

期間内の請求書を返し, 既定は直近 31 日・最長 366 日です. 対象は現在検証済みの Stripe Customer に限られ (meta.coverage=current_customer_only), アカウントの全履歴ではありません.

アカウントに紐付く Stripe Customer が変わると, それまでのページングカーソルは無効になり, 最初のページからやり直す必要があります. 金額は Stripe の元通貨の十進文字列です: USD/CNY は小数 2 桁, JPY は 0 桁, KWD は 3 桁, ISK/UGX は小数 2 桁を維持する互換ルールで処理されます.

subtotal/total は小計と合計, amount_due/amount_paid/amount_remaining は請求額, 支払済み, 残額です. ローカル注文との確実な関連がない場合 platform_trade_no=null で, number と paid_at も null の場合があります.

Customer ID, メール, 住所, 請求書ダウンロード URL, ホストリンクは返しません. エラー処理: Customer がなければ 409 (code=15045), Stripe 読み取り失敗は 503 (code=15046), 対応の競合は 503 (code=15047) で, 空リストでエラーを隠しません.

請求書は Stripe 側のデータであり, ローカルの入金記録とは別物です.

認証

Authorizationstringヘッダー必須

Bearer YOUR_SYSTEM_ACCESS_TOKEN を使用します. モデル API キーは使用できません. X-User-Id は不要です.

リクエストパラメータ

fromstringクエリ

タイムゾーン付き RFC 3339 の開始時刻. この時刻を含みます. to と一緒に指定します.

制約: date-time.

tostringクエリ

タイムゾーン付き RFC 3339 の終了時刻. この時刻を含まず, from より後である必要があります.

制約: date-time.

cursorstringクエリ

前の next_cursor を変更せずに渡します. フィルターを維持し, 変更時は最初から取得します.

制約: maxLength=2048.

limitintegerクエリデフォルト: 20

1 ページの最大件数.

制約: minimum=1; maximum=100; 既定値: 20.

リクエスト例

リクエスト例

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());

レスポンスフィールド

例は架空のデータで, credits_per_usd="100" を仮定しています. 実際の換算にはレスポンスの値を使用してください.

結果は data.items にあります. has_more と next_cursor で次のページを取得します. 最終カーソルは null です. 総件数は返しません.

codeinteger

結果コード. 0 は成功です.

messagestring

成功時は空文字列です. エラーメッセージは翻訳されます.

dataobject

今回の照会結果オブジェクトです.

data.itemsobject[]

現在のページのレコード一覧. 空の場合は [] です.

data.items[].idstring

請求書詳細の取得に使う Stripe 請求書 ID です.

data.items[].providerstring

決済サービスの提供元です. 固定値: "stripe".

data.items[].numberstring | null

Stripe 請求書番号で, 請求書 ID とは異なります. 不明または対象外の場合は null です.

data.items[].statusstring

Stripe が返した請求書の状態です.

data.items[].created_atstring | null

作成時刻です. タイムゾーン付き RFC 3339 形式です. 不明または対象外の場合は null です.

data.items[].currencystring

金額の元通貨です.

data.items[].subtotalstring

請求書小計. currency の元通貨額です. 精度を保持するため 10 進文字列で返します.

data.items[].totalstring

請求書総額. currency の元通貨額です. 精度を保持するため 10 進文字列で返します.

data.items[].amount_duestring

請求書の支払必要額. 通貨は currency です. 精度を保持するため 10 進文字列で返します.

data.items[].amount_paidstring

請求書の支払済み額. 通貨は currency です. 精度を保持するため 10 進文字列で返します.

data.items[].amount_remainingstring

請求書の支払残額. 通貨は currency です. 精度を保持するため 10 進文字列で返します.

data.items[].paid_atstring | null

Stripe に記録された請求書支払完了時刻です. タイムゾーン付き RFC 3339 形式です. 不明または対象外の場合は null です.

data.items[].platform_trade_nonull

確実に関連するローカル注文番号. 関連を確認できなければ null です.

data.has_moreboolean

次のページがあるかを示します.

data.next_cursorstring | null

同じ条件で cursor にそのまま渡します. 最終ページは null です.

data.metaobject

データソース, 照会範囲, 集計基準などのメタデータです.

data.meta.sourcestring

データソースです. ローカル設定や台帳の値は Stripe のリアルタイム状態を意味しません.

data.meta.coveragestring

現在確認済みの Stripe Customer のみが対象で, 全履歴ではありません.

data.meta.scopestring

照会対象の所有範囲で, 認証された自身のアカウントです.

data.meta.fetched_atstring

今回 Stripe から取得した時刻で, 請求書の作成時刻ではありません.

data.meta.fromstring

照会時間範囲の開始時刻を含みます.

data.meta.tostring

照会時間範囲の終了時刻は含みません.

レスポンス例

レスポンス例

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