@leaflow/sdk 0.101.0 → 0.103.0

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

@@ -171,7 +171,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
@@ -247,8 +247,8 @@ export interface paths {
         };
         /**
          * List project orders
-         * @description An order awaiting payment shows what is outstanding. Paying it is done from the billing
-         *     centre by the account owner.
+         * @description A draft order invoice shows base amounts awaiting checkout. A confirmed invoice shows what
+         *     is outstanding. Checkout and payment are performed in the billing centre by the account owner.
          */
         get: operations["list-project-orders"];
         put?: never;
@@ -314,15 +314,27 @@ export interface paths {
         put?: never;
         /**
          * Quote for a project
-         * @description Priced in the project billing account's currency, and at any rate negotiated for that account.
-         *     Nothing is reserved and nothing is recorded, so this may be called as often as required.
+         * @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.
          *
-         *     Prices may change between quoting and ordering. An order is charged at the price in
-         *     effect when it is placed, so a quote should be refreshed before a final confirmation is
-         *     shown.
+         *     New purchases use the project's current billing account and currency. With order_id, the order
+         *     must belong to this project; its recorded purchase terms, billing account and currency are used.
+         *     An optional promotion_code previews one code for the purchase or order. 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 through
+         *     Billing; 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.
+         *
+         *     Prices may change before an order is created; confirmed purchase terms are not repriced from
+         *     today's catalog. Usage estimates describe future usage and are not checkout amounts. They do
+         *     not accept a promotion code, including when mixed with fixed purchase lines.
          *
          *     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.
          *
          *     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 lines or
@@ -331,8 +343,8 @@ export interface paths {
          *     amount is not checked. Give the returned `cancellation.proration_date` and
          *     `cancellation.refundable_amount` when creating it.
          *
-         *     Returns 404 when the project has no billing account, or when a subscription to be renewed or
-         *     canceled does not belong to this project.
+         *     Returns 404 when the project has no billing account for a new purchase quote, or when the order
+         *     or a subscription to be renewed or canceled does not belong to this project.
          */
         post: operations["create-project-quote"];
         delete?: never;
@@ -421,7 +433,16 @@ 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";
@@ -438,8 +459,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.
@@ -653,37 +674,17 @@ export interface components {
         /**
          * @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`.
+         *     Charges for future usage are not estimated here; the service that sells the product quotes
+         *     them with its purchase.
          */
         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}
@@ -693,18 +694,13 @@ export interface components {
             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;
         };
         /**
          * @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 */
@@ -714,6 +710,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
@@ -721,21 +719,49 @@ export interface components {
             periods?: number;
         };
         /**
-         * @description Specify lines for new purchases and renewals for existing subscriptions, or one cancellation on
-         *     its own. The total includes all requested lines and renewals.
+         * @description Quote exactly one target: purchase `lines`, 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: {
+            /**
+             * @description A proposed purchase, priced with the project's current billing account. Future usage
+             *     estimates cannot be combined with a promotion code or used as a checkout amount.
+             */
             lines?: components["schemas"]["QuoteLine"][];
+            /**
+             * 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;
         };
-        QuoteLineResult: {
-            /** @description Tax included in the account quote. Absent in public catalogue estimates. */
+        /**
+         * @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 Tax already included in the displayed price. */
+            /** @description The part of tax_amount already contained in amount minus discount_amount. */
             tax_included_amount?: components["schemas"]["Money"];
-            /** @description Which line of the request this answers. */
+            /** @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.
              *
@@ -749,14 +775,9 @@ export interface components {
             priced: boolean;
             /**
              * @description Why no price was found; `none` while `priced` is true.
-             *
-             *     The last four are told apart because their remedies differ: the price points
-             *     at no price list, the list holds no rate for that meter, that exact combination
-             *     of attributes is not configured, or it is configured but nothing is in effect
-             *     at the moment asked about.
              * @enum {string}
              */
-            unpriced_reason?: "none" | "no_price" | "no_rate_card" | "no_meter" | "no_dimensions" | "no_effective_rule";
+            unpriced_reason?: "none" | "no_price";
             /**
              * Format: uuid
              * @description The price selected. Returned whenever `priced` is true, including when the
@@ -764,14 +785,19 @@ export interface components {
              */
             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 The quantity actually priced. When `duration_seconds` is given, it is the requested
-             *     `quantity` multiplied by that duration.
+             * @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.
              */
-            quantity?: string;
-            /** @description Not rounded. Round only for display. */
             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;
         };
         /**
@@ -811,23 +837,55 @@ export interface components {
              */
             total: components["schemas"]["Money"];
         };
+        /**
+         * @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: {
-            lines?: components["schemas"]["QuoteLineResult"][];
+            /**
+             * @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 would be owed in total, renewals included. 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"] | null;
+            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 narrow view of the project's billing account, restricted to what a project member needs in order
          *     to know whether the project's resources will keep running.
@@ -870,7 +928,11 @@ export interface components {
             currency: string;
         };
         /**
-         * @description `refunded` means the invoice was paid and has since been refunded in full; a partial refund
+         * @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.
+         *
+         *     `refunded` means the invoice was paid and has since been refunded in full; a partial refund
          *     leaves it `paid`, with the refunded part in `amount_refunded`.
          *
          *     `void` means the invoice will not be paid and holds no money: nothing was paid, or its order
@@ -946,7 +1008,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} */
@@ -954,13 +1039,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;
@@ -1008,13 +1100,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;
@@ -1063,7 +1164,12 @@ export interface components {
             pagination: components["schemas"]["OffsetPagination"];
         };
         /**
-         * @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
@@ -1071,7 +1177,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.
@@ -1080,13 +1186,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. */
@@ -1137,7 +1249,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 */
@@ -1172,19 +1284,39 @@ export interface components {
             brand?: string;
             last4?: string;
         };
-        /** @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;
@@ -1219,14 +1351,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
@@ -1316,7 +1450,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;
@@ -1334,6 +1472,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;