@metronome/sdk 3.4.1 → 3.6.0

package/resources/v1/contracts/contracts.d.ts

@@ -17,8 +17,8 @@ export declare class Contracts extends APIResource {
     /**
      * Contracts define a customer's products, pricing, discounts, access duration, and
      * billing configuration. Contracts serve as the central billing agreement for both
-     * PLG and Enterprise customers, you can automatically customers access to your
-     * products and services directly from your product or CRM.
+     * PLG and Enterprise customers. You can automatically grant customers access to
+     * your products and services directly from your product or CRM.
      *
      * ### Use this endpoint to:
      *
@@ -339,6 +339,10 @@ export declare class Contracts extends APIResource {
      *
      * ### Usage guidelines:
      *
+     * - **Balance ledger details**: Use the
+     *   [listBalances](https://docs.metronome.com/api-reference/credits-and-commits/list-balances)
+     *   endpoint instead to understand detailed ledger drawdowns for each individual
+     *   balance
      * - **Draft invoice handling**: Use `invoice_inclusion_mode` to control whether
      *   pending draft invoice deductions are included (`FINALIZED_AND_DRAFT`, the
      *   default) or excluded (`FINALIZED`) from the balance calculation
@@ -395,6 +399,9 @@ export declare class Contracts extends APIResource {
      *
      * ### Usage guidelines:
      *
+     * - Use the
+     *   [getNetBalance](https://docs.metronome.com/api-reference/credits-and-commits/get-the-net-balance-of-a-customer)
+     *   endpoint to retrieve a single combined current balance
      * - Date filtering: Use `effective_before` to include only balances with access
      *   before a specific date (exclusive)
      * - Set `include_balance=true` for calculated balance amounts on each commit or
@@ -420,6 +427,49 @@ export declare class Contracts extends APIResource {
      * ```
      */
     listBalances(body: ContractListBalancesParams, options?: RequestOptions): PagePromise<ContractListBalancesResponsesBodyCursorPage, ContractListBalancesResponse>;
+    /**
+     * Retrieve detailed balance for seat-based credits and commits from the contract's
+     * subscriptions, broken down by individual seats.
+     *
+     * ### Use this endpoint to:
+     *
+     * - Display per-seat balance information in customer dashboards
+     * - Filter balance data by subscription or specific seats
+     *
+     * ### Key response fields:
+     *
+     * An array of seat balance objects containing:
+     *
+     * - Seat id
+     * - Balance: current total balance across all commits and credits
+     *
+     * ### Usage guidelines:
+     *
+     * - Date filtering: use `covering_date` OR `starting_at`/`ending_before` to filter
+     *   balance data by time range
+     * - Set `include_credits_and_commits=true` for detailed commits and credits
+     *   breakdown per seat
+     * - Set `include_ledgers=true` for detailed transaction history per commit/credit
+     *   per seat
+     *
+     * @example
+     * ```ts
+     * const response = await client.v1.contracts.listSeatBalances(
+     *   {
+     *     contract_id: 'd7abd0cd-4ae9-4db7-8676-e986a4ebd8dc',
+     *     customer_id: '13117714-3f05-48e5-a6e9-a66093f13b4d',
+     *     covering_date: '2024-03-01T00:00:00.000Z',
+     *     include_credits_and_commits: true,
+     *     include_ledgers: true,
+     *     limit: 25,
+     *     subscription_ids: [
+     *       '8deed800-1b7a-495d-a207-6c52bac54dc9',
+     *     ],
+     *   },
+     * );
+     * ```
+     */
+    listSeatBalances(body: ContractListSeatBalancesParams, options?: RequestOptions): APIPromise<ContractListSeatBalancesResponse>;
     /**
      * For a specific customer and contract, get the rates at a specific point in time.
      * This endpoint takes the contract's rate card into consideration, including
@@ -584,6 +634,134 @@ export declare namespace ContractGetNetBalanceResponse {
     }
 }
 export type ContractListBalancesResponse = Shared.Commit | Shared.Credit;
+export interface ContractListSeatBalancesResponse {
+    data: Array<ContractListSeatBalancesResponse.Data>;
+    pagination: ContractListSeatBalancesResponse.Pagination;
+}
+export declare namespace ContractListSeatBalancesResponse {
+    interface Data {
+        balances: Array<Data.Balance>;
+        /**
+         * The unique identifier for the seat
+         */
+        seat_id: string;
+        /**
+         * Array of commits applicable to this seat with their balances
+         */
+        commits?: Array<Data.Commit> | null;
+        /**
+         * Array of credits applicable to this seat with their balances
+         */
+        credits?: Array<Data.Credit>;
+    }
+    namespace Data {
+        interface Balance {
+            /**
+             * The total balance across all commits and credits for this seat, of this credit
+             * type.
+             */
+            balance: number;
+            credit_type_id: string;
+            /**
+             * The total initial balances of all commits and credits for this seat, of this
+             * credit type.
+             */
+            starting_balance: number;
+        }
+        interface Commit {
+            /**
+             * The commit or credit ID
+             */
+            id: string;
+            /**
+             * The current balance for this commit for this specific seat
+             */
+            balance: number;
+            /**
+             * The datetime when the commit becomes active
+             */
+            start_date: string;
+            /**
+             * The datetime when the commit expires
+             */
+            end_date?: string | null;
+            /**
+             * Transaction history for this commit for this seat (only included if
+             * include_ledgers=true)
+             */
+            ledger_entries?: Array<Commit.LedgerEntry>;
+        }
+        namespace Commit {
+            interface LedgerEntry {
+                /**
+                 * Amount of the ledger entry
+                 */
+                amount: number;
+                /**
+                 * The datetime when the ledger is created
+                 */
+                timestamp: string;
+                /**
+                 * Commit ledger type
+                 */
+                type: 'PREPAID_COMMIT_SEGMENT_START' | 'PREPAID_COMMIT_AUTOMATED_INVOICE_DEDUCTION' | 'PREPAID_COMMIT_ROLLOVER' | 'PREPAID_COMMIT_EXPIRATION' | 'PREPAID_COMMIT_CANCELED' | 'PREPAID_COMMIT_CREDITED' | 'PREPAID_COMMIT_MANUAL' | 'PREPAID_COMMIT_SEAT_BASED_ADJUSTMENT';
+            }
+        }
+        interface Credit {
+            /**
+             * The credit ID
+             */
+            id: string;
+            /**
+             * The current balance for this credit for this specific seat
+             */
+            balance: number;
+            /**
+             * The datetime when the credit becomes active
+             */
+            start_date: string;
+            /**
+             * The datetime when the credit expires
+             */
+            end_date?: string | null;
+            /**
+             * Transaction history for this credit for this seat (only included if
+             * include_ledgers=true)
+             */
+            ledger_entries?: Array<Credit.LedgerEntry>;
+        }
+        namespace Credit {
+            interface LedgerEntry {
+                /**
+                 * Amount of the ledger entry
+                 */
+                amount: number;
+                /**
+                 * The datetime when the ledger is created
+                 */
+                timestamp: string;
+                /**
+                 * Credit ledger type
+                 */
+                type: 'CREDIT_SEGMENT_START' | 'CREDIT_AUTOMATED_INVOICE_DEDUCTION' | 'CREDIT_EXPIRATION' | 'CREDIT_CANCELED' | 'CREDIT_CREDITED' | 'CREDIT_MANUAL' | 'CREDIT_SEAT_BASED_ADJUSTMENT' | 'CREDIT_ROLLOVER';
+            }
+        }
+    }
+    interface Pagination {
+        /**
+         * Number of seats available to fetch in the next page
+         */
+        seats_available_for_next_page: number;
+        /**
+         * Number of seats included in this response
+         */
+        seats_included: number;
+        /**
+         * Token to retrieve the next page of results. Null if no more pages available
+         */
+        next_page?: string | null;
+    }
+}
 export interface ContractRetrieveRateScheduleResponse {
     data: Array<ContractRetrieveRateScheduleResponse.Data>;
     next_page?: string | null;
@@ -695,7 +873,7 @@ export interface ContractCreateParams {
     /**
      * If provided, provisions a customer on a package instead of creating a
      * traditional contract. When specified, only customer_id, starting_at, package_id,
-     * and uniqueness_key are allowed.
+     * uniqueness_key, transition, and custom_fields are allowed.
      */
     package_id?: string;
     prepaid_balance_threshold_configuration?: Shared.PrepaidBalanceThresholdConfiguration;
@@ -829,10 +1007,6 @@ export declare namespace ContractCreateParams {
          * This field's availability is dependent on your client's configuration.
          */
         netsuite_sales_order_id?: string;
-        /**
-         * optionally payment gate this commit
-         */
-        payment_gate_config?: Commit.PaymentGateConfig;
         /**
          * If multiple commits are applicable, the one with the lower priority will apply
          * first.
@@ -970,76 +1144,6 @@ export declare namespace ContractCreateParams {
                 unit_price?: number;
             }
         }
-        /**
-         * optionally payment gate this commit
-         */
-        interface PaymentGateConfig {
-            /**
-             * Gate access to the commit balance based on successful collection of payment.
-             * Select STRIPE for Metronome to facilitate payment via Stripe. Select EXTERNAL to
-             * facilitate payment using your own payment integration. Select NONE if you do not
-             * wish to payment gate the commit balance.
-             */
-            payment_gate_type: 'NONE' | 'STRIPE' | 'EXTERNAL';
-            /**
-             * Only applicable if using PRECALCULATED as your tax type.
-             */
-            precalculated_tax_config?: PaymentGateConfig.PrecalculatedTaxConfig;
-            /**
-             * Only applicable if using STRIPE as your payment gate type.
-             */
-            stripe_config?: PaymentGateConfig.StripeConfig;
-            /**
-             * Stripe tax is only supported for Stripe payment gateway. Select NONE if you do
-             * not wish Metronome to calculate tax on your behalf. Leaving this field blank
-             * will default to NONE.
-             */
-            tax_type?: 'NONE' | 'STRIPE' | 'ANROK' | 'PRECALCULATED';
-        }
-        namespace PaymentGateConfig {
-            /**
-             * Only applicable if using PRECALCULATED as your tax type.
-             */
-            interface PrecalculatedTaxConfig {
-                /**
-                 * Amount of tax to be applied. This should be in the same currency and
-                 * denomination as the commit's invoice schedule
-                 */
-                tax_amount: number;
-                /**
-                 * Name of the tax to be applied. This may be used in an invoice line item
-                 * description.
-                 */
-                tax_name?: string;
-            }
-            /**
-             * Only applicable if using STRIPE as your payment gate type.
-             */
-            interface StripeConfig {
-                /**
-                 * If left blank, will default to INVOICE
-                 */
-                payment_type: 'INVOICE' | 'PAYMENT_INTENT';
-                /**
-                 * Metadata to be added to the Stripe invoice. Only applicable if using INVOICE as
-                 * your payment type.
-                 */
-                invoice_metadata?: {
-                    [key: string]: string;
-                };
-                /**
-                 * If true, the payment will be made assuming the customer is present (i.e. on
-                 * session).
-                 *
-                 * If false, the payment will be made assuming the customer is not present (i.e.
-                 * off session). For cardholders from a country with an e-mandate requirement (e.g.
-                 * India), the payment may be declined.
-                 *
-                 * If left blank, will default to false.
-                 */
-                on_session_payment?: boolean;
-            }
-        }
     }
     interface Credit {
         /**
@@ -1373,13 +1477,6 @@ export declare namespace ContractCreateParams {
              * commits created by the specified recurring commit ids.
              */
             recurring_commit_ids?: Array<string>;
-            /**
-             * Can only be used for commit specific overrides. Must be used in conjunction with
-             * one of `product_id`, `product_tags`, `pricing_group_values`, or
-             * `presentation_group_values`. If provided, the override will only apply to
-             * credits created by the specified recurring credit ids.
-             */
-            recurring_credit_ids?: Array<string>;
         }
         /**
          * Required for OVERWRITE type.
@@ -2201,10 +2298,6 @@ export declare namespace ContractAmendParams {
          * This field's availability is dependent on your client's configuration.
          */
         netsuite_sales_order_id?: string;
-        /**
-         * optionally payment gate this commit
-         */
-        payment_gate_config?: Commit.PaymentGateConfig;
         /**
          * If multiple commits are applicable, the one with the lower priority will apply
          * first.
@@ -2342,76 +2435,6 @@ export declare namespace ContractAmendParams {
                 unit_price?: number;
             }
         }
-        /**
-         * optionally payment gate this commit
-         */
-        interface PaymentGateConfig {
-            /**
-             * Gate access to the commit balance based on successful collection of payment.
-             * Select STRIPE for Metronome to facilitate payment via Stripe. Select EXTERNAL to
-             * facilitate payment using your own payment integration. Select NONE if you do not
-             * wish to payment gate the commit balance.
-             */
-            payment_gate_type: 'NONE' | 'STRIPE' | 'EXTERNAL';
-            /**
-             * Only applicable if using PRECALCULATED as your tax type.
-             */
-            precalculated_tax_config?: PaymentGateConfig.PrecalculatedTaxConfig;
-            /**
-             * Only applicable if using STRIPE as your payment gate type.
-             */
-            stripe_config?: PaymentGateConfig.StripeConfig;
-            /**
-             * Stripe tax is only supported for Stripe payment gateway. Select NONE if you do
-             * not wish Metronome to calculate tax on your behalf. Leaving this field blank
-             * will default to NONE.
-             */
-            tax_type?: 'NONE' | 'STRIPE' | 'ANROK' | 'PRECALCULATED';
-        }
-        namespace PaymentGateConfig {
-            /**
-             * Only applicable if using PRECALCULATED as your tax type.
-             */
-            interface PrecalculatedTaxConfig {
-                /**
-                 * Amount of tax to be applied. This should be in the same currency and
-                 * denomination as the commit's invoice schedule
-                 */
-                tax_amount: number;
-                /**
-                 * Name of the tax to be applied. This may be used in an invoice line item
-                 * description.
-                 */
-                tax_name?: string;
-            }
-            /**
-             * Only applicable if using STRIPE as your payment gate type.
-             */
-            interface StripeConfig {
-                /**
-                 * If left blank, will default to INVOICE
-                 */
-                payment_type: 'INVOICE' | 'PAYMENT_INTENT';
-                /**
-                 * Metadata to be added to the Stripe invoice. Only applicable if using INVOICE as
-                 * your payment type.
-                 */
-                invoice_metadata?: {
-                    [key: string]: string;
-                };
-                /**
-                 * If true, the payment will be made assuming the customer is present (i.e. on
-                 * session).
-                 *
-                 * If false, the payment will be made assuming the customer is not present (i.e.
-                 * off session). For cardholders from a country with an e-mandate requirement (e.g.
-                 * India), the payment may be declined.
-                 *
-                 * If left blank, will default to false.
-                 */
-                on_session_payment?: boolean;
-            }
-        }
     }
     interface Credit {
         /**
@@ -2704,13 +2727,6 @@ export declare namespace ContractAmendParams {
              * commits created by the specified recurring commit ids.
              */
             recurring_commit_ids?: Array<string>;
-            /**
-             * Can only be used for commit specific overrides. Must be used in conjunction with
-             * one of `product_id`, `product_tags`, `pricing_group_values`, or
-             * `presentation_group_values`. If provided, the override will only apply to
-             * credits created by the specified recurring credit ids.
-             */
-            recurring_credit_ids?: Array<string>;
         }
         /**
          * Required for OVERWRITE type.
@@ -3041,6 +3057,64 @@ export interface ContractListBalancesParams extends BodyCursorPageParams {
      */
     starting_at?: string;
 }
+export interface ContractListSeatBalancesParams {
+    /**
+     * The contract ID to retrieve seat balances for
+     */
+    contract_id: string;
+    /**
+     * The customer ID to retrieve seat balances for
+     */
+    customer_id: string;
+    /**
+     * Include only commits or credits with access that cover this specific date
+     * (cannot be used with starting_at or ending_before).
+     */
+    covering_date?: string;
+    /**
+     * Page token from a previous response to retrieve the next page
+     */
+    cursor?: string;
+    /**
+     * Include only commits or credits with access effective on or before this date
+     * (cannot be used with covering_date).
+     */
+    effective_before?: string;
+    /**
+     * Include credits and commits in the response
+     */
+    include_credits_and_commits?: boolean;
+    /**
+     * Include ledger entries for each commit and commit. `include_credits_and_commits`
+     * must be set to `true` for `include_ledgers=true` to apply.
+     */
+    include_ledgers?: boolean;
+    /**
+     * Maximum number of seats to return. Range: 1-100. Default: 25. When
+     * `include_credits_and_commits = true`, if the total commits/credits across all
+     * seats exceeds 100, a limit of 100 applies to the total credits and commits.
+     * Seats are included greedily to maximize the number of seats returned. Example:
+     * if seat 1 has 98 commits and seat 2 has 10 commits, both seats will be returned
+     * (total: 108 commits). Each returned seat includes all of its associated credits
+     * and commits.
+     */
+    limit?: number;
+    /**
+     * Optional filter to only include specific seats.
+     */
+    seat_ids?: Array<string>;
+    /**
+     * Include only commits or credits with access effective on or after this date
+     * (cannot be used with covering_date).
+     */
+    starting_at?: string;
+    /**
+     * Optional filter to only include seats from specific subscriptions. If
+     * subscriptions ids are not mapped to SEAT_BASED subscriptions, error will be
+     * returned.
+     */
+    subscription_ids?: Array<string>;
+}
 export interface ContractRetrieveRateScheduleParams {
     /**
      * Body param: ID of the contract to get the rate schedule for.
@@ -3195,7 +3269,7 @@ export interface ContractUpdateEndDateParams {
     ending_before?: string;
 }
 export declare namespace Contracts {
-    export { type ContractCreateResponse as ContractCreateResponse, type ContractRetrieveResponse as ContractRetrieveResponse, type ContractListResponse as ContractListResponse, type ContractAmendResponse as ContractAmendResponse, type ContractArchiveResponse as ContractArchiveResponse, type ContractCreateHistoricalInvoicesResponse as ContractCreateHistoricalInvoicesResponse, type ContractGetNetBalanceResponse as ContractGetNetBalanceResponse, type ContractListBalancesResponse as ContractListBalancesResponse, type ContractRetrieveRateScheduleResponse as ContractRetrieveRateScheduleResponse, type ContractRetrieveSubscriptionQuantityHistoryResponse as ContractRetrieveSubscriptionQuantityHistoryResponse, type ContractScheduleProServicesInvoiceResponse as ContractScheduleProServicesInvoiceResponse, type ContractUpdateEndDateResponse as ContractUpdateEndDateResponse, type ContractListBalancesResponsesBodyCursorPage as ContractListBalancesResponsesBodyCursorPage, type ContractCreateParams as ContractCreateParams, type ContractRetrieveParams as ContractRetrieveParams, type ContractListParams as ContractListParams, type ContractAddManualBalanceEntryParams as ContractAddManualBalanceEntryParams, type ContractAmendParams as ContractAmendParams, type ContractArchiveParams as ContractArchiveParams, type ContractCreateHistoricalInvoicesParams as ContractCreateHistoricalInvoicesParams, type ContractGetNetBalanceParams as ContractGetNetBalanceParams, type ContractListBalancesParams as ContractListBalancesParams, type ContractRetrieveRateScheduleParams as ContractRetrieveRateScheduleParams, type ContractRetrieveSubscriptionQuantityHistoryParams as ContractRetrieveSubscriptionQuantityHistoryParams, type ContractScheduleProServicesInvoiceParams as ContractScheduleProServicesInvoiceParams, type ContractSetUsageFilterParams as ContractSetUsageFilterParams, type ContractUpdateEndDateParams as ContractUpdateEndDateParams, };
+    export { type ContractCreateResponse as ContractCreateResponse, type ContractRetrieveResponse as ContractRetrieveResponse, type ContractListResponse as ContractListResponse, type ContractAmendResponse as ContractAmendResponse, type ContractArchiveResponse as ContractArchiveResponse, type ContractCreateHistoricalInvoicesResponse as ContractCreateHistoricalInvoicesResponse, type ContractGetNetBalanceResponse as ContractGetNetBalanceResponse, type ContractListBalancesResponse as ContractListBalancesResponse, type ContractListSeatBalancesResponse as ContractListSeatBalancesResponse, type ContractRetrieveRateScheduleResponse as ContractRetrieveRateScheduleResponse, type ContractRetrieveSubscriptionQuantityHistoryResponse as ContractRetrieveSubscriptionQuantityHistoryResponse, type ContractScheduleProServicesInvoiceResponse as ContractScheduleProServicesInvoiceResponse, type ContractUpdateEndDateResponse as ContractUpdateEndDateResponse, type ContractListBalancesResponsesBodyCursorPage as ContractListBalancesResponsesBodyCursorPage, type ContractCreateParams as ContractCreateParams, type ContractRetrieveParams as ContractRetrieveParams, type ContractListParams as ContractListParams, type ContractAddManualBalanceEntryParams as ContractAddManualBalanceEntryParams, type ContractAmendParams as ContractAmendParams, type ContractArchiveParams as ContractArchiveParams, type ContractCreateHistoricalInvoicesParams as ContractCreateHistoricalInvoicesParams, type ContractGetNetBalanceParams as ContractGetNetBalanceParams, type ContractListBalancesParams as ContractListBalancesParams, type ContractListSeatBalancesParams as ContractListSeatBalancesParams, type ContractRetrieveRateScheduleParams as ContractRetrieveRateScheduleParams, type ContractRetrieveSubscriptionQuantityHistoryParams as ContractRetrieveSubscriptionQuantityHistoryParams, type ContractScheduleProServicesInvoiceParams as ContractScheduleProServicesInvoiceParams, type ContractSetUsageFilterParams as ContractSetUsageFilterParams, type ContractUpdateEndDateParams as ContractUpdateEndDateParams, };
     export { Products as Products, type ProductListItemState as ProductListItemState, type QuantityConversion as QuantityConversion, type QuantityRounding as QuantityRounding, type ProductCreateResponse as ProductCreateResponse, type ProductRetrieveResponse as ProductRetrieveResponse, type ProductUpdateResponse as ProductUpdateResponse, type ProductListResponse as ProductListResponse, type ProductArchiveResponse as ProductArchiveResponse, type ProductListResponsesCursorPage as ProductListResponsesCursorPage, type ProductCreateParams as ProductCreateParams, type ProductRetrieveParams as ProductRetrieveParams, type ProductUpdateParams as ProductUpdateParams, type ProductListParams as ProductListParams, type ProductArchiveParams as ProductArchiveParams, };
     export { RateCards as RateCards, type RateCardCreateResponse as RateCardCreateResponse, type RateCardRetrieveResponse as RateCardRetrieveResponse, type RateCardUpdateResponse as RateCardUpdateResponse, type RateCardListResponse as RateCardListResponse, type RateCardArchiveResponse as RateCardArchiveResponse, type RateCardRetrieveRateScheduleResponse as RateCardRetrieveRateScheduleResponse, type RateCardListResponsesCursorPage as RateCardListResponsesCursorPage, type RateCardCreateParams as RateCardCreateParams, type RateCardRetrieveParams as RateCardRetrieveParams, type RateCardUpdateParams as RateCardUpdateParams, type RateCardListParams as RateCardListParams, type RateCardArchiveParams as RateCardArchiveParams, type RateCardRetrieveRateScheduleParams as RateCardRetrieveRateScheduleParams, };
     export { NamedSchedules as NamedSchedules, type NamedScheduleRetrieveResponse as NamedScheduleRetrieveResponse, type NamedScheduleRetrieveParams as NamedScheduleRetrieveParams, type NamedScheduleUpdateParams as NamedScheduleUpdateParams, };