@leaflow/sdk 0.101.0 → 0.103.0

package/dist/billing/account/v1/schema.d.ts

@@ -388,15 +388,19 @@ export interface paths {
         get?: never;
         put?: never;
         /**
-         * Pay invoice
-         * @description Applies the account balance first, then charges the remainder to a payment method. Give
-         *     `payment_method_id` to choose one, or omit it to use the default.
+         * Pay an invoice
+         * @description Applies eligible credit grants and available balance as requested, then collects the remainder
+         *     through the selected payment gateway and method. With no gateway selection, insufficient
+         *     account funds fail without starting an online payment. Card and non-card methods use this same
+         *     operation. Promotion codes are confirmed by checkout, before collecting payment.
          *
-         *     Returns a checkout address when the gateway requires the cardholder to confirm the
-         *     payment; the invoice is marked paid once the gateway confirms it.
+         *     Returns a payment action when customer interaction is required. requires_action and processing
+         *     do not mean paid; the invoice is marked paid after payment is confirmed. An unresolved payment
+         *     attempt is reused, and retries do not apply credit grants or balance twice.
          *
-         *     Calling this on an invoice that is already paid returns the invoice unchanged. A void invoice
-         *     is refused with `BILLING_INVOICE_NOT_PAYABLE`; the invoice of an order that has failed or was
+         *     Calling this on an invoice that is already paid returns the existing payment result without
+         *     another charge. A draft order invoice must first be confirmed through checkout. It and a void
+         *     invoice are refused with `BILLING_INVOICE_NOT_PAYABLE`; the invoice of an order that has failed or was
          *     canceled, with `BILLING_ORDER_FAILED` or `BILLING_ORDER_CANCELED`; and that of an order whose
          *     payment deadline has passed, with `BILLING_ORDER_EXPIRED`.
          */
@@ -453,7 +457,7 @@ export interface paths {
          *     Either every invoice is paid or none is. When the credit grants and balance cannot cover
          *     them all, the request fails with `BILLING_INSUFFICIENT_FUNDS` and nothing is charged.
          *     Invoices that are already paid are not charged again. An invoice with an online payment
-         *     still in progress is refused with `BILLING_PAYMENT_PENDING`, a void invoice with
+         *     still in progress is refused with `BILLING_PAYMENT_PENDING`, a draft order invoice or void invoice with
          *     `BILLING_INVOICE_NOT_PAYABLE`, an order that has failed or was canceled with
          *     `BILLING_ORDER_FAILED` or `BILLING_ORDER_CANCELED`, and an order whose payment deadline has
          *     passed with `BILLING_ORDER_EXPIRED`.
@@ -693,23 +697,33 @@ export interface paths {
         get?: never;
         put?: never;
         /**
-         * Quote renewals or a cancellation
-         * @description Priced in the currency of the billing account that pays for the subscriptions, and at any rate
-         *     negotiated for that account. Nothing is reserved and nothing is recorded, so this may be called
-         *     as often as required. Prices may change between quoting and renewing, so a quote should be
-         *     refreshed before a final confirmation is shown.
+         * Quote order checkout, renewals or a cancellation
+         * @description Computes a price preview without creating a resource or saving a quote. Nothing is charged,
+         *     reserved or applied to an order, and no discount redemption is consumed. The response has no
+         *     quote ID and does not guarantee a price or reserve a promotion code.
+         *
+         *     With order_id, uses that order's recorded purchase terms and billing account. An optional
+         *     promotion_code previews one code; without it, Billing selects an applicable account discount.
+         *     An invalid or inapplicable explicit code is refused rather than silently replaced. Give total
+         *     as expected_amount when confirming checkout; eligibility and availability are checked again.
+         *     An order already checked out returns its confirmed amounts, without reapplying its discount;
+         *     a different code is refused with BILLING_ORDER_CHECKOUT_CONFLICT.
          *
          *     A renewal is priced exactly as renewing would charge it: at the agreed amount or the price
-         *     named, with the discounts the account holds, and with tax.
+         *     named, with the discounts the account holds, and with tax. A renewal list does not accept a
+         *     promotion code because its entries create separate orders. To use a new code on a renewal,
+         *     first create a renewal order and quote its checkout by order_id. Prices and discount eligibility
+         *     may change between preview and confirmation.
          *
          *     A cancellation is quoted as creating it would compute the refund, as of now and under the refund
-         *     terms agreed when each subscription was bought. It is quoted on its own: combined with renewals
+         *     terms agreed when each subscription was bought. It is quoted on its own: combined with another target
          *     the request is refused with HTTP 400 `BILLING_PURCHASE_INVALID` and `meta.field`
          *     `cancellation`. It is refused with the same errors as creating the cancellation, except that the
          *     amount is not checked. Give the returned `cancellation.proration_date` and
          *     `cancellation.refundable_amount` when creating it.
          *
-         *     Every subscription must be paid for by the same one of your billing accounts; otherwise the
+         *     Orders must belong to one of your billing accounts. Every subscription in a renewal or cancellation
+         *     quote must be paid for by the same one of your billing accounts; otherwise the
          *     request is refused with HTTP 400 `BILLING_PURCHASE_INVALID`. Returns 404 when a subscription does
          *     not exist, and 403 `BILLING_ACCOUNT_FORBIDDEN` when it is paid for by an account you do not own.
          */
@@ -764,7 +778,7 @@ export interface paths {
          *     - 409 `BILLING_CANCELLATION_SCHEDULES_DIFFER` when, for `period_end`, the paid terms end at
          *       different times;
          *     - 409 `BILLING_SUBSCRIPTION_OPERATION_PENDING` when a subscription is already being canceled
-         *       (`meta.cancellation_id`) or reclaimed (`meta.job_id`);
+         *       (`meta.cancellation_id`) or reclaimed (`meta.action_id`);
          *     - 409 `BILLING_ORDER_PAYMENT_IN_FLIGHT` while an online payment for a renewal of one of them
          *       is in progress;
          *     - 409 `BILLING_CANCELLATION_REFUND_CHANGED` when the refund is no longer
@@ -894,11 +908,13 @@ export interface paths {
         put?: never;
         /**
          * Create renewal order
-         * @description Places a renewal order and issues its invoice without charging anything; pay the invoice to
-         *     renew. The periods and price are chosen as for renewing. The order can be paid until the
-         *     current paid period ends, and never after the end of the first period it renews; unpaid by
+         * @description Places a renewal order with a draft invoice, without applying a new discount or charging anything.
+         *     Quote and confirm its checkout before collecting payment to renew. Existing subscription
+         *     discount commitments are retained. The periods and price are chosen as for renewing. The order
+         *     can be paid until the current paid period ends, and never after the end of the first period it renews; unpaid by
          *     then, it is canceled. While auto-renew is on, the renewal due at the end of the period pays
-         *     this order instead of placing another.
+         *     this order instead of placing another, confirming checkout with an applicable account discount
+         *     first if it has not already been confirmed.
          *
          *     Save `order_id` before submitting and read the order after an unknown outcome; creating it a
          *     second time conflicts.
@@ -937,27 +953,6 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
-    "/account/v1/promotion-codes/preview": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        get?: never;
-        put?: never;
-        /**
-         * Preview promotion code
-         * @description Nothing is recorded and the code is not consumed. Use it to show the customer the effect
-         *     before they commit.
-         */
-        post: operations["preview-promotion-code"];
-        delete?: never;
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
     "/account/v1/allowances": {
         parameters: {
             query?: never;
@@ -993,7 +988,7 @@ export interface paths {
         };
         /**
          * List orders
-         * @description Lists acceptance status and associated invoice amounts. Pending may be unpaid or paid; active means accepted, not delivered. Only pending orders expire at expires_at.
+         * @description Lists acceptance status and associated invoice amounts. pending_checkout awaits confirmation; pending has confirmed checkout and may be unpaid or paid. active means accepted, not delivered. pending_checkout and pending orders can expire at expires_at.
          */
         get: operations["list-orders"];
         put?: never;
@@ -1023,6 +1018,55 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/account/v1/orders/{orderId}/checkout": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                orderId: components["parameters"]["OrderId"];
+            };
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Confirm order checkout
+         * @description Confirms the purchase's final amount and discount. Supply the same promotion_code used for the
+         *     preview, or omit it to select an applicable account discount. At most one new coupon is applied
+         *     to an order; existing subscription discount commitments are not stacked with a new coupon on
+         *     the same line. Promotion codes are evaluated against the order, not client-supplied line amounts.
+         *
+         *     Rechecks eligibility and redemption availability. A different total fails with
+         *     BILLING_AMOUNT_CHANGED. An invalid or inapplicable code fails rather than collecting full price.
+         *     A failed confirmation leaves the invoice draft and reserves no discount redemption.
+         *
+         *     A successful confirmation records the discount, including any recurring discount terms,
+         *     reserves its redemption, moves pending_checkout to pending and finalizes the invoice when one
+         *     is required. The reservation counts toward the code's limits and is consumed when the invoice
+         *     is paid, or at confirmation when nothing is due. Use pay-invoice to collect
+         *     its outstanding amount from account funds or a payment gateway. No payment attempt or checkout
+         *     session is created by this operation. An order whose total is zero completes checkout at
+         *     placement in either mode and does not need this operation; an order with an amount due, even
+         *     when credits would cover it, still does. Checkout alone does not confirm resource delivery.
+         *
+         *     Retrying with the same code and expected amount returns the existing order without another
+         *     redemption. Omitting the code on a confirmed checkout retains its recorded discount. Changing
+         *     that code is refused with BILLING_ORDER_CHECKOUT_CONFLICT. Payment retries reuse the confirmed
+         *     terms. Cancellation, expiry or complete fulfillment failure releases the reservation or returns
+         *     the consumed redemption; a refund alone does not.
+         *
+         *     The order must belong to one of your billing accounts. A canceled, failed or expired order
+         *     cannot be checked out. A period-end change cannot be checked out before its renewal invoice is
+         *     available. Orders retain their billing account and currency after a project is linked elsewhere;
+         *     discounts from another account cannot be used for them.
+         */
+        post: operations["checkout-order"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/account/v1/orders/{orderId}/cancel": {
         parameters: {
             query?: never;
@@ -1113,19 +1157,59 @@ export interface components {
          */
         TerminationPolicy: "immediate" | "period_end";
         /**
-         * @description Prorated returns the unused value of paid service periods using integer-second duration ratios. Setup fees are excluded. Tax and funds follow the original invoice and payment sources.
+         * @description none refunds nothing. prorated refunds the amount paid for the current period minus the value of
+         *     the time used, never below zero and never more than what remains unrefunded. The time used runs
+         *     from the period start to the effective cancellation time and is valued at the plan's
+         *     shorter-period prices in the same currency, frozen at purchase as the order item's
+         *     refund_monthly_amount and refund_hourly_amount: each full calendar month at the one-month prepaid
+         *     price, the remainder at the postpaid hourly price or, without one, at the one-month price by the
+         *     second. When the plan has no prepaid period shorter than the one bought, the time used is valued
+         *     at the price paid, pro rata by the second. Discounts are not refunded, as they were never paid,
+         *     and setup fees are excluded. The refunded part returns to the payment sources it came from. Tax
+         *     paid is refunded in the same proportion as the amount it was paid on.
          * @enum {string}
          */
         RefundPolicy: "none" | "prorated";
-        /** @description Specify renewals for existing subscriptions, or one cancellation on its own. */
+        /**
+         * @description Quote exactly one target: an existing `order_id`, `renewals` or a `cancellation`. Giving none or
+         *     more than one, or a `promotion_code` with `renewals` or a `cancellation`, fails with HTTP 400
+         *     `BILLING_PURCHASE_INVALID` and `meta.field` naming the offending field. Without a code, an
+         *     applicable account discount is selected. An explicit code is evaluated without reserving or
+         *     consuming a redemption and must be supplied again when confirming checkout through Billing.
+         */
         QuoteRequest: {
+            /**
+             * Format: uuid
+             * @description Preview checkout of this existing order. Its recorded purchase terms supply every line, and a
+             *     confirmed order returns its recorded amounts. A preview does not change the order.
+             */
+            order_id?: string;
+            /**
+             * @description Preview renewing these subscriptions, each at most once. Each entry represents a separate
+             *     renewal order. To preview a new promotion code, create a renewal order and quote it by order_id.
+             */
             renewals?: components["schemas"]["QuoteRenewal"][];
             cancellation?: components["schemas"]["QuoteCancellation"];
+            promotion_code?: string;
+        };
+        CheckoutOrderRequest: {
+            /**
+             * @description The code to apply, evaluated again at confirmation. Omit to select an applicable account
+             *     discount. On an already confirmed checkout, omission retains the recorded discount.
+             */
+            promotion_code?: string;
+            /**
+             * @description Quote.total in the order's currency, after discounts and tax but before applying credit
+             *     grants or balance. A different total fails with BILLING_AMOUNT_CHANGED.
+             */
+            expected_amount: components["schemas"]["Money"];
         };
         /**
          * @description Price renewing a prepaid subscription. Give `price_id`, or `interval` with
          *     `interval_count`, to renew for another term at the price currently sold for it. Naming
-         *     the current term, or giving neither, renews at the agreed amount.
+         *     the current term, or giving neither, renews at the agreed amount. A term sold at several
+         *     prices that differ in termination policy is refused with 409
+         *     `BILLING_RENEWAL_OPTION_AMBIGUOUS` unless `termination_policy` or `price_id` is given.
          */
         QuoteRenewal: {
             /** Format: uuid */
@@ -1135,6 +1219,8 @@ export interface components {
             /** @enum {string} */
             interval?: "day" | "month" | "year";
             interval_count?: number;
+            /** @description With `interval` and `interval_count`, chooses among prices of that term that differ in termination policy. */
+            termination_policy?: components["schemas"]["TerminationPolicy"];
             /**
              * @description How many consecutive periods to renew for.
              * @default 1
@@ -1178,18 +1264,110 @@ export interface components {
              */
             total: components["schemas"]["Money"];
         };
+        /**
+         * @description A purchase quote line or one recorded order item. Monetary fields use the account currency.
+         *     Fixed purchase amounts are rounded as checkout rounds them. Usage estimates are not amounts
+         *     collectible at checkout. When priced is false, monetary fields and price_id are absent.
+         */
+        QuotedLine: {
+            /** @description Tax on the discounted amount, including any tax already contained in that amount. */
+            tax_amount?: components["schemas"]["Money"];
+            /** @description The part of tax_amount already contained in amount minus discount_amount. */
+            tax_included_amount?: components["schemas"]["Money"];
+            /** @description Zero-based request line index, or the recorded order item's position for an order quote. */
+            index: number;
+            /**
+             * Format: uuid
+             * @description Present for an existing order quote; identifies the recorded item being priced.
+             */
+            order_item_id?: string;
+            /**
+             * @description Whether a price was found for this line. Read this before anything else.
+             *
+             *     A single item with no price no longer fails the whole request. A catalogue
+             *     almost always has something not yet priced, and refusing the request would
+             *     leave no way to render a list in which a few entries are simply not on sale.
+             *
+             *     When false, `price_id`, `unit_amount` and `amount` are absent and
+             *     `unpriced_reason` states what is missing.
+             */
+            priced: boolean;
+            /**
+             * @description Why no price was found; `none` while `priced` is true.
+             * @enum {string}
+             */
+            unpriced_reason?: "none" | "no_price";
+            /**
+             * Format: uuid
+             * @description The price selected. Returned whenever `priced` is true, including when the
+             *     request identified the item indirectly, so that the choice can be confirmed.
+             */
+            price_id?: string;
+            plan_name?: string;
+            /** @description Unit price before discounts, with tax included only where the price includes it. */
+            unit_amount?: components["schemas"]["Money"];
+            /** @description The quantity priced. */
+            quantity?: string;
+            /**
+             * @description Before discounts, including any setup charges. Contains tax only where the price includes it.
+             *     Zero for a priced order item with no immediate charge.
+             */
+            amount?: components["schemas"]["Money"];
+            /** @description Total reduction on this line, including any committed recurring discount. */
+            discount_amount?: components["schemas"]["Money"];
+            /** @description amount minus discount_amount plus tax_amount minus tax_included_amount. */
+            total?: components["schemas"]["Money"];
+            currency: string;
+        };
+        /**
+         * @description A computed price preview, without a saved quote or a price guarantee. No funds or discount
+         *     redemptions are reserved. Amounts use currency and exclude payment from credit grants or balance.
+         */
         Quote: {
+            /**
+             * @description Sum before discounts, less tax already included in the discounted line amounts, as on an
+             *     invoice. Null when any line cannot be priced. Zero for a cancellation-only quote.
+             */
+            subtotal: components["schemas"]["Money"] | null;
+            /** @description Total line discounts. Null when any line cannot be priced; zero for a cancellation-only quote. */
+            discount_amount: components["schemas"]["Money"] | null;
+            /** @description Total tax on the discounted amounts. Null when any line cannot be priced; zero for a cancellation-only quote. */
+            tax_amount: components["schemas"]["Money"] | null;
+            /**
+             * @description The one new discount evaluated for a purchase or order, without applying it. Null when
+             *     none is selected, pricing is incomplete, or the quote targets a renewal list or cancellation.
+             *     A confirmed order instead reports its recorded discount.
+             */
+            discount: components["schemas"]["QuotedDiscount"] | null;
+            lines?: components["schemas"]["QuotedLine"][];
             renewals?: components["schemas"]["QuoteRenewalResult"][];
             /** @description What the cancellation requested would return. Present only when one was requested. */
             cancellation?: components["schemas"]["CancellationRefundPreview"];
             /**
-             * @description What the renewals would charge in total. Amounts to be returned are not netted off it: a
-             *     quote of a cancellation alone has a total of zero, and what it would return is in
-             *     `cancellation`.
+             * @description subtotal minus discount_amount plus tax_amount, before applying credit grants or balance.
+             *     For a purchase or order with no usage estimates, pass this as expected_amount at checkout.
+             *     A renewal list sums separate orders; use each renewal's total when confirming that order.
+             *     Refunds are not netted off: a cancellation-only quote has zero totals and its refund is in
+             *     cancellation. Usage estimates are projections, not checkout amounts.
+             *
+             *     Null when any line could not be priced. What would be owed is not knowable then, and a
+             *     total that silently left the unpriced lines out would read as a smaller bill rather than
+             *     an incomplete one — the per-line `priced` flag is easy to skip, a missing total is not.
              */
-            total: components["schemas"]["Money"];
+            total: components["schemas"]["Money"] | null;
             currency: string;
         };
+        /**
+         * @description The discount selected for this calculation. Its presence in a quote does not apply it or
+         *     reserve a redemption. Discount amounts are reported on the quote and its lines.
+         */
+        QuotedDiscount: {
+            /** @enum {string} */
+            type: "promotion_code" | "account_discount";
+            name: string;
+            /** @description Code text for a promotion_code discount; null for an account_discount. */
+            promotion_code: string | null;
+        };
         /**
          * @description A cancellation to quote: what ending these subscriptions together would return. One mode per
          *     request; to compare, quote `immediate` and `period_end` separately.
@@ -1203,8 +1381,8 @@ export interface components {
          * @description What the cancellation would return, subscription by subscription and in total, as of now. Give
          *     `proration_date` and `refundable_amount` when creating the cancellation.
          *
-         *     - `unused_amount`: before tax, the value of the paid service still unused, whatever the refund
-         *       terms say.
+         *     - `unused_amount`: before tax, the amount paid for the current periods minus the value of the
+         *       time used, valued as refund policy `prorated` describes, whatever the refund terms say.
          *     - `refundable_amount`: what is returned the way it was paid, including the tax paid on it;
          *       `refund_amount` plus `credit_amount`.
          *     - `refund_amount`: the part returned to the balance or to the payment method.
@@ -1415,57 +1593,6 @@ export interface components {
         };
         /** @description Immutable platform service identifier, such as compute, canopy or assistant. */
         ProductID: string;
-        /**
-         * @description Identify a price directly, or select a price for a plan. For each resource give its ID or lookup key, never both. Lookup keys require product_id.
-         *
-         *     A line that gives a meter, `dimensions` or `duration_seconds` estimates usage and is
-         *     priced only at a postpaid price. Such a line is refused with HTTP 400
-         *     `BILLING_PURCHASE_INVALID` when `price_type` is `prepaid` or `one_time`, or when the price
-         *     it names is not postpaid; `meta.field` is `price_type`, `price_id` or `price_lookup_key`
-         *     accordingly. When the plan has no postpaid price, the line is returned unpriced with
-         *     `no_price`.
-         */
-        QuoteLine: {
-            price_lookup_key?: string;
-            plan_lookup_key?: string;
-            meter_lookup_key?: string;
-            /** Format: uuid */
-            price_id?: string;
-            product_id?: components["schemas"]["ProductID"];
-            /** Format: uuid */
-            plan_id?: string;
-            /** Format: uuid */
-            meter_id?: string;
-            /**
-             * @description The attributes the price depends on — region, instance type, token class.
-             *
-             *     Required when the price draws its rates from a price list, which is how anything
-             *     sold by region or by machine type is priced. A price that carries a single unit
-             *     amount, or a ladder, has no attributes to give and takes none.
-             *
-             *     Every attribute the meter declares must be present. A combination with no rate
-             *     covering it is refused rather than priced at zero.
-             */
-            dimensions?: {
-                [key: string]: string;
-            };
-            /**
-             * @description Narrows the selection when a plan offers more than one billing type.
-             * @enum {string}
-             */
-            price_type?: "postpaid" | "prepaid" | "one_time";
-            /** @enum {string} */
-            interval?: "none" | "day" | "month" | "year";
-            interval_count?: number;
-            quantity: string;
-            /**
-             * Format: int64
-             * @description For metered items, how long to price for. This allows an estimate such as "about
-             *     this much per month" to be shown before anything exists. The priced quantity is
-             *     `quantity` multiplied by this duration.
-             */
-            duration_seconds?: number;
-        };
         BillingAccount: {
             /** Format: int64 */
             id: number;
@@ -1817,7 +1944,7 @@ export interface components {
          *     An unresolved channel payment is reused; retries do not apply the grant or balance portions twice.
          *     Without a gateway selection, insufficient account funds fail without starting an online payment.
          */
-        PayRequest: {
+        PayInvoiceRequest: {
             /** @description Required to collect an online remainder. An existing attempt keeps its original gateway. */
             payment_gateway?: string;
             /** @description Required with payment_gateway; for example card, wechat_pay or alipay. */
@@ -1954,7 +2081,11 @@ export interface components {
             failure_reason?: string;
         };
         /**
-         * @description A usage invoice stays `draft` through its month: each charge is added to it as it is priced
+         * @description An order invoice stays `draft` until checkout confirms its discount and final amounts. It
+         *     cannot be collected while draft. Confirmation makes it `open`, or `paid` when its total is zero
+         *     without creating a payment transaction. A quote never changes this status.
+         *
+         *     A usage invoice stays `draft` through its month: each charge is added to it as it is priced
          *     and paid from credits and balance as it goes. It is issued at the end of the month, becoming
          *     `paid` when everything was covered and `open` when something is still owed.
          *
@@ -2004,6 +2135,8 @@ export interface components {
             /** @description Subtotal less discount plus tax. Balance and credit grants are payment sources, not reductions of the receivable. */
             total: components["schemas"]["Money"];
             amount_paid?: components["schemas"]["Money"];
+            /** @description What is still collectible after applied credits and successful payments; never below zero. A draft order invoice is not collectible until checkout confirms it, and a paid or void invoice has none. */
+            amount_due: components["schemas"]["Money"];
             /** Format: date-time */
             period_start?: string | null;
             /**
@@ -2249,7 +2382,10 @@ export interface components {
          *     - `subscription_canceled`: the subscription was canceled and its unused value returned under
          *       its refund terms.
          *     - `future_period_canceled`: a renewal that had not started yet was withdrawn.
-         *     - `downgrade_difference`: the unused value above the new price after a downgrade.
+         *     - `downgrade_difference`: after a downgrade, the remaining value of what was paid, valued as refund
+         *       policy `prorated` describes, minus the new configuration's cost for the remaining time at the
+         *       change item's `refund_monthly_amount` and `refund_hourly_amount`. Nothing is refunded when that is
+         *       zero or less.
          *     - `usage_true_up`: usage priced again over the whole month cost less than was charged.
          *     - `payment_not_applied`: a payment arrived after its invoice could no longer be paid.
          *     - `operator`: made by the platform operator.
@@ -2316,7 +2452,30 @@ export interface components {
             items: components["schemas"]["Subscription"][];
             pagination: components["schemas"]["OffsetPagination"];
         };
-        /** @description An independently billed purchase. Fixed renewals use the agreed recurring_amount and interval; already paid periods retain their original value. Technical state belongs to the owning service. */
+        /**
+         * @description An independently billed purchase relationship, separate from the owning service's resource.
+         *     Placing a new prepaid or postpaid service order creates a pending subscription for each line
+         *     in the same purchase transaction. Its ID is returned on the order item and remains stable
+         *     through checkout and delivery. One order may create several subscriptions, such as an instance,
+         *     its system disk and its address; it has no single subscription ID.
+         *
+         *     Pending and provisioning do not grant service or accrue usage. A service-owned subscription
+         *     becomes provisioning when the owning service accepts the order, and active when the service
+         *     confirms delivery, with started_at set to the confirmed effective time; payment changes neither. Prepaid service periods start
+         *     then; postpaid usage starts only when the service reports actual delivery and metering.
+         *
+         *     One-time delivery may omit a subscription. Renewals reference and extend existing subscriptions
+         *     rather than creating another; a change keeps the subscription ID and switches its terms when it
+         *     takes effect. Canceling or failing an
+         *     unfulfilled purchase closes its pending or provisioning subscriptions without starting a service period.
+         *     Fixed renewals use the agreed recurring_amount and interval; already paid periods retain their
+         *     original value. Technical state belongs to the owning service.
+         *
+         *     A purchased shared capacity limit, such as a regional snapshot count quota, can have its own
+         *     subscription. Activating that capacity confirms delivery of the quota, not individual snapshots.
+         *     Creating or deleting snapshots within it does not create, activate or terminate more subscriptions;
+         *     the owning service enforces current holdings against the purchased count.
+         */
         Subscription: {
             currency: string;
             /** @enum {string} */
@@ -2324,13 +2483,20 @@ export interface components {
             /** @enum {string} */
             interval: "none" | "day" | "month" | "year";
             interval_count?: number;
-            /** @description Whole-subscription prepaid renewal amount, after continuing discounts and before tax. Absent for other billing types. */
+            /**
+             * @description Whole-subscription prepaid renewal amount, after continuing discounts and before tax.
+             *     Pending subscriptions show base terms until checkout confirms any new continuing discount.
+             *     Absent for other billing types.
+             */
             recurring_amount?: string;
             termination_policy?: components["schemas"]["TerminationPolicy"];
             refund_policy?: components["schemas"]["RefundPolicy"];
             /** Format: uuid */
             order_item_id?: string;
-            /** Format: uuid */
+            /**
+             * Format: uuid
+             * @description Present only on subscriptions created by an earlier change that replaced the subscription. A change now keeps the subscription ID.
+             */
             replaces_subscription_id?: string;
             /** Format: uuid */
             coupon_id?: string;
@@ -2378,13 +2544,22 @@ export interface components {
             quantity: string;
             /**
              * Format: date-time
-             * @description Present for prepaid items. Absent for metered ones, which have no end date.
+             * @description End of the prepaid service already activated. Null until a new subscription becomes active,
+             *     even when its purchase has been paid, and for postpaid subscriptions with no prepaid end date.
              */
             paid_until?: string | null;
             auto_renew: boolean;
-            /** @enum {string} */
-            status: "pending" | "active" | "suspended" | "canceled" | "terminated";
-            /** Format: date-time */
+            /**
+             * @description pending means the purchase relationship exists but its order has not been accepted.
+             *     provisioning means the service accepted the order and is delivering. For a service-owned
+             *     purchase, only confirmed delivery moves it to active; paying alone does not.
+             * @enum {string}
+             */
+            status: "pending" | "provisioning" | "active" | "suspended" | "canceled" | "terminated";
+            /**
+             * Format: date-time
+             * @description Confirmed start of service. Null until a new subscription becomes active, including after payment.
+             */
             started_at?: string | null;
             /** Format: date-time */
             ended_at?: string | null;
@@ -2432,7 +2607,9 @@ export interface components {
              *
              *     Leaving both out renews at the price this item already bills at, which a later price
              *     change does not affect. Naming a term that differs from the current one is a fresh
-             *     choice, so it is bought at today's price. Naming the current term changes nothing.
+             *     choice, so it is bought at today's price. Naming the current term changes nothing. A
+             *     term sold at several prices that differ in termination policy is refused with 409
+             *     `BILLING_RENEWAL_OPTION_AMBIGUOUS` unless `termination_policy` is given.
              *
              *     List the terms on offer with the renewal prices operation.
              */
@@ -2442,6 +2619,8 @@ export interface components {
              * @enum {string}
              */
             interval?: "day" | "month" | "year";
+            /** @description With `interval` and `interval_count`, chooses among prices of that term that differ in termination policy. */
+            termination_policy?: components["schemas"]["TerminationPolicy"];
             /** Format: uuid */
             payment_method_id?: string;
             /**
@@ -2480,7 +2659,12 @@ export interface components {
             auto_renew: boolean;
         };
         /**
-         * @description Follows the items. `pending` is not yet accepted and may be paid or unpaid. `active` is
+         * @description pending_checkout has recorded purchase terms but no confirmed checkout; only a deferred order
+         *     with an amount due reaches it, since a zero-total order completes checkout at placement.
+         *     Confirmation moves it to pending. Both pending_checkout
+         *     and pending can expire or be canceled; neither establishes service delivery.
+         *
+         *     Follows the items. `pending` has confirmed checkout, is not yet accepted and may be paid or unpaid. `active` is
          *     accepted with items still being set up. `completed` means every item was set up.
          *     `partially_completed` means some items were set up and the others failed and were
          *     refunded to their original payment sources. `failed` means every item failed and the
@@ -2488,7 +2672,7 @@ export interface components {
          *     nothing was charged.
          * @enum {string}
          */
-        OrderStatus: "pending" | "active" | "completed" | "partially_completed" | "failed" | "canceled";
+        OrderStatus: "pending_checkout" | "pending" | "active" | "completed" | "partially_completed" | "failed" | "canceled";
         /**
          * @description `pending` is waiting to be set up. `completed` was confirmed by the service.
          *     `failed` was not set up and its amount was refunded to the original payment sources.
@@ -2497,13 +2681,19 @@ export interface components {
          * @enum {string}
          */
         OrderItemStatus: "pending" | "completed" | "failed" | "canceled";
+        /**
+         * @description A recorded purchase. pending_checkout requires explicit Billing confirmation before collection
+         *     or acceptance, even without an invoice. Coupon fields describe a discount confirmed at checkout and are absent
+         *     before confirmation; a quote never populates them. A draft invoice contains base purchase
+         *     amounts awaiting checkout. Payment and acceptance remain separate from resource delivery.
+         */
         Order: {
             /** Format: uuid */
             coupon_id?: string;
             coupon?: components["schemas"]["ObjectIdentity"];
             /** Format: uuid */
             promotion_code_id?: string;
-            /** @description Code text frozen when this order applied the coupon. */
+            /** @description Code text frozen when checkout applied the coupon. Absent for an account discount. */
             promotion_code?: string;
             invoice?: components["schemas"]["InvoiceSummary"];
             /** @description How the order was paid. Absent until it is paid. */
@@ -2554,7 +2744,7 @@ export interface components {
             change_effective?: "none" | "immediate" | "period_end";
             /**
              * Format: date-time
-             * @description Acceptance deadline. Only pending orders expire automatically.
+             * @description Acceptance deadline. pending_checkout and pending orders can expire automatically.
              */
             expires_at?: string | null;
             /** Format: date-time */
@@ -2589,75 +2779,6 @@ export interface components {
             brand?: string;
             last4?: string;
         };
-        /** @description Specify lines to check whether the promotion code applies to new purchases and to estimate its discount. Without lines, the response contains the code terms without a purchase-specific applicability decision. */
-        PromotionCodePreviewRequest: {
-            /** Format: int64 */
-            billing_account_id: number;
-            promotion_code: string;
-            /** @description New purchases to test against, in the same shape as a quote. */
-            lines?: components["schemas"]["QuoteLine"][];
-        };
-        /** @description Describes a usable promotion code and its applicability to the requested purchase. Invalid codes return an error response. */
-        PromotionCodePreview: {
-            min_amount?: string;
-            /** @enum {string} */
-            type?: "percentage" | "fixed_amount" | "price_override" | "free_setup";
-            recurring?: boolean;
-            recurring_cycles?: number;
-            name?: string;
-            /** @description For a fixed-amount discount. */
-            amount?: components["schemas"]["Money"];
-            /** @description For a percentage discount. */
-            percent_off?: string;
-            max_discount?: components["schemas"]["Money"];
-            currency?: string;
-            /**
-             * @description What it may be used for. Present whether or not a purchase was given, so that the
-             *     terms can be shown before anything is chosen.
-             */
-            applies_to?: components["schemas"]["Applicability"];
-            /**
-             * @description The terms in one sentence, ready to display — for example "Compute, new purchases
-             *     only, from 100.00" or "No restriction on product or purchase type".
-             */
-            summary?: string;
-            /** Format: date-time */
-            valid_until?: string | null;
-            /**
-             * @description Whether it applies to the purchase given in `lines`. Absent when no purchase was
-             *     given.
-             */
-            applicable?: boolean;
-            applicable_reason?: components["schemas"]["PromotionCodeRejection"];
-            /**
-             * @description The total of the lines that match the restrictions. This is what the threshold is
-             *     measured against, not the order total.
-             */
-            qualifying_amount?: components["schemas"]["Money"];
-            /**
-             * @description How much more of a qualifying purchase is needed to reach the threshold. `"0"` once
-             *     it is met.
-             */
-            shortfall?: components["schemas"]["Money"];
-            /**
-             * @description What it would take off this purchase. An estimate: the amount is settled at the
-             *     moment the order is placed.
-             */
-            estimated_discount?: components["schemas"]["Money"];
-        };
-        /**
-         * @description Why a code cannot be used. `none` when it can.
-         *
-         *     `operation_not_covered` means the code is limited to certain purchase actions — a
-         *     first-purchase code presented for a renewal, for example.
-         *
-         *     `term_not_covered` means the code is limited to certain term lengths. A purchase with
-         *     no term, such as metered usage, is reported the same way.
-         *
-         *     `below_minimum` is accompanied by `shortfall`.
-         * @enum {string}
-         */
-        PromotionCodeRejection: "none" | "not_found" | "expired" | "not_yet_valid" | "exhausted" | "already_redeemed" | "currency_mismatch" | "product_not_covered" | "plan_not_covered" | "price_not_covered" | "price_type_not_covered" | "operation_not_covered" | "term_not_covered" | "not_first_purchase" | "below_minimum";
         /**
          * @description Which purchase this applies to. `upgrade` and `downgrade` are told apart by money: a change
          *     that costs more for the remainder of the period is an upgrade, one that returns money
@@ -2709,7 +2830,7 @@ export interface components {
             items: components["schemas"]["Discount"][];
             pagination: components["schemas"]["OffsetPagination"];
         };
-        /** @description A price's display terms, including retired prices referenced by an applicability list. */
+        /** @description A price's display terms, including archived prices referenced by an applicability list. */
         PriceOption: {
             product: components["schemas"]["Product"];
             plan: components["schemas"]["ObjectIdentity"];
@@ -2747,19 +2868,39 @@ export interface components {
             /** @description The longest term a purchase may have, in months. */
             max_term_months?: number;
         };
-        /** @description Frozen purchase terms. Monetary fields come from related invoice-line snapshots and are absent when there is no immediate invoice. Later catalog changes do not reprice this line. */
+        /**
+         * @description Frozen purchase terms. Monetary fields come from related invoice-line snapshots and are absent
+         *     when there is no immediate invoice. Later catalog changes do not reprice this line. A new service
+         *     purchase creates its pending subscription when this item is recorded, not when payment succeeds.
+         */
         OrderItem: {
             position?: number;
             configuration?: {
                 [key: string]: unknown;
             };
-            /** Format: uuid */
+            /**
+             * Format: uuid
+             * @description Stable Billing subscription ID. A new prepaid or postpaid service purchase returns the
+             *     pending subscription here; renewals and changes reference the existing subscription, which
+             *     keeps its ID. Absent for delivery without a subscription. This is not a business resource ID.
+             */
             subscription_id?: string;
             /** @enum {string} */
             interval: "none" | "day" | "month" | "year";
             interval_count?: number;
             termination_policy?: components["schemas"]["TerminationPolicy"];
             refund_policy?: components["schemas"]["RefundPolicy"];
+            /**
+             * @description Prepaid items only: the plan's one-month prepaid price for this item's quantity before tax, frozen
+             *     at purchase, used to value time used under a prorated refund or a downgrade. Null when the plan has
+             *     no prepaid period shorter than the one bought.
+             */
+            refund_monthly_amount?: string | null;
+            /**
+             * @description Prepaid items only: the plan's postpaid hourly price for this item's quantity before tax, frozen at
+             *     purchase, used for time used short of a full month. Null when the plan has no postpaid price.
+             */
+            refund_hourly_amount?: string | null;
             completes_on_payment: boolean;
             recurring_amount?: string;
             setup_amount?: string;
@@ -2794,14 +2935,16 @@ export interface components {
             quantity: string;
             /**
              * @description The unit amount of the price this line is charged under. Absent for a tiered price, which has no
-             *     single unit amount, and for a change that takes effect at once, which is charged the prorated
-             *     difference.
+             *     single unit amount, and for a change that takes effect at once, which is charged as `gross_amount`
+             *     describes.
              */
             unit_amount?: components["schemas"]["Money"];
             /**
              * @description Before discounts: the price applied to the quantity, which for a per-unit price is `unit_amount`
-             *     times `quantity`; a minimum charge can make it higher. For a change that takes effect at once it is
-             *     the prorated difference. The setup fee is not part of it; see `setup_amount`.
+             *     times `quantity`; a minimum charge can make it higher. For an upgrade that takes effect at once it is
+             *     the new price minus the old price for the time left in the paid period, both at the subscription's
+             *     own period price, and the period end does not move; a downgrade charges nothing and may refund the
+             *     difference instead. A change between equal period prices charges and refunds nothing. The setup fee is not part of it; see `setup_amount`.
              *
              *     Under an inclusive tax rate it includes tax, as the price does, and the included part is
              *     `tax_included_amount`. A renewal at the agreed terms is the exception: the agreed amount excludes
@@ -2891,7 +3034,11 @@ export interface components {
             items: components["schemas"]["Entitlement"][];
             pagination: components["schemas"]["OffsetPagination"];
         };
-        /** @description Purchase-related invoice amounts, without account contact details or payment methods. Absent on an order with no immediate invoice. */
+        /**
+         * @description Purchase-related invoice amounts, without account contact details or payment methods. A draft
+         *     order invoice shows base amounts awaiting checkout, not a confirmed discount or collectible total.
+         *     Absent when no invoice has been created; absence does not establish acceptance or delivery.
+         */
         InvoiceSummary: {
             /** Format: uuid */
             id: string;
@@ -2909,6 +3056,8 @@ export interface components {
             tax_amount: string;
             total: string;
             amount_paid: string;
+            /** @description What is still collectible after applied credits and successful payments; never below zero. */
+            amount_due: string;
             amount_refunded: string;
             /** Format: date-time */
             due_at?: string;
@@ -3522,7 +3671,7 @@ export interface operations {
         };
         requestBody?: {
             content: {
-                "application/json": components["schemas"]["PayRequest"];
+                "application/json": components["schemas"]["PayInvoiceRequest"];
             };
         };
         responses: {
@@ -4176,31 +4325,6 @@ export interface operations {
             default: components["responses"]["Error"];
         };
     };
-    "preview-promotion-code": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        requestBody: {
-            content: {
-                "application/json": components["schemas"]["PromotionCodePreviewRequest"];
-            };
-        };
-        responses: {
-            /** @description OK */
-            200: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["PromotionCodePreview"];
-                };
-            };
-            default: components["responses"]["Error"];
-        };
-    };
     "list-allowances": {
         parameters: {
             query?: {
@@ -4289,6 +4413,48 @@ export interface operations {
             default: components["responses"]["Error"];
         };
     };
+    "checkout-order": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                orderId: components["parameters"]["OrderId"];
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                /**
+                 * @example {
+                 *       "promotion_code": "WELCOME",
+                 *       "expected_amount": "90.00"
+                 *     }
+                 */
+                "application/json": components["schemas"]["CheckoutOrderRequest"];
+            };
+        };
+        responses: {
+            /** @description The order with confirmed checkout terms and its invoice, when applicable. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Order"];
+                };
+            };
+            /** @description The order no longer permits checkout or another discount has already been confirmed. */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Error"];
+                };
+            };
+            default: components["responses"]["Error"];
+        };
+    };
     "cancel-order": {
         parameters: {
             query?: never;