billing

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

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

प्रमाणीकरण

एपिआई कुञ्जीलाई बियरर टोकन (bearer token) को रूपमा पठाउनुहोस्। कुञ्जीसँग billing.payment.manage अनुमति हुनुपर्छ; अनुमति नभएको कुञ्जीलाई 404 होइन, 403 मार्फत अस्वीकार गरिन्छ।

यो इन्डपोइन्टले कुनै संस्थाको आइडी लिँदैन। तपाईंको कुञ्जीले यस अन्तर्गत पर्ने संस्थालाई पहिल्यै पहिचान गर्छ, र प्रतिक्रिया त्यसैमा सीमित हुन्छ।

प्रयास गर्नुहोस्

कोणीय कोष्ठकभित्र भएका जुनसुकै कुरालाई आफ्नो मानहरूद्वारा बदल्नुहोस्, र मुख्य स्थानहोल्डरलाई तपाईंको ड्यासबोर्डको कुञ्जीद्वारा बदल्नुहोस्।

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

लगइन गर्नुभएको छ? तपाईंको ड्यासबोर्डमा रहेको API कन्सोलले तपाईंको वास्तविक संस्थाको आईडी र आफ्नै कुञ्जी भरिदिन्छ, र लाइभ API विरुद्ध अनुरोध चलाउँछ ताकि तपाईंले वास्तविक प्रतिक्रिया हेर्न सक्नुहोस्। यो एन्डपोइन्टलाई API कन्सोलमा खोल्नुहोस्

विवरणहरू

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`.

प्यारामिटरहरू

नाम	प्रकार	आवश्यक	यो के हो
`subscriptionId (path)`	`Uuid`	हुन्छ	The subscription to pay ahead on.

अनुरोध बडी

नाम	प्रकार	आवश्यक	यो के हो
`periods`	`integer`	हुन्छ	How many whole billing periods to pay for now.

प्रतिक्रिया

नाम	प्रकार	आवश्यक	यो के हो
`order_id`	`Uuid`	हुन्छ	UUIDv7 identifier — sortable by creation time (docs/02 §8).
`order_number`	`string`	हुन्छ	—
`periods`	`integer`	हुन्छ	—
`total_amount_minor`	`integer`	हुन्छ	Including tax.
`currency`	`string`	हुन्छ	—
`status`	`string`	हुन्छ	—

यो इन्डपोइन्टले फर्काउन सक्ने त्रुटिहरू

401 · 403 · 404 · 422 · 429

POST /v1/subscriptions/{subscriptionId}/prepay