billing
orc billing は、Workspace に適用される組織の契約、credit 残高、請求書、月間利用額を確認するコマンドです。円建ての支出上限と自動チャージを設定し、追加の利用 credit を見積もって Stripe の決済画面へ進めます。
実行前にログインし、対象の Workspace を確認してください。--workspace で対象を指定でき、契約と請求先はその Workspace の親組織の billing account に属します。支出上限・自動チャージの変更、購入、契約管理画面へのアクセスは人間の組織 owner または admin に限られ、API key や service account では実行できません。
使い方
orc billing current --workspace wks_example対象 Workspace の契約を確認する
orc billing monthly-spend get --workspace wks_example今月の利用額を確認する
結果の読み方
| 操作 | 主な出力 |
|---|---|
current | organizationId、billingAccountId、workspaceId、planTier、seatCount、creditBalance、entitlements、usage、契約状態 |
monthly-spend get | currency: JPY、used、reserved、limit、periodStart、periodEnd、timeZone、revision |
invoices list | invoices 内の請求書 ID・発行日時・状態・金額・通貨・URL |
purchase quote | 円建て credit 額・割引・税額・税込合計・calculationId・expiresAt |
--json は success、data、metadata の envelope を返します。項目の詳細は data を読みます。credit 残高、購入価格、月間利用額は用途が異なるため、同じ値として扱わないでください。
サブコマンド
current
対象 Workspace に適用された組織の契約スナップショットを返します。プラン、席数、API credit 残高、権利と使用量、Stripe の契約状態、期間末の解約予定と契約期間の終了日時を確認できます。current_period_end は取得できる場合に返り、credit bucket ごとの期限ではありません。
orc billing current [options]使用例
orc billing current --workspace wks_example契約と残高を確認する
orc billing current --workspace wks_example --json契約スナップショットを JSON で受け取る
invoices list
Workspace の親 billing account の最新 12 件の請求書を返します。請求書 ID、発行日時、説明、支払状態、金額、通貨、取得できる場合は請求書の URL が含まれます。未登録の請求先には空の一覧を返します。
orc billing invoices list [options]使用例
orc billing invoices list --workspace wks_example --json請求書を一覧にする
portal
管理者向けの Stripe 契約管理セッションを作成し、返された URL を既定ブラウザーで開きます。登録された請求先・決済方法・契約の管理に使います。ブラウザー側の操作結果を確認してください。
orc billing portal [options]固有のオプション
--no-browser
Return the billing URL without opening a browser
型: boolean。任意。
orc billing portal --no-browser使用例
orc billing portal --workspace wks_example契約管理画面を開く
monthly-spend get
Asia/Tokyo の今月の利用額と支出上限を JPY で返します。used は計上済み利用額、reserved は予約された金額です。料金を算定できない場合は両方が null になり、ゼロ支出として扱えません。periodStart、periodEnd、revision、設定変更の可否 canManage も返します。
orc billing monthly-spend get [options]使用例
orc billing monthly-spend get --workspace wks_example --json今月の利用額と上限を確認する
monthly-spend update
limit と直前に取得した revision を指定して支出上限を保存します。limit は JPY の整数で 0〜1,000,000,000、null は上限なしです。currency は入力しません。設定だけを変更し、この操作では購入しません。すべての必須入力を渡し、省略による部分更新は行いません。
orc billing monthly-spend update [options]固有のオプション
--revision
(required) Body field: revision
型: number。任意。
orc billing monthly-spend update --revision <value>使用例
orc billing monthly-spend get --workspace wks_example --json上限を変更する前に設定を読む
orc billing monthly-spend update --workspace wks_example --stdin --dry-run < spending-limit.json上限変更の送信内容を確認する
orc billing monthly-spend update --workspace wks_example --stdin < spending-limit.json上限を保存する
auto-recharge get
自動チャージの enabled、円建ての thresholdJpy と targetJpy、revision、変更権限 canManage、保存済み決済方法の利用可否 available と unavailableReason を返します。参照だけで課金は発生しません。
orc billing auto-recharge get [options]使用例
orc billing auto-recharge get --workspace wks_example --json自動チャージの状態を確認する
auto-recharge update
enabled、thresholdJpy、targetJpy、取得済みの revision を指定します。しきい値は 0〜99,999,999 円、目標残高は 1〜99,999,999 円の整数で、目標残高をしきい値より 50 円以上大きくします。対象は円建ての購入済み残高です。残高がしきい値以下になると、目標残高までの不足分を購入する設定です。有効化には自動決済できる登録済みの card または Link が必要です。設定変更には確認が必要で、非対話環境では --yes を指定します。
orc billing auto-recharge update [options]固有のオプション
--enabled
(required) Body field: enabled
型: string。任意。
orc billing auto-recharge update --enabled <value>--revision
(required) Body field: revision
型: number。任意。
orc billing auto-recharge update --revision <value>--target-jpy
(required) Body field: targetJpy
型: number。任意。
orc billing auto-recharge update --target-jpy <value>--threshold-jpy
(required) Body field: thresholdJpy
型: number。任意。
orc billing auto-recharge update --threshold-jpy <value>使用例
orc billing auto-recharge update --workspace wks_example --stdin --dry-run < auto-recharge.json変更内容を事前に確認する
orc billing auto-recharge update --workspace wks_example --stdin < auto-recharge.json設定を確認して保存する
purchase create
amountJpy、UUID の attemptId、Unix ミリ秒の attemptAt を指定して Stripe Checkout を開始します。calculationId を引数として渡す操作ではありません。CLI の確認後に決済画面を開き、請求先と最終的な税込金額を Stripe で確認して支払います。非対話環境では --yes が必要です。成功応答の url は決済画面の作成を示し、支払完了や credit 付与を示しません。
orc billing purchase create [options]固有のオプション
--amount-jpy
(required) Body field: amountJpy
型: number。任意。
orc billing purchase create --amount-jpy <value>--attempt-at
(required) Body field: attemptAt
型: number。任意。
orc billing purchase create --attempt-at <value>--attempt-id
(required) Body field: attemptId
型: string。任意。
orc billing purchase create --attempt-id <value>--no-browser
Return the billing URL without opening a browser
型: boolean。任意。
orc billing purchase create --no-browser使用例
orc billing purchase create --workspace wks_example --stdin --dry-run < purchase-attempt.json購入試行の送信内容を確認する
orc billing purchase create --workspace wks_example --stdin < purchase-attempt.json確認後に決済画面へ進む
再試行では同じファイルを使います。新しい attempt を作り直す前に支払状態を確認してください。
orc billing purchase create --workspace wks_example --stdin < purchase-attempt.json同じ購入試行を再送する
purchase quote
購入する利用 credit の円建て額を amountJpy に指定します。1〜99,999,999 の整数が必要です。creditAmountJpy、割引額と率、税額、税込合計、Stripe の税計算 ID calculationId と有効期限 expiresAt（Unix 秒）を返します。請求先を使った見積もりであり、購入や credit の付与は実行しません。
orc billing purchase quote [options]固有のオプション
--amount-jpy
(required) Body field: amountJpy
型: number。任意。
orc billing purchase quote --amount-jpy <value>使用例
orc billing purchase quote --workspace wks_example --amount-jpy 15000 --json15,000 円相当の利用 credit を見積もる
使用例
月間支出上限の入力
revision は例です。対象 Workspace の最新の get 応答で置き換えてください。上限なしにする場合は limit を null にします。
{
"limit": 10000,
"revision": 0
}月間支出上限の入力
自動チャージ設定の入力
最新の revision を使います。有効化後は設定条件を満たすと保存済み決済方法に請求されます。
{
"enabled": true,
"thresholdJpy": 1000,
"targetJpy": 5000,
"revision": 0
}自動チャージ設定の入力
見積もりから購入試行を準備する
見積もりの額・割引・税・期限を確認した後、購入ごとに一度だけ試行ファイルを作成します。同じ購入の再試行では保存したファイルを保持します。
orc billing purchase quote --workspace wks_example --amount-jpy 15000 --json
node --input-type=module -e 'import { randomUUID } from "node:crypto"; console.log(JSON.stringify({ amountJpy: 15000, attemptId: randomUUID(), attemptAt: Date.now() }))' > purchase-attempt.json見積もりから購入試行を準備する
決済後の状態を確認する
ブラウザーが開いたことだけで購入完了とは判断せず、決済画面の結果と契約・請求書の反映を確認します。
orc billing current --workspace wks_example --json
orc billing invoices list --workspace wks_example --json決済後の状態を確認する
購入と設定変更の流れ
購入前に purchase quote で金額と税を確認し、同じ amountJpy の購入試行を準備します。purchase create は確認を求め、返された Stripe Checkout URL を開きます。税や請求先の最終確認と支払いは Stripe で行います。見積もりの calculationId は税計算の識別子で、購入を承認する ID ではありません。
attemptAt は作成時刻の Unix ミリ秒です。サーバーは 23 時間を超えた試行と現在より 60 秒を超えて未来の試行を拒否します。通信失敗時は同じ attemptId と attemptAt を保って再試行し、古い試行は先に支払状態を確認します。
支出上限と自動チャージ設定は、get で取得した revision を update に渡します。確認対象の purchase create と auto-recharge update では、対話できない実行に --yes を指定します。--dry-run は送信予定を確認するためのもので、サーバーの権限・請求先・金額計算が成功する保証ではありません。
必要な権限
読み取りにも認証と対象 Workspace へのアクセスが必要です。monthly-spend update、auto-recharge update、purchase create、portal は組織の owner または admin の人間のセッションで実行します。権限不足は認証情報を再試行して回避せず、組織の管理者へ依頼してください。
グローバルオプション
orc billing では、次のグローバルオプションを使用できます。
各オプションの詳細と使用例は、グローバルオプションを参照してください。
トラブルシューティング
権限が拒否される
対象 Workspace とログインした組織を確認します。課金関連の変更には人間の owner/admin セッションが必要です。API key の権限を広げても、この制限は解除されません。
設定が別の画面で更新された
revision の競合には get を再実行し、最新設定を確認して必要な変更を組み直します。古い revision を繰り返し送信しません。
請求先・決済方法がない
見積もりには請求先が必要です。自動チャージの有効化には自動決済可能な支払い方法も必要です。auto-recharge get の available と unavailableReason を確認し、管理者が billing portal で請求情報を整えます。
購入や自動チャージの結果が不明
Checkout URL の作成を支払完了として扱わず、Stripe の画面と current・請求書を確認します。同じ購入を再試行する間は attempt を保持します。自動チャージの前回請求が未完了で設定変更を拒否された場合は、金額を変えて回避せず表示された案内に従います。
月間利用額が null
価格が算定できない状態です。used と reserved をゼロに置き換えず、算定状況を確認してください。API やネットワークの失敗をスクリプトで扱う場合は、stderr の文言ではなく終了コードを使います。