billing

POST `/v1/subscriptions/{subscriptionId}/prepay`

Create the order to pay for several billing periods at once.

Autentikasi

Kirim kunci API sebagai token bearer. Kunci tersebut harus memiliki izin billing.payment.manage; kunci tanpa izin tersebut akan ditolak dengan status 403, bukan 404.

Endpoint ini tidak memerlukan id organisasi. Kunci Anda telah mengidentifikasi organisasi tempatnya berafiliasi, dan respons akan dibatasi untuk organisasi tersebut.

Coba

Ganti apa pun di dalam tanda kurung sudut dengan nilai Anda sendiri, dan placeholder kunci dengan kunci dari dasbor Anda.

curl -X POST https://api.zinndigital.com/v1/subscriptions/{subscriptionId}/prepay \
  -H "Authorization: Bearer zdk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "periods": <integer> }'

Sudah masuk? Konsol API di dasbor Anda akan mengisi ID organisasi asli dan kunci Anda sendiri, serta menjalankan permintaan terhadap API langsung sehingga Anda dapat melihat respons aktualnya. Buka titik akhir ini di konsol API

Detail

Mints an **unpaid** order for N whole billing periods. ⛔⛔ **No money is taken here.** The client then settles that order through `POST /v1/orders/{orderId}/pay`, which already knows how to pay from account balance, from a gateway, or from both. That separation is the point rather than an implementation detail: it is what lets a customer with **no chargeable mandate** use this at all — somebody paying in crypto, or in a market whose regulator forbids an off-session charge. They top up once and pay six months from their balance, with no card anywhere in the flow. Replaying the same request returns the **same** order rather than a second one, so a double-clicked button cannot bill twice. Asking for a *different* number of periods supersedes the earlier unpaid prepay order and mints a fresh one — a customer changing their mind is not a collision. An unpaid order against this subscription that is **not** a prepayment (a plan change, say) is refused with `ORDER_IN_FLIGHT` instead, and is never cancelled on the customer's behalf. Requires `billing.payment.manage`. `422` carries a `code` in its details: `TOO_FEW` / `TOO_MANY` (outside the allowed range), `NOT_PREPAYABLE` (ended, comped or free), `RAIL_NOT_SUPPORTED` (billed by PayPal on its own schedule), or `ORDER_IN_FLIGHT`.

Parameter

Nama	Jenis	Wajib	Tentang apa ini
`subscriptionId (path)`	`Uuid`	Ya	The subscription to pay ahead on.

Isi permintaan

Nama	Jenis	Wajib	Tentang apa ini
`periods`	`integer`	Ya	How many whole billing periods to pay for now.

Tanggapan

Nama	Jenis	Wajib	Tentang apa ini
`order_id`	`Uuid`	Ya	UUIDv7 identifier — sortable by creation time (docs/02 §8).
`order_number`	`string`	Ya	—
`periods`	`integer`	Ya	—
`total_amount_minor`	`integer`	Ya	Including tax.
`currency`	`string`	Ya	—
`status`	`string`	Ya	—

Kesalahan yang dapat dikembalikan oleh titik akhir ini

401 · 403 · 404 · 422 · 429

POST /v1/subscriptions/{subscriptionId}/prepay