feat(api): expose booked and spendable credit balances

api/spec/packages/aip-client-javascript/src/models/operations/customers.ts

@@ -267,7 +267,9 @@ export type ListCreditGrantsResponse = CreditGrantPagePaginatedResponse
 
 export interface GetCustomerCreditBalanceQuery {
   /**
-   * Return the credit balance as of this timestamp.
+   * Return credit balances at this timestamp using all currently recorded postings,
+   * including corrections recorded later. This is not a snapshot of what was known
+   * at the requested time.
    *
    * Defaults to the current time. Historical responses return `live` as zero because
    * live charge impacts are only available for current balances.

api/spec/packages/aip-client-javascript/src/models/schemas.ts

@@ -4355,7 +4355,9 @@ export const creditBalance = z
     currency: billingCurrencyCode,
     customCurrency: currencyCustomReference.optional(),
     live: numeric,
+    booked: numeric,
     settled: numeric,
+    spendable: numeric,
     pending: numeric,
   })
   .describe('The credit balance by currency.')
@@ -4388,7 +4390,10 @@ export const creditTransaction = z
         before: numeric,
         after: numeric,
       })
-      .describe('The available balance before and after the transaction.'),
+
+      .describe(
+        'The booked credit balance before and after the transaction, including credit-only advance debt.',
+      ),
   })
 
   .describe(
@@ -14112,7 +14117,9 @@ export const creditBalanceWire = z
     currency: billingCurrencyCodeWire,
     custom_currency: currencyCustomReferenceWire.optional(),
     live: numericWire,
+    booked: numericWire,
     settled: numericWire,
+    spendable: numericWire,
     pending: numericWire,
   })
   .describe('The credit balance by currency.')
@@ -14145,7 +14152,10 @@ export const creditTransactionWire = z
         before: numericWire,
         after: numericWire,
       })
-      .describe('The available balance before and after the transaction.'),
+
+      .describe(
+        'The booked credit balance before and after the transaction, including credit-only advance debt.',
+      ),
   })
 
   .describe(

api/spec/packages/aip-client-javascript/src/models/types.ts

@@ -3235,14 +3235,27 @@ export interface CreditBalance {
   /** Managed currency reference. Present only for custom currencies. */
   customCurrency?: CurrencyCustomReference
   /**
-   * Credits available after applying currently live charge impacts.
+   * Spendable balance after applying currently live, unbooked charge impacts. Can be
+   * negative when usage exceeds available credit.
    *
    * Always zero for historical balance queries using the `timestamp` parameter
    * because live charge impacts cannot be reconstructed historically.
    */
   live: string
-  /** Credits that have been booked on the ledger as of the balance timestamp. */
+  /**
+   * Credits that have been booked on the ledger as of the balance timestamp,
+   * including credit-only advance debt. Can be negative.
+   */
+  booked: string
+  /** Deprecated alias for `booked`. Always returns the same value. */
   settled: string
+  /**
+   * Spendable credit at the balance timestamp, including any credit-only advance
+   * debt. Preserves credit already committed to later usage. Future grants cannot be
+   * spent early; scheduled expiry reduces availability when it takes effect. Can be
+   * negative when advance debt exceeds spendable credit.
+   */
+  spendable: string
   /**
    * Credits that have been granted but are not yet written to the ledger, or are
    * written to the ledger with a future booked time.
@@ -3286,7 +3299,10 @@ export interface CreditTransaction {
    * values reduce balance.
    */
   amount: string
-  /** The available balance before and after the transaction. */
+  /**
+   * The booked credit balance before and after the transaction, including
+   * credit-only advance debt.
+   */
   availableBalance: { before: string; after: string }
 }
 

api/spec/packages/aip/src/customers/credits/balance.tsp

@@ -39,7 +39,8 @@ model CreditBalance {
   custom_currency?: Shared.ResourceReference<Currencies.CurrencyCustom>;
 
   /**
-   * Credits available after applying currently live charge impacts.
+   * Spendable balance after applying currently live, unbooked charge impacts. Can be
+   * negative when usage exceeds available credit.
    *
    * Always zero for historical balance queries using the `timestamp` parameter
    * because live charge impacts cannot be reconstructed historically.
@@ -49,12 +50,33 @@ model CreditBalance {
   live: Shared.Numeric;
 
   /**
-   * Credits that have been booked on the ledger as of the balance timestamp.
+   * Credits that have been booked on the ledger as of the balance timestamp,
+   * including credit-only advance debt. Can be negative.
    */
   @visibility(Lifecycle.Read)
   @example("150.00")
+  booked: Shared.Numeric;
+
+  /**
+   * Deprecated alias for `booked`. Always returns the same value.
+   *
+   * @deprecated Use `booked` instead.
+   */
+  #deprecated "Use booked instead"
+  @visibility(Lifecycle.Read)
+  @example("150.00")
   settled: Shared.Numeric;
 
+  /**
+   * Spendable credit at the balance timestamp, including any credit-only advance
+   * debt. Preserves credit already committed to later usage. Future grants cannot be
+   * spent early; scheduled expiry reduces availability when it takes effect. Can be
+   * negative when advance debt exceeds spendable credit.
+   */
+  @visibility(Lifecycle.Read)
+  @example("120.00")
+  spendable: Shared.Numeric;
+
   /**
    * Credits that have been granted but are not yet written to the ledger, or are
    * written to the ledger with a future booked time.

api/spec/packages/aip/src/customers/credits/ledger.tsp

@@ -118,7 +118,8 @@ model CreditTransaction {
   amount: Shared.Numeric;
 
   /**
-   * The available balance before and after the transaction.
+   * The booked credit balance before and after the transaction, including
+   * credit-only advance debt.
    */
   @visibility(Lifecycle.Read)
   available_balance: {

api/spec/packages/aip/src/customers/credits/operations.tsp

@@ -209,7 +209,9 @@ namespace Credits.Balance {
       @path customerId: Shared.ULID,
 
       /**
-       * Return the credit balance as of this timestamp.
+       * Return credit balances at this timestamp using all currently recorded postings,
+       * including corrections recorded later. This is not a snapshot of what was known
+       * at the requested time.
        *
        * Defaults to the current time. Historical responses return `live` as zero because
        * live charge impacts are only available for current balances.