tenancy
POST /v1/orgs/{orgId}/billing-currency
Change what this organization is invoiced in.
인증
Bearer 토큰으로 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