Buys virtual machines and volumes, applies whatever granted credit the account
holds as a discount, and leaves the rest for a card. This is the only endpoint in
the API that spends money.
There is no card path HERE, and this is structural rather than a setting: a stored
card's first charge always requires an interactive 3-D Secure challenge in a
browser (global_settings.shop_threeds_only defaults to true and
credit_cards.threeds_authorized defaults to false), which nothing headless can
complete. So the order is PLACED and the subscriptions are created, and the whole
bill is left on the payment for a person to settle: needs_card says whether that
is the case, credit_applied says what the account's credit will take off it,
payable says what a card is then asked for, and payment_url is where a browser
finishes it. A card is never charged silently.
Placing an order moves no money. Nothing is taken from the balance here — the
credit is applied when the payment is settled, like any other bill, so an order
nobody ever pays holds none of the customer's credit. credit_applied and
payable are therefore projections of what will happen at payment, while the
nested payment object carries the row as it stands: its amount is the whole
figure and its applied_balance is 0.00 until it is paid.
Granted credit is a discount on the NET, capped at a share of it, so an order with
a price on it normally leaves something payable however large the balance. An order
is no longer refused for want of a balance.
Credit is granted by our staff, never bought; there is no way to add it from
the API or the panel.
Asynchronous. Paying does not provision. A queued listener reacts to the
order and dials the cloud, driving each subscription new → pending →
deployed or failed. The response is 202 and carries a Location header
pointing at the first subscription; poll GET /subscriptions/{id} from there.
A subscription that never leaves pending is a failed deployment that has not
yet been recorded — check failure_reason on the subscription.
Idempotent. Idempotency-Key is required. The key is claimed before the
order runs, so a client that times out and retries while the first request is
still in flight gets 409 rather than a second charge; once the first request
has finished, the same key with the same body replays the original 202 and
creates nothing.
Preconditions, each re-asserted here exactly as the panel's checkout
enforces them, and each refused with 422 naming the one that is unmet:
billing information on file, the end-user licence agreement accepted, an
identity or passport number on file, the shop open, and the caller's max_vms
/ max_vols quotas not exceeded. This endpoint is not a way around any limit
the panel applies.
Requires order:write, which is off by default when a token is minted and is
never implied by another ability.
