tenancy
POST /v1/orgs/{orgId}/billing-currency
Change what this organization is invoiced in.
身份验证
请将 API 密钥作为 bearer 令牌发送。该密钥必须具有 billing.payment.manage 权限；缺少该权限的密钥将被拒绝并返回 403 状态码，而非 404。
您的组织 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 figures… |
响应
| 名称 | 类型 | 必填 | 内容简介 |
|---|---|---|---|
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… |
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