tenancy
POST /v1/orgs/{orgId}/billing-currency
Change what this organization is invoiced in.
認証
ベアラー トークンとして API キーを送信します。キーには billing.payment.manage 権限が付与されている必要があります。権限のないキーは 404 ではなく 403 で拒否されます。
組織 ID を入力する場所
このエンドポイントでは、URL内に組織IDを orgId として直接指定します。パスの中にその値を代入してください。この動作を代替するヘッダーやクエリパラメータはありません。
組織IDは、ダッシュボードのAPIキー画面にキーのすぐ横に表示されています。これは、実行するすべての呼び出しで同じIDになります。
試してみる
アングルブラケット内のすべてをご自身の値に置き換え、キーのプレースホルダーをご利用中のダッシュボードのキーに置き換えてください。
curl -X POST https://api.zinndigital.com/v1/orgs/{orgId}/billing-currency \
-H "Authorization: Bearer zdk_live_…" \
-H "Content-Type: application/json" \
-d '{ "currency": <string> }'ログインしていますか？ダッシュボード内のAPIコンソールでは、実際の組織IDやお客様ご自身のキーが自動入力され、ライブAPIに対してリクエストが実行されるため、実際のレスポンスを確認することができます。 API コンソールでこのエンドポイントを開く
詳細
⚖️ Owner ruling 2026-08-31 (W37-V). A customer may re-denominate their own organization. Three things happen and they are deliberately different: 1. **Invoices already issued are frozen.** An invoice is a legal document with a number; its currency, FX stamps and tax treatment stay as issued, for ever. ⚠️ An invoice that is still DUE keeps its old currency and will be collected in it — `invoices_left_in_old_currency` reports how many, so the screen can say so rather than let the customer discover it on a bill. 2. **Live subscriptions re-price from the CATALOGUE**, not by FX-converting the locked price. The catalogue's per-currency price is the number a page displayed and the business chose; a converted one would be invented and would drift on every rate move. A subscription whose plan has no price in the target currency is left in its original currency and counted in `subscriptions_unpriced` — never zeroed. 3. **Wallet credit is converted** at the day's rate, per purse, as a draw-down in the old currency plus a grant in the new sharing one reference. Credit is held per `(org, currency)` and currencies are never mixed, so leaving it would strand real money the customer could no longer spend. ⛔ A dedicated route rather than a field on `PATCH /v1/orgs/{orgId}`: a rename writes one column, this moves money. It requires `billing.payment.manage` — the person who may correct a typo in the account name is not necessarily the person who may re-denominate the balance. An org you cannot reach answers 404, not 403. ⭐ Send `dry_run: true` to get exactly these numbers **without** applying anything. The preview runs the real conversion inside a transaction it then rolls back, so it cannot disagree with the commit.
パラメータ
| 名前 | タイプ | 必須 | これがその内容です |
|---|---|---|---|
orgId (path) | Uuid | はい | Organization ID (UUIDv7). |
リクエスト本文
| 名前 | タイプ | 必須 | これがその内容です |
|---|---|---|---|
currency | string | はい | ISO-4217, the currency to invoice this organization in from now on. Must be one we can actually charge — enabled in the registry, not policy-blocked, and presentable by at least… |
dry_run | boolean | いいえ | Compute the change and report it **without applying it**. ⭐ The preview runs the real conversion in a transaction it rolls back, so the figures a customer confirms are the figur… |
返信
| 名前 | タイプ | 必須 | これがその内容です |
|---|---|---|---|
dry_run | boolean | はい | True when nothing was applied. |
from_currency | string | はい | — |
to_currency | string | はい | — |
rate | string | はい | Units of `to_currency` per unit of `from_currency`, to ten decimal places. ⛔ A **string**: JSON has no decimal type, and a float here would be the one place in this path that br… |
converted | ConvertedPurse[] | はい | The purses that moved. A purse whose balance rounds to zero in the target currency is **left alone** and is absent here — debiting it would destroy the customer's credit. |
subscriptions_repriced | integer | はい | Live subscriptions now priced from the catalogue in the new currency. |
subscriptions_unpriced | integer | はい | Live subscriptions whose plan has **no** price in the target currency. Left untouched in their original currency — never converted, never zeroed. |
invoices_left_in_old_currency | integer | はい | Issued invoices keeping the old currency, by design. Includes any still due. |
このエンドポイントが返すエラー
401 · 403 · 404 · 422 · 429