@metronome/sdk 3.6.0 → 3.8.0

package/src/resources/v1/packages.ts

@@ -145,10 +145,9 @@ export class Packages extends APIResource {
    *
    * ### **Usage guidelines:**
    *
-   * Use the **`starting_at`**, **`covering_date`**,
-   * and **`include_archived`** parameters to filter the list of returned contracts.
-   * For example, to list only currently active contracts,
-   * pass **`covering_date`** equal to the current time.
+   * Use the **`starting_at`**, **`covering_date`**, and **`include_archived`**
+   * parameters to filter the list of returned contracts. For example, to list only
+   * currently active contracts, pass **`covering_date`** equal to the current time.
    *
    * @example
    * ```ts
@@ -259,6 +258,8 @@ export namespace PackageRetrieveResponse {
 
     spend_threshold_configuration?: Shared.SpendThresholdConfiguration;
 
+    spend_trackers?: Array<Data.SpendTracker>;
+
     subscriptions?: Array<Data.Subscription>;
 
     /**
@@ -429,6 +430,8 @@ export namespace PackageRetrieveResponse {
 
     export namespace Override {
       export interface OverrideSpecifier {
+        any_commit_or_credit_template_ids?: Array<string>;
+
         billing_frequency?: 'MONTHLY' | 'QUARTERLY' | 'ANNUAL' | 'WEEKLY';
 
         commit_template_ids?: Array<string>;
@@ -665,6 +668,11 @@ export namespace PackageRetrieveResponse {
        */
       proration?: 'NONE' | 'FIRST' | 'LAST' | 'FIRST_AND_LAST';
 
+      /**
+       * Rounding configuration for prorated recurring commit amounts.
+       */
+      proration_rounding?: RecurringCommit.ProrationRounding | null;
+
       /**
        * The frequency at which the recurring commits will be created. If not provided: -
        * The commits will be created on the usage invoice frequency. If provided: - The
@@ -672,7 +680,7 @@ export namespace PackageRetrieveResponse {
        * be created aligned with the recurring commit's starting_at rather than the usage
        * invoice dates.
        */
-      recurrence_frequency?: 'MONTHLY' | 'QUARTERLY' | 'ANNUAL' | 'WEEKLY';
+      recurrence_frequency?: 'MONTHLY' | 'QUARTERLY' | 'ANNUAL' | 'WEEKLY' | 'DAILY';
 
       /**
        * Will be passed down to the individual commits. This controls how much of an
@@ -752,6 +760,41 @@ export namespace PackageRetrieveResponse {
         unit_price: number;
       }
 
+      /**
+       * Rounding configuration for prorated recurring commit amounts.
+       */
+      export interface ProrationRounding {
+        access?: ProrationRounding.Access;
+
+        invoice?: ProrationRounding.Invoice;
+      }
+
+      export namespace ProrationRounding {
+        export interface Access {
+          /**
+           * Number of decimal places to round to. Applied directly to the stored monetary
+           * representation. Negative values round to powers of 10 (e.g., -2 rounds to
+           * nearest 100 in the stored unit. For USD, this means rounding to the nearest
+           * dollar).
+           */
+          decimal_places: number;
+
+          rounding_method: 'HALF_UP' | 'FLOOR' | 'CEILING';
+        }
+
+        export interface Invoice {
+          /**
+           * Number of decimal places to round to. Applied directly to the stored monetary
+           * representation. Negative values round to powers of 10 (e.g., -2 rounds to
+           * nearest 100 in the stored unit. For USD, this means rounding to the nearest
+           * dollar).
+           */
+          decimal_places: number;
+
+          rounding_method: 'HALF_UP' | 'FLOOR' | 'CEILING';
+        }
+      }
+
       /**
        * Attach a subscription to the recurring commit/credit.
        */
@@ -827,6 +870,11 @@ export namespace PackageRetrieveResponse {
        */
       proration?: 'NONE' | 'FIRST' | 'LAST' | 'FIRST_AND_LAST';
 
+      /**
+       * Rounding configuration for prorated recurring credit amounts.
+       */
+      proration_rounding?: RecurringCredit.ProrationRounding | null;
+
       /**
        * The frequency at which the recurring commits will be created. If not provided: -
        * The commits will be created on the usage invoice frequency. If provided: - The
@@ -834,7 +882,7 @@ export namespace PackageRetrieveResponse {
        * be created aligned with the recurring commit's starting_at rather than the usage
        * invoice dates.
        */
-      recurrence_frequency?: 'MONTHLY' | 'QUARTERLY' | 'ANNUAL' | 'WEEKLY';
+      recurrence_frequency?: 'MONTHLY' | 'QUARTERLY' | 'ANNUAL' | 'WEEKLY' | 'DAILY';
 
       /**
        * Will be passed down to the individual commits. This controls how much of an
@@ -903,6 +951,27 @@ export namespace PackageRetrieveResponse {
         value: number;
       }
 
+      /**
+       * Rounding configuration for prorated recurring credit amounts.
+       */
+      export interface ProrationRounding {
+        access?: ProrationRounding.Access;
+      }
+
+      export namespace ProrationRounding {
+        export interface Access {
+          /**
+           * Number of decimal places to round to. Applied directly to the stored monetary
+           * representation. Negative values round to powers of 10 (e.g., -2 rounds to
+           * nearest 100 in the stored unit. For USD, this means rounding to the nearest
+           * dollar).
+           */
+          decimal_places: number;
+
+          rounding_method: 'HALF_UP' | 'FLOOR' | 'CEILING';
+        }
+      }
+
       /**
        * Attach a subscription to the recurring commit/credit.
        */
@@ -924,6 +993,29 @@ export namespace PackageRetrieveResponse {
       }
     }
 
+    export interface SpendTracker {
+      /**
+       * Human-readable identifier, unique per contract.
+       */
+      alias: string;
+
+      applicable_spend_specifiers: Array<SpendTracker.ApplicableSpendSpecifier>;
+
+      credit_type_id: string;
+
+      reset_frequency: 'BILLING_PERIOD';
+    }
+
+    export namespace SpendTracker {
+      export interface ApplicableSpendSpecifier {
+        sources: Array<'THRESHOLD_RECHARGE' | 'MANUAL'>;
+
+        spend_type: 'COMMIT_PURCHASE';
+
+        discounted?: 'ANY' | 'DISCOUNTED_ONLY' | 'UNDISCOUNTED_ONLY';
+      }
+    }
+
     export interface Subscription {
       collection_schedule: 'ADVANCE' | 'ARREARS';
 
@@ -933,6 +1025,8 @@ export namespace PackageRetrieveResponse {
 
       id?: string;
 
+      billing_cycle_config?: Subscription.BillingCycleConfig;
+
       /**
        * Custom fields to be added eg. { "key1": "value1", "key2": "value2" }
        */
@@ -971,6 +1065,22 @@ export namespace PackageRetrieveResponse {
         invoice_behavior: 'BILL_IMMEDIATELY' | 'BILL_ON_NEXT_COLLECTION_DATE';
 
         is_prorated: boolean;
+
+        rounding?: Proration.Rounding;
+      }
+
+      export namespace Proration {
+        export interface Rounding {
+          /**
+           * Number of decimal places to round to. Applied directly to the stored monetary
+           * representation. Negative values round to powers of 10 (e.g., -2 rounds to
+           * nearest 100 in the stored unit. For USD, this means rounding to the nearest
+           * dollar).
+           */
+          decimal_places: number;
+
+          rounding_method: 'HALF_UP' | 'FLOOR' | 'CEILING';
+        }
       }
 
       export interface SubscriptionRate {
@@ -987,6 +1097,10 @@ export namespace PackageRetrieveResponse {
         }
       }
 
+      export interface BillingCycleConfig {
+        invoice_placement?: 'ON_SCHEDULED_INVOICE' | 'ON_USAGE_INVOICE';
+      }
+
       export interface Duration {
         unit: 'DAYS' | 'WEEKS' | 'MONTHS' | 'YEARS';
 
@@ -1086,6 +1200,8 @@ export interface PackageListResponse {
 
   spend_threshold_configuration?: Shared.SpendThresholdConfiguration;
 
+  spend_trackers?: Array<PackageListResponse.SpendTracker>;
+
   subscriptions?: Array<PackageListResponse.Subscription>;
 
   /**
@@ -1256,6 +1372,8 @@ export namespace PackageListResponse {
 
   export namespace Override {
     export interface OverrideSpecifier {
+      any_commit_or_credit_template_ids?: Array<string>;
+
       billing_frequency?: 'MONTHLY' | 'QUARTERLY' | 'ANNUAL' | 'WEEKLY';
 
       commit_template_ids?: Array<string>;
@@ -1492,6 +1610,11 @@ export namespace PackageListResponse {
      */
     proration?: 'NONE' | 'FIRST' | 'LAST' | 'FIRST_AND_LAST';
 
+    /**
+     * Rounding configuration for prorated recurring commit amounts.
+     */
+    proration_rounding?: RecurringCommit.ProrationRounding | null;
+
     /**
      * The frequency at which the recurring commits will be created. If not provided: -
      * The commits will be created on the usage invoice frequency. If provided: - The
@@ -1499,7 +1622,7 @@ export namespace PackageListResponse {
      * be created aligned with the recurring commit's starting_at rather than the usage
      * invoice dates.
      */
-    recurrence_frequency?: 'MONTHLY' | 'QUARTERLY' | 'ANNUAL' | 'WEEKLY';
+    recurrence_frequency?: 'MONTHLY' | 'QUARTERLY' | 'ANNUAL' | 'WEEKLY' | 'DAILY';
 
     /**
      * Will be passed down to the individual commits. This controls how much of an
@@ -1579,6 +1702,41 @@ export namespace PackageListResponse {
       unit_price: number;
     }
 
+    /**
+     * Rounding configuration for prorated recurring commit amounts.
+     */
+    export interface ProrationRounding {
+      access?: ProrationRounding.Access;
+
+      invoice?: ProrationRounding.Invoice;
+    }
+
+    export namespace ProrationRounding {
+      export interface Access {
+        /**
+         * Number of decimal places to round to. Applied directly to the stored monetary
+         * representation. Negative values round to powers of 10 (e.g., -2 rounds to
+         * nearest 100 in the stored unit. For USD, this means rounding to the nearest
+         * dollar).
+         */
+        decimal_places: number;
+
+        rounding_method: 'HALF_UP' | 'FLOOR' | 'CEILING';
+      }
+
+      export interface Invoice {
+        /**
+         * Number of decimal places to round to. Applied directly to the stored monetary
+         * representation. Negative values round to powers of 10 (e.g., -2 rounds to
+         * nearest 100 in the stored unit. For USD, this means rounding to the nearest
+         * dollar).
+         */
+        decimal_places: number;
+
+        rounding_method: 'HALF_UP' | 'FLOOR' | 'CEILING';
+      }
+    }
+
     /**
      * Attach a subscription to the recurring commit/credit.
      */
@@ -1654,6 +1812,11 @@ export namespace PackageListResponse {
      */
     proration?: 'NONE' | 'FIRST' | 'LAST' | 'FIRST_AND_LAST';
 
+    /**
+     * Rounding configuration for prorated recurring credit amounts.
+     */
+    proration_rounding?: RecurringCredit.ProrationRounding | null;
+
     /**
      * The frequency at which the recurring commits will be created. If not provided: -
      * The commits will be created on the usage invoice frequency. If provided: - The
@@ -1661,7 +1824,7 @@ export namespace PackageListResponse {
      * be created aligned with the recurring commit's starting_at rather than the usage
      * invoice dates.
      */
-    recurrence_frequency?: 'MONTHLY' | 'QUARTERLY' | 'ANNUAL' | 'WEEKLY';
+    recurrence_frequency?: 'MONTHLY' | 'QUARTERLY' | 'ANNUAL' | 'WEEKLY' | 'DAILY';
 
     /**
      * Will be passed down to the individual commits. This controls how much of an
@@ -1730,6 +1893,27 @@ export namespace PackageListResponse {
       value: number;
     }
 
+    /**
+     * Rounding configuration for prorated recurring credit amounts.
+     */
+    export interface ProrationRounding {
+      access?: ProrationRounding.Access;
+    }
+
+    export namespace ProrationRounding {
+      export interface Access {
+        /**
+         * Number of decimal places to round to. Applied directly to the stored monetary
+         * representation. Negative values round to powers of 10 (e.g., -2 rounds to
+         * nearest 100 in the stored unit. For USD, this means rounding to the nearest
+         * dollar).
+         */
+        decimal_places: number;
+
+        rounding_method: 'HALF_UP' | 'FLOOR' | 'CEILING';
+      }
+    }
+
     /**
      * Attach a subscription to the recurring commit/credit.
      */
@@ -1751,6 +1935,29 @@ export namespace PackageListResponse {
     }
   }
 
+  export interface SpendTracker {
+    /**
+     * Human-readable identifier, unique per contract.
+     */
+    alias: string;
+
+    applicable_spend_specifiers: Array<SpendTracker.ApplicableSpendSpecifier>;
+
+    credit_type_id: string;
+
+    reset_frequency: 'BILLING_PERIOD';
+  }
+
+  export namespace SpendTracker {
+    export interface ApplicableSpendSpecifier {
+      sources: Array<'THRESHOLD_RECHARGE' | 'MANUAL'>;
+
+      spend_type: 'COMMIT_PURCHASE';
+
+      discounted?: 'ANY' | 'DISCOUNTED_ONLY' | 'UNDISCOUNTED_ONLY';
+    }
+  }
+
   export interface Subscription {
     collection_schedule: 'ADVANCE' | 'ARREARS';
 
@@ -1760,6 +1967,8 @@ export namespace PackageListResponse {
 
     id?: string;
 
+    billing_cycle_config?: Subscription.BillingCycleConfig;
+
     /**
      * Custom fields to be added eg. { "key1": "value1", "key2": "value2" }
      */
@@ -1798,6 +2007,22 @@ export namespace PackageListResponse {
       invoice_behavior: 'BILL_IMMEDIATELY' | 'BILL_ON_NEXT_COLLECTION_DATE';
 
       is_prorated: boolean;
+
+      rounding?: Proration.Rounding;
+    }
+
+    export namespace Proration {
+      export interface Rounding {
+        /**
+         * Number of decimal places to round to. Applied directly to the stored monetary
+         * representation. Negative values round to powers of 10 (e.g., -2 rounds to
+         * nearest 100 in the stored unit. For USD, this means rounding to the nearest
+         * dollar).
+         */
+        decimal_places: number;
+
+        rounding_method: 'HALF_UP' | 'FLOOR' | 'CEILING';
+      }
     }
 
     export interface SubscriptionRate {
@@ -1814,6 +2039,10 @@ export namespace PackageListResponse {
       }
     }
 
+    export interface BillingCycleConfig {
+      invoice_placement?: 'ON_SCHEDULED_INVOICE' | 'ON_USAGE_INVOICE';
+    }
+
     export interface Duration {
       unit: 'DAYS' | 'WEEKS' | 'MONTHS' | 'YEARS';
 
@@ -1917,6 +2146,8 @@ export interface PackageCreateParams {
 
   spend_threshold_configuration?: Shared.SpendThresholdConfiguration;
 
+  spend_trackers?: Array<PackageCreateParams.SpendTracker>;
+
   subscriptions?: Array<PackageCreateParams.Subscription>;
 
   /**
@@ -2256,9 +2487,10 @@ export namespace PackageCreateParams {
 
     /**
      * Indicates whether the override should only apply to commits. Defaults to
-     * `false`. If `true`, you can specify relevant commits in `override_specifiers` by
-     * passing `commit_ids`. if you do not specify `commit_ids`, then the override will
-     * apply when consuming any prepaid or postpaid commit.
+     * `false`. If `true` you can specify relevant commits in `override_specifiers` by
+     * passing `commit_ids`, `recurring_commit_ids`, or `any_commit_or_credit_ids`. If
+     * you do not specify any of these fields, the override will apply when consuming
+     * any prepaid commit, postpaid commit, or credit
      */
     is_commit_specific?: boolean;
 
@@ -2300,6 +2532,15 @@ export namespace PackageCreateParams {
 
   export namespace Override {
     export interface OverrideSpecifier {
+      /**
+       * 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`. Must be used instead of both `commit_ids` and
+       * `recurring_commit_ids` If provided, the override will apply to any specified
+       * commit, credit, recurring commit or recurring credit IDs.
+       */
+      any_commit_or_credit_ids?: Array<string>;
+
       billing_frequency?: 'MONTHLY' | 'QUARTERLY' | 'ANNUAL' | 'WEEKLY';
 
       /**
@@ -2469,6 +2710,11 @@ export namespace PackageCreateParams {
      */
     proration?: 'NONE' | 'FIRST' | 'LAST' | 'FIRST_AND_LAST';
 
+    /**
+     * Optional rounding configuration for prorated recurring commit amounts.
+     */
+    proration_rounding?: RecurringCommit.ProrationRounding;
+
     /**
      * Whether the created commits will use the commit rate or list rate
      */
@@ -2481,7 +2727,7 @@ export namespace PackageCreateParams {
      * be created aligned with the recurring commit's starting_at rather than the usage
      * invoice dates.
      */
-    recurrence_frequency?: 'MONTHLY' | 'QUARTERLY' | 'ANNUAL' | 'WEEKLY';
+    recurrence_frequency?: 'MONTHLY' | 'QUARTERLY' | 'ANNUAL' | 'WEEKLY' | 'DAILY';
 
     /**
      * Will be passed down to the individual commits. This controls how much of an
@@ -2568,6 +2814,41 @@ export namespace PackageCreateParams {
       unit_price: number;
     }
 
+    /**
+     * Optional rounding configuration for prorated recurring commit amounts.
+     */
+    export interface ProrationRounding {
+      access?: ProrationRounding.Access;
+
+      invoice?: ProrationRounding.Invoice;
+    }
+
+    export namespace ProrationRounding {
+      export interface Access {
+        /**
+         * Number of decimal places to round to. Applied directly to the stored monetary
+         * representation. Negative values round to powers of 10 (e.g., -2 rounds to
+         * nearest 100 in the stored unit. For USD, this means rounding to the nearest
+         * dollar).
+         */
+        decimal_places: number;
+
+        rounding_method: 'HALF_UP' | 'FLOOR' | 'CEILING';
+      }
+
+      export interface Invoice {
+        /**
+         * Number of decimal places to round to. Applied directly to the stored monetary
+         * representation. Negative values round to powers of 10 (e.g., -2 rounds to
+         * nearest 100 in the stored unit. For USD, this means rounding to the nearest
+         * dollar).
+         */
+        decimal_places: number;
+
+        rounding_method: 'HALF_UP' | 'FLOOR' | 'CEILING';
+      }
+    }
+
     /**
      * Attach a subscription to the recurring commit/credit.
      */
@@ -2654,6 +2935,11 @@ export namespace PackageCreateParams {
      */
     proration?: 'NONE' | 'FIRST' | 'LAST' | 'FIRST_AND_LAST';
 
+    /**
+     * Optional rounding configuration for prorated recurring credit amounts.
+     */
+    proration_rounding?: RecurringCredit.ProrationRounding;
+
     /**
      * Whether the created commits will use the commit rate or list rate
      */
@@ -2666,7 +2952,7 @@ export namespace PackageCreateParams {
      * be created aligned with the recurring commit's starting_at rather than the usage
      * invoice dates.
      */
-    recurrence_frequency?: 'MONTHLY' | 'QUARTERLY' | 'ANNUAL' | 'WEEKLY';
+    recurrence_frequency?: 'MONTHLY' | 'QUARTERLY' | 'ANNUAL' | 'WEEKLY' | 'DAILY';
 
     /**
      * Will be passed down to the individual commits. This controls how much of an
@@ -2742,6 +3028,27 @@ export namespace PackageCreateParams {
       value: number;
     }
 
+    /**
+     * Optional rounding configuration for prorated recurring credit amounts.
+     */
+    export interface ProrationRounding {
+      access?: ProrationRounding.Access;
+    }
+
+    export namespace ProrationRounding {
+      export interface Access {
+        /**
+         * Number of decimal places to round to. Applied directly to the stored monetary
+         * representation. Negative values round to powers of 10 (e.g., -2 rounds to
+         * nearest 100 in the stored unit. For USD, this means rounding to the nearest
+         * dollar).
+         */
+        decimal_places: number;
+
+        rounding_method: 'HALF_UP' | 'FLOOR' | 'CEILING';
+      }
+    }
+
     /**
      * Attach a subscription to the recurring commit/credit.
      */
@@ -2838,6 +3145,32 @@ export namespace PackageCreateParams {
     }
   }
 
+  export interface SpendTracker {
+    /**
+     * Human-readable identifier, unique per contract.
+     */
+    alias: string;
+
+    applicable_spend_specifiers: Array<SpendTracker.ApplicableSpendSpecifier>;
+
+    credit_type_id: string;
+
+    reset_frequency: 'BILLING_PERIOD';
+  }
+
+  export namespace SpendTracker {
+    export interface ApplicableSpendSpecifier {
+      sources: Array<'THRESHOLD_RECHARGE' | 'MANUAL'>;
+
+      spend_type: 'COMMIT_PURCHASE';
+
+      /**
+       * Filter by whether the spend was discounted. Defaults to ANY if omitted.
+       */
+      discounted?: 'ANY' | 'DISCOUNTED_ONLY' | 'UNDISCOUNTED_ONLY';
+    }
+  }
+
   export interface Subscription {
     collection_schedule: 'ADVANCE' | 'ARREARS';
 
@@ -2845,6 +3178,8 @@ export namespace PackageCreateParams {
 
     subscription_rate: Subscription.SubscriptionRate;
 
+    billing_cycle_config?: Subscription.BillingCycleConfig;
+
     /**
      * Custom fields to be added eg. { "key1": "value1", "key2": "value2" }
      */
@@ -2909,6 +3244,22 @@ export namespace PackageCreateParams {
        * Indicates if the partial period will be prorated or charged a full amount.
        */
       is_prorated?: boolean;
+
+      rounding?: Proration.Rounding;
+    }
+
+    export namespace Proration {
+      export interface Rounding {
+        /**
+         * Number of decimal places to round to. Applied directly to the stored monetary
+         * representation. Negative values round to powers of 10 (e.g., -2 rounds to
+         * nearest 100 in the stored unit. For USD, this means rounding to the nearest
+         * dollar).
+         */
+        decimal_places: number;
+
+        rounding_method: 'HALF_UP' | 'FLOOR' | 'CEILING';
+      }
     }
 
     export interface SubscriptionRate {
@@ -2924,6 +3275,14 @@ export namespace PackageCreateParams {
       product_id: string;
     }
 
+    export interface BillingCycleConfig {
+      /**
+       * Controls whether subscriptions consolidate onto usage invoices. Defaults to
+       * ON_USAGE_INVOICE if omitted.
+       */
+      invoice_placement?: 'ON_SCHEDULED_INVOICE' | 'ON_USAGE_INVOICE';
+    }
+
     /**
      * Lifetime of the subscription from its start. If not provided, subscription
      * inherits contract end date.