tenancy

POST `/v1/orgs/{orgId}/billing-currency`

Change what this organization is invoiced in.

المصادقة

أرسل مفتاح واجهة برمجة التطبيقات (API key) كرمز حامل (bearer token). يجب أن يحمل المفتاح إذن billing.payment.manage؛ والمفتاح الذي لا يملكه يُرفض بالرمز 403 وليس 404.

حيث يتم إدخال معرف مؤسستك

تأخذ نقطة النهاية هذه معرف مؤسستك في عنوان URL نفسه باسم orgId. استبدله في المسار — فلا يوجد رأس أو معامل استعلام يمكنه القيام بذلك بدلاً منه.

معرف مؤسستك موجود على شاشة مفاتيح واجهة برمجة التطبيقات (API) في لوحة تحكمك، بجوار المفتاح نفسه. وهو نفس المعرف في كل طلب تجريه.

جربه الآن

استبدل أي شيء بين أقواس زاوية بقيمك الخاصة، والعنصر النائب للمفتاح بمفتاح من لوحة تحكمك.

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

التفاصيل

⚖️ 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

POST /v1/orgs/{orgId}/billing-currency