orb-billing 2.11.2 → 3.0.0

package/resources/subscriptions.d.ts

@@ -1,5 +1,5 @@
-import * as Core from "../core.js";
 import { APIResource } from "../resource.js";
+import * as Core from "../core.js";
 import * as SubscriptionsAPI from "./subscriptions.js";
 import * as Shared from "./shared.js";
 import * as CustomersAPI from "./customers/customers.js";
@@ -735,6 +735,21 @@ export declare class Subscriptions extends APIResource {
      * interval. This will only apply to this price interval, not any other price
      * intervals on the subscription.
      *
+     * ## Adjustment intervals
+     *
+     * An adjustment interval represents the time period that a particular adjustment
+     * (a discount, minimum, or maximum) applies to the prices on a subscription.
+     * Adjustment intervals can be added to a subscription by specifying them in the
+     * `add_adjustments` array, or modified via the `edit_adjustments` array. When
+     * creating an adjustment interval, you'll need to provide the definition of the
+     * new adjustment (the type of adjustment, and which prices it applies to), as well
+     * as the start and end dates for the adjustment interval. The start and end dates
+     * of an existing adjustment interval can be edited via the `edit_adjustments`
+     * field (just like price intervals). (To "change" the amount of a discount,
+     * minimum, or maximum, then, you'll need to end the existing interval, and create
+     * a new adjustment interval with the new amount and a start date that matches the
+     * end date of the previous interval.)
+     *
      * ## Editing price intervals
      *
      * Price intervals can be adjusted by specifying edits to make in the `edit` array.
@@ -2960,10 +2975,18 @@ export interface SubscriptionPriceIntervalsParams {
      * A list of price intervals to add to the subscription.
      */
     add?: Array<SubscriptionPriceIntervalsParams.Add>;
+    /**
+     * A list of adjustments to add to the subscription.
+     */
+    add_adjustments?: Array<SubscriptionPriceIntervalsParams.AddAdjustment>;
     /**
      * A list of price intervals to edit on the subscription.
      */
     edit?: Array<SubscriptionPriceIntervalsParams.Edit>;
+    /**
+     * A list of adjustments to edit on the subscription.
+     */
+    edit_adjustments?: Array<SubscriptionPriceIntervalsParams.EditAdjustment>;
 }
 export declare namespace SubscriptionPriceIntervalsParams {
     interface Add {
@@ -2972,6 +2995,10 @@ export declare namespace SubscriptionPriceIntervalsParams {
          * billing on the subscription.
          */
         start_date: (string & {}) | Shared.BillingCycleRelativeDate;
+        /**
+         * The definition of a new allocation price to create and add to the subscription.
+         */
+        allocation_price?: Add.AllocationPrice | null;
         /**
          * A list of discounts to initialize on the price interval.
          */
@@ -3009,6 +3036,29 @@ export declare namespace SubscriptionPriceIntervalsParams {
         price_id?: string | null;
     }
     namespace Add {
+        /**
+         * The definition of a new allocation price to create and add to the subscription.
+         */
+        interface AllocationPrice {
+            /**
+             * An amount of the currency to allocate to the customer at the specified cadence.
+             */
+            amount: string;
+            /**
+             * The cadence at which to allocate the amount to the customer.
+             */
+            cadence: 'one_time' | 'monthly' | 'quarterly' | 'semi_annual' | 'annual';
+            /**
+             * An ISO 4217 currency string or a custom pricing unit identifier in which to bill
+             * this price.
+             */
+            currency: string;
+            /**
+             * Whether the allocated amount should expire at the end of the cadence or roll
+             * over to the next period.
+             */
+            expires_at_end_of_cadence: boolean;
+        }
         interface AmountDiscountCreationParams {
             /**
              * Only available if discount_type is `amount`.
@@ -3046,7 +3096,7 @@ export declare namespace SubscriptionPriceIntervalsParams {
             /**
              * The cadence to bill for this price on.
              */
-            cadence: 'annual' | 'monthly' | 'quarterly' | 'one_time';
+            cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time';
             /**
              * An ISO 4217 currency string for which this price is billed in.
              */
@@ -3088,6 +3138,12 @@ export declare namespace SubscriptionPriceIntervalsParams {
              * The property used to group this price on an invoice
              */
             invoice_grouping_key?: string | null;
+            /**
+             * User-specified key/value pairs for the resource. Individual keys can be removed
+             * by setting the value to `null`, and the entire metadata mapping can be cleared
+             * by setting `metadata` to `null`.
+             */
+            metadata?: Record<string, string | null> | null;
         }
         namespace NewFloatingUnitPrice {
             interface UnitConfig {
@@ -3101,7 +3157,7 @@ export declare namespace SubscriptionPriceIntervalsParams {
             /**
              * The cadence to bill for this price on.
              */
-            cadence: 'annual' | 'monthly' | 'quarterly' | 'one_time';
+            cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time';
             /**
              * An ISO 4217 currency string for which this price is billed in.
              */
@@ -3143,6 +3199,12 @@ export declare namespace SubscriptionPriceIntervalsParams {
              * The property used to group this price on an invoice
              */
             invoice_grouping_key?: string | null;
+            /**
+             * User-specified key/value pairs for the resource. Individual keys can be removed
+             * by setting the value to `null`, and the entire metadata mapping can be cleared
+             * by setting `metadata` to `null`.
+             */
+            metadata?: Record<string, string | null> | null;
         }
         namespace NewFloatingPackagePrice {
             interface PackageConfig {
@@ -3161,7 +3223,7 @@ export declare namespace SubscriptionPriceIntervalsParams {
             /**
              * The cadence to bill for this price on.
              */
-            cadence: 'annual' | 'monthly' | 'quarterly' | 'one_time';
+            cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time';
             /**
              * An ISO 4217 currency string for which this price is billed in.
              */
@@ -3203,6 +3265,12 @@ export declare namespace SubscriptionPriceIntervalsParams {
              * The property used to group this price on an invoice
              */
             invoice_grouping_key?: string | null;
+            /**
+             * User-specified key/value pairs for the resource. Individual keys can be removed
+             * by setting the value to `null`, and the entire metadata mapping can be cleared
+             * by setting `metadata` to `null`.
+             */
+            metadata?: Record<string, string | null> | null;
         }
         namespace NewFloatingMatrixPrice {
             interface MatrixConfig {
@@ -3238,7 +3306,7 @@ export declare namespace SubscriptionPriceIntervalsParams {
             /**
              * The cadence to bill for this price on.
              */
-            cadence: 'annual' | 'monthly' | 'quarterly' | 'one_time';
+            cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time';
             /**
              * An ISO 4217 currency string for which this price is billed in.
              */
@@ -3280,6 +3348,12 @@ export declare namespace SubscriptionPriceIntervalsParams {
              * The property used to group this price on an invoice
              */
             invoice_grouping_key?: string | null;
+            /**
+             * User-specified key/value pairs for the resource. Individual keys can be removed
+             * by setting the value to `null`, and the entire metadata mapping can be cleared
+             * by setting `metadata` to `null`.
+             */
+            metadata?: Record<string, string | null> | null;
         }
         namespace NewFloatingMatrixWithAllocationPrice {
             interface MatrixWithAllocationConfig {
@@ -3319,7 +3393,7 @@ export declare namespace SubscriptionPriceIntervalsParams {
             /**
              * The cadence to bill for this price on.
              */
-            cadence: 'annual' | 'monthly' | 'quarterly' | 'one_time';
+            cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time';
             /**
              * An ISO 4217 currency string for which this price is billed in.
              */
@@ -3361,6 +3435,12 @@ export declare namespace SubscriptionPriceIntervalsParams {
              * The property used to group this price on an invoice
              */
             invoice_grouping_key?: string | null;
+            /**
+             * User-specified key/value pairs for the resource. Individual keys can be removed
+             * by setting the value to `null`, and the entire metadata mapping can be cleared
+             * by setting `metadata` to `null`.
+             */
+            metadata?: Record<string, string | null> | null;
         }
         namespace NewFloatingTieredPrice {
             interface TieredConfig {
@@ -3390,7 +3470,7 @@ export declare namespace SubscriptionPriceIntervalsParams {
             /**
              * The cadence to bill for this price on.
              */
-            cadence: 'annual' | 'monthly' | 'quarterly' | 'one_time';
+            cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time';
             /**
              * An ISO 4217 currency string for which this price is billed in.
              */
@@ -3432,6 +3512,12 @@ export declare namespace SubscriptionPriceIntervalsParams {
              * The property used to group this price on an invoice
              */
             invoice_grouping_key?: string | null;
+            /**
+             * User-specified key/value pairs for the resource. Individual keys can be removed
+             * by setting the value to `null`, and the entire metadata mapping can be cleared
+             * by setting `metadata` to `null`.
+             */
+            metadata?: Record<string, string | null> | null;
         }
         namespace NewFloatingTieredBpsPrice {
             interface TieredBpsConfig {
@@ -3467,7 +3553,7 @@ export declare namespace SubscriptionPriceIntervalsParams {
             /**
              * The cadence to bill for this price on.
              */
-            cadence: 'annual' | 'monthly' | 'quarterly' | 'one_time';
+            cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time';
             /**
              * An ISO 4217 currency string for which this price is billed in.
              */
@@ -3508,6 +3594,12 @@ export declare namespace SubscriptionPriceIntervalsParams {
              * The property used to group this price on an invoice
              */
             invoice_grouping_key?: string | null;
+            /**
+             * User-specified key/value pairs for the resource. Individual keys can be removed
+             * by setting the value to `null`, and the entire metadata mapping can be cleared
+             * by setting `metadata` to `null`.
+             */
+            metadata?: Record<string, string | null> | null;
         }
         namespace NewFloatingBpsPrice {
             interface BpsConfig {
@@ -3526,7 +3618,7 @@ export declare namespace SubscriptionPriceIntervalsParams {
             /**
              * The cadence to bill for this price on.
              */
-            cadence: 'annual' | 'monthly' | 'quarterly' | 'one_time';
+            cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time';
             /**
              * An ISO 4217 currency string for which this price is billed in.
              */
@@ -3567,6 +3659,12 @@ export declare namespace SubscriptionPriceIntervalsParams {
              * The property used to group this price on an invoice
              */
             invoice_grouping_key?: string | null;
+            /**
+             * User-specified key/value pairs for the resource. Individual keys can be removed
+             * by setting the value to `null`, and the entire metadata mapping can be cleared
+             * by setting `metadata` to `null`.
+             */
+            metadata?: Record<string, string | null> | null;
         }
         namespace NewFloatingBulkBpsPrice {
             interface BulkBpsConfig {
@@ -3598,7 +3696,7 @@ export declare namespace SubscriptionPriceIntervalsParams {
             /**
              * The cadence to bill for this price on.
              */
-            cadence: 'annual' | 'monthly' | 'quarterly' | 'one_time';
+            cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time';
             /**
              * An ISO 4217 currency string for which this price is billed in.
              */
@@ -3639,6 +3737,12 @@ export declare namespace SubscriptionPriceIntervalsParams {
              * The property used to group this price on an invoice
              */
             invoice_grouping_key?: string | null;
+            /**
+             * User-specified key/value pairs for the resource. Individual keys can be removed
+             * by setting the value to `null`, and the entire metadata mapping can be cleared
+             * by setting `metadata` to `null`.
+             */
+            metadata?: Record<string, string | null> | null;
         }
         namespace NewFloatingBulkPrice {
             interface BulkConfig {
@@ -3664,7 +3768,7 @@ export declare namespace SubscriptionPriceIntervalsParams {
             /**
              * The cadence to bill for this price on.
              */
-            cadence: 'annual' | 'monthly' | 'quarterly' | 'one_time';
+            cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time';
             /**
              * An ISO 4217 currency string for which this price is billed in.
              */
@@ -3706,12 +3810,18 @@ export declare namespace SubscriptionPriceIntervalsParams {
              * The property used to group this price on an invoice
              */
             invoice_grouping_key?: string | null;
+            /**
+             * User-specified key/value pairs for the resource. Individual keys can be removed
+             * by setting the value to `null`, and the entire metadata mapping can be cleared
+             * by setting `metadata` to `null`.
+             */
+            metadata?: Record<string, string | null> | null;
         }
         interface NewFloatingTieredPackagePrice {
             /**
              * The cadence to bill for this price on.
              */
-            cadence: 'annual' | 'monthly' | 'quarterly' | 'one_time';
+            cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time';
             /**
              * An ISO 4217 currency string for which this price is billed in.
              */
@@ -3753,12 +3863,18 @@ export declare namespace SubscriptionPriceIntervalsParams {
              * The property used to group this price on an invoice
              */
             invoice_grouping_key?: string | null;
+            /**
+             * User-specified key/value pairs for the resource. Individual keys can be removed
+             * by setting the value to `null`, and the entire metadata mapping can be cleared
+             * by setting `metadata` to `null`.
+             */
+            metadata?: Record<string, string | null> | null;
         }
         interface NewFloatingGroupedTieredPrice {
             /**
              * The cadence to bill for this price on.
              */
-            cadence: 'annual' | 'monthly' | 'quarterly' | 'one_time';
+            cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time';
             /**
              * An ISO 4217 currency string for which this price is billed in.
              */
@@ -3800,12 +3916,18 @@ export declare namespace SubscriptionPriceIntervalsParams {
              * The property used to group this price on an invoice
              */
             invoice_grouping_key?: string | null;
+            /**
+             * User-specified key/value pairs for the resource. Individual keys can be removed
+             * by setting the value to `null`, and the entire metadata mapping can be cleared
+             * by setting `metadata` to `null`.
+             */
+            metadata?: Record<string, string | null> | null;
         }
         interface NewFloatingTieredWithMinimumPrice {
             /**
              * The cadence to bill for this price on.
              */
-            cadence: 'annual' | 'monthly' | 'quarterly' | 'one_time';
+            cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time';
             /**
              * An ISO 4217 currency string for which this price is billed in.
              */
@@ -3847,12 +3969,18 @@ export declare namespace SubscriptionPriceIntervalsParams {
              * The property used to group this price on an invoice
              */
             invoice_grouping_key?: string | null;
+            /**
+             * User-specified key/value pairs for the resource. Individual keys can be removed
+             * by setting the value to `null`, and the entire metadata mapping can be cleared
+             * by setting `metadata` to `null`.
+             */
+            metadata?: Record<string, string | null> | null;
         }
         interface NewFloatingPackageWithAllocationPrice {
             /**
              * The cadence to bill for this price on.
              */
-            cadence: 'annual' | 'monthly' | 'quarterly' | 'one_time';
+            cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time';
             /**
              * An ISO 4217 currency string for which this price is billed in.
              */
@@ -3894,12 +4022,18 @@ export declare namespace SubscriptionPriceIntervalsParams {
              * The property used to group this price on an invoice
              */
             invoice_grouping_key?: string | null;
+            /**
+             * User-specified key/value pairs for the resource. Individual keys can be removed
+             * by setting the value to `null`, and the entire metadata mapping can be cleared
+             * by setting `metadata` to `null`.
+             */
+            metadata?: Record<string, string | null> | null;
         }
         interface NewFloatingTieredPackageWithMinimumPrice {
             /**
              * The cadence to bill for this price on.
              */
-            cadence: 'annual' | 'monthly' | 'quarterly' | 'one_time';
+            cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time';
             /**
              * An ISO 4217 currency string for which this price is billed in.
              */
@@ -3941,12 +4075,18 @@ export declare namespace SubscriptionPriceIntervalsParams {
              * The property used to group this price on an invoice
              */
             invoice_grouping_key?: string | null;
+            /**
+             * User-specified key/value pairs for the resource. Individual keys can be removed
+             * by setting the value to `null`, and the entire metadata mapping can be cleared
+             * by setting `metadata` to `null`.
+             */
+            metadata?: Record<string, string | null> | null;
         }
         interface NewFloatingUnitWithPercentPrice {
             /**
              * The cadence to bill for this price on.
              */
-            cadence: 'annual' | 'monthly' | 'quarterly' | 'one_time';
+            cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time';
             /**
              * An ISO 4217 currency string for which this price is billed in.
              */
@@ -3988,12 +4128,18 @@ export declare namespace SubscriptionPriceIntervalsParams {
              * The property used to group this price on an invoice
              */
             invoice_grouping_key?: string | null;
+            /**
+             * User-specified key/value pairs for the resource. Individual keys can be removed
+             * by setting the value to `null`, and the entire metadata mapping can be cleared
+             * by setting `metadata` to `null`.
+             */
+            metadata?: Record<string, string | null> | null;
         }
         interface NewFloatingTieredWithProrationPrice {
             /**
              * The cadence to bill for this price on.
              */
-            cadence: 'annual' | 'monthly' | 'quarterly' | 'one_time';
+            cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time';
             /**
              * An ISO 4217 currency string for which this price is billed in.
              */
@@ -4035,12 +4181,18 @@ export declare namespace SubscriptionPriceIntervalsParams {
              * The property used to group this price on an invoice
              */
             invoice_grouping_key?: string | null;
+            /**
+             * User-specified key/value pairs for the resource. Individual keys can be removed
+             * by setting the value to `null`, and the entire metadata mapping can be cleared
+             * by setting `metadata` to `null`.
+             */
+            metadata?: Record<string, string | null> | null;
         }
         interface NewFloatingUnitWithProrationPrice {
             /**
              * The cadence to bill for this price on.
              */
-            cadence: 'annual' | 'monthly' | 'quarterly' | 'one_time';
+            cadence: 'annual' | 'semi_annual' | 'monthly' | 'quarterly' | 'one_time';
             /**
              * An ISO 4217 currency string for which this price is billed in.
              */
@@ -4082,6 +4234,66 @@ export declare namespace SubscriptionPriceIntervalsParams {
              * The property used to group this price on an invoice
              */
             invoice_grouping_key?: string | null;
+            /**
+             * User-specified key/value pairs for the resource. Individual keys can be removed
+             * by setting the value to `null`, and the entire metadata mapping can be cleared
+             * by setting `metadata` to `null`.
+             */
+            metadata?: Record<string, string | null> | null;
+        }
+    }
+    interface AddAdjustment {
+        /**
+         * The definition of a new adjustment to create and add to the subscription.
+         */
+        adjustment: AddAdjustment.NewPercentageDiscount | AddAdjustment.NewAmountDiscount | AddAdjustment.NewMinimum | AddAdjustment.NewMaximum;
+        /**
+         * The start date of the adjustment interval. This is the date that the adjustment
+         * will start affecting prices on the subscription.
+         */
+        start_date: (string & {}) | Shared.BillingCycleRelativeDate;
+        /**
+         * The end date of the adjustment interval. This is the date that the adjustment
+         * will stop affecting prices on the subscription.
+         */
+        end_date?: (string & {}) | Shared.BillingCycleRelativeDate | null;
+    }
+    namespace AddAdjustment {
+        interface NewPercentageDiscount {
+            adjustment_type: 'percentage_discount';
+            /**
+             * The set of price IDs to which this adjustment applies.
+             */
+            applies_to_price_ids: Array<string>;
+            percentage_discount: number;
+        }
+        interface NewAmountDiscount {
+            adjustment_type: 'amount_discount';
+            amount_discount: string;
+            /**
+             * The set of price IDs to which this adjustment applies.
+             */
+            applies_to_price_ids: Array<string>;
+        }
+        interface NewMinimum {
+            adjustment_type: 'minimum';
+            /**
+             * The set of price IDs to which this adjustment applies.
+             */
+            applies_to_price_ids: Array<string>;
+            /**
+             * The item ID that revenue from this minimum will be attributed to.
+             */
+            item_id: string;
+            minimum_amount: string;
+        }
+        interface NewMaximum {
+            adjustment_type: 'maximum';
+            /**
+             * The set of price IDs to which this adjustment applies.
+             */
+            applies_to_price_ids: Array<string>;
+            maximum_amount: string;
         }
     }
     interface Edit {
@@ -4124,6 +4336,22 @@ export declare namespace SubscriptionPriceIntervalsParams {
             quantity: number;
         }
     }
+    interface EditAdjustment {
+        /**
+         * The id of the adjustment interval to edit.
+         */
+        adjustment_interval_id: string;
+        /**
+         * The updated end date of this adjustment interval. If not specified, the start
+         * date will not be updated.
+         */
+        end_date?: (string & {}) | Shared.BillingCycleRelativeDate | null;
+        /**
+         * The updated start date of this adjustment interval. If not specified, the start
+         * date will not be updated.
+         */
+        start_date?: (string & {}) | Shared.BillingCycleRelativeDate;
+    }
 }
 export interface SubscriptionSchedulePlanChangeParams {
     change_option: 'requested_date' | 'end_of_subscription_term' | 'immediate';