orb-billing 4.73.0 → 4.74.0

package/src/resources/subscriptions.ts

@@ -752,6 +752,17 @@ export class Subscriptions extends APIResource {
     return this._client.post(`/subscriptions/${subscriptionId}/price_intervals`, { body, ...options });
   }
 
+  /**
+   * Redeem a coupon effective at a given time.
+   */
+  redeemCoupon(
+    subscriptionId: string,
+    body: SubscriptionRedeemCouponParams,
+    options?: Core.RequestOptions,
+  ): Core.APIPromise<SubscriptionRedeemCouponResponse> {
+    return this._client.post(`/subscriptions/${subscriptionId}/redeem_coupon`, { body, ...options });
+  }
+
   /**
    * This endpoint can be used to change an existing subscription's plan. It returns
    * the serialized updated subscription object.
@@ -1931,91 +1942,976 @@ export namespace Subscription {
   export interface TrialInfo {
     end_date: string | null;
   }
-}
-
-export type SubscriptionUsage =
-  | SubscriptionUsage.UngroupedSubscriptionUsage
-  | SubscriptionUsage.GroupedSubscriptionUsage;
-
-export namespace SubscriptionUsage {
-  export interface UngroupedSubscriptionUsage {
-    data: Array<UngroupedSubscriptionUsage.Data>;
-  }
-
-  export namespace UngroupedSubscriptionUsage {
-    export interface Data {
-      billable_metric: Data.BillableMetric;
-
-      usage: Array<Data.Usage>;
-
-      view_mode: 'periodic' | 'cumulative';
-    }
-
-    export namespace Data {
-      export interface BillableMetric {
-        id: string;
-
-        name: string;
-      }
-
-      export interface Usage {
-        quantity: number;
-
-        timeframe_end: string;
-
-        timeframe_start: string;
-      }
-    }
-  }
-
-  export interface GroupedSubscriptionUsage {
-    data: Array<GroupedSubscriptionUsage.Data>;
+}
+
+export type SubscriptionUsage =
+  | SubscriptionUsage.UngroupedSubscriptionUsage
+  | SubscriptionUsage.GroupedSubscriptionUsage;
+
+export namespace SubscriptionUsage {
+  export interface UngroupedSubscriptionUsage {
+    data: Array<UngroupedSubscriptionUsage.Data>;
+  }
+
+  export namespace UngroupedSubscriptionUsage {
+    export interface Data {
+      billable_metric: Data.BillableMetric;
+
+      usage: Array<Data.Usage>;
+
+      view_mode: 'periodic' | 'cumulative';
+    }
+
+    export namespace Data {
+      export interface BillableMetric {
+        id: string;
+
+        name: string;
+      }
+
+      export interface Usage {
+        quantity: number;
+
+        timeframe_end: string;
+
+        timeframe_start: string;
+      }
+    }
+  }
+
+  export interface GroupedSubscriptionUsage {
+    data: Array<GroupedSubscriptionUsage.Data>;
+
+    pagination_metadata?: Shared.PaginationMetadata | null;
+  }
+
+  export namespace GroupedSubscriptionUsage {
+    export interface Data {
+      billable_metric: Data.BillableMetric;
+
+      metric_group: Data.MetricGroup;
+
+      usage: Array<Data.Usage>;
+
+      view_mode: 'periodic' | 'cumulative';
+    }
+
+    export namespace Data {
+      export interface BillableMetric {
+        id: string;
+
+        name: string;
+      }
+
+      export interface MetricGroup {
+        property_key: string;
+
+        property_value: string;
+      }
+
+      export interface Usage {
+        quantity: number;
+
+        timeframe_end: string;
+
+        timeframe_start: string;
+      }
+    }
+  }
+}
+
+export interface Subscriptions {
+  data: Array<Subscription>;
+
+  pagination_metadata: Shared.PaginationMetadata;
+}
+
+export interface SubscriptionCreateResponse {
+  id: string;
+
+  /**
+   * The current plan phase that is active, only if the subscription's plan has
+   * phases.
+   */
+  active_plan_phase_order: number | null;
+
+  /**
+   * The adjustment intervals for this subscription sorted by the start_date of the
+   * adjustment interval.
+   */
+  adjustment_intervals: Array<SubscriptionCreateResponse.AdjustmentInterval>;
+
+  /**
+   * Determines whether issued invoices for this subscription will automatically be
+   * charged with the saved payment method on the due date. This property defaults to
+   * the plan's behavior. If null, defaults to the customer's setting.
+   */
+  auto_collection: boolean | null;
+
+  billing_cycle_anchor_configuration: SubscriptionCreateResponse.BillingCycleAnchorConfiguration;
+
+  /**
+   * The day of the month on which the billing cycle is anchored. If the maximum
+   * number of days in a month is greater than this value, the last day of the month
+   * is the billing cycle day (e.g. billing_cycle_day=31 for April means the billing
+   * period begins on the 30th.
+   */
+  billing_cycle_day: number;
+
+  created_at: string;
+
+  /**
+   * The end of the current billing period. This is an exclusive timestamp, such that
+   * the instant returned is not part of the billing period. Set to null for
+   * subscriptions that are not currently active.
+   */
+  current_billing_period_end_date: string | null;
+
+  /**
+   * The start date of the current billing period. This is an inclusive timestamp;
+   * the instant returned is exactly the beginning of the billing period. Set to null
+   * if the subscription is not currently active.
+   */
+  current_billing_period_start_date: string | null;
+
+  /**
+   * A customer is a buyer of your products, and the other party to the billing
+   * relationship.
+   *
+   * In Orb, customers are assigned system generated identifiers automatically, but
+   * it's often desirable to have these match existing identifiers in your system. To
+   * avoid having to denormalize Orb ID information, you can pass in an
+   * `external_customer_id` with your own identifier. See
+   * [Customer ID Aliases](/events-and-metrics/customer-aliases) for further
+   * information about how these aliases work in Orb.
+   *
+   * In addition to having an identifier in your system, a customer may exist in a
+   * payment provider solution like Stripe. Use the `payment_provider_id` and the
+   * `payment_provider` enum field to express this mapping.
+   *
+   * A customer also has a timezone (from the standard
+   * [IANA timezone database](https://www.iana.org/time-zones)), which defaults to
+   * your account's timezone. See [Timezone localization](/essentials/timezones) for
+   * information on what this timezone parameter influences within Orb.
+   */
+  customer: CustomersAPI.Customer;
+
+  /**
+   * Determines the default memo on this subscriptions' invoices. Note that if this
+   * is not provided, it is determined by the plan configuration.
+   */
+  default_invoice_memo: string | null;
+
+  /**
+   * @deprecated The discount intervals for this subscription sorted by the
+   * start_date.
+   */
+  discount_intervals: Array<
+    | SubscriptionCreateResponse.AmountDiscountInterval
+    | SubscriptionCreateResponse.PercentageDiscountInterval
+    | SubscriptionCreateResponse.UsageDiscountInterval
+  >;
+
+  /**
+   * The date Orb stops billing for this subscription.
+   */
+  end_date: string | null;
+
+  fixed_fee_quantity_schedule: Array<SubscriptionCreateResponse.FixedFeeQuantitySchedule>;
+
+  invoicing_threshold: string | null;
+
+  /**
+   * @deprecated The maximum intervals for this subscription sorted by the
+   * start_date.
+   */
+  maximum_intervals: Array<SubscriptionCreateResponse.MaximumInterval>;
+
+  /**
+   * User specified key-value pairs for the resource. If not present, this defaults
+   * to an empty dictionary. 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>;
+
+  /**
+   * @deprecated The minimum intervals for this subscription sorted by the
+   * start_date.
+   */
+  minimum_intervals: Array<SubscriptionCreateResponse.MinimumInterval>;
+
+  /**
+   * The name of the subscription.
+   */
+  name: string;
+
+  /**
+   * Determines the difference between the invoice issue date for subscription
+   * invoices as the date that they are due. A value of `0` here represents that the
+   * invoice is due on issue, whereas a value of `30` represents that the customer
+   * has a month to pay the invoice.
+   */
+  net_terms: number;
+
+  /**
+   * A pending subscription change if one exists on this subscription.
+   */
+  pending_subscription_change: SubscriptionCreateResponse.PendingSubscriptionChange | null;
+
+  /**
+   * The [Plan](/core-concepts#plan-and-price) resource represents a plan that can be
+   * subscribed to by a customer. Plans define the billing behavior of the
+   * subscription. You can see more about how to configure prices in the
+   * [Price resource](/reference/price).
+   */
+  plan: PlansAPI.Plan | null;
+
+  /**
+   * The price intervals for this subscription.
+   */
+  price_intervals: Array<SubscriptionCreateResponse.PriceInterval>;
+
+  redeemed_coupon: SubscriptionCreateResponse.RedeemedCoupon | null;
+
+  /**
+   * The date Orb starts billing for this subscription.
+   */
+  start_date: string;
+
+  status: 'active' | 'ended' | 'upcoming';
+
+  trial_info: SubscriptionCreateResponse.TrialInfo;
+
+  /**
+   * The resources that were changed as part of this operation. Only present when
+   * fetched through the subscription changes API or if the
+   * `include_changed_resources` parameter was passed in the request.
+   */
+  changed_resources?: SubscriptionCreateResponse.ChangedResources | null;
+}
+
+export namespace SubscriptionCreateResponse {
+  export interface AdjustmentInterval {
+    id: string;
+
+    adjustment:
+      | AdjustmentInterval.PlanPhaseUsageDiscountAdjustment
+      | AdjustmentInterval.PlanPhaseAmountDiscountAdjustment
+      | AdjustmentInterval.PlanPhasePercentageDiscountAdjustment
+      | AdjustmentInterval.PlanPhaseMinimumAdjustment
+      | AdjustmentInterval.PlanPhaseMaximumAdjustment;
+
+    /**
+     * The price interval IDs that this adjustment applies to.
+     */
+    applies_to_price_interval_ids: Array<string>;
+
+    /**
+     * The end date of the adjustment interval.
+     */
+    end_date: string | null;
+
+    /**
+     * The start date of the adjustment interval.
+     */
+    start_date: string;
+  }
+
+  export namespace AdjustmentInterval {
+    export interface PlanPhaseUsageDiscountAdjustment {
+      id: string;
+
+      adjustment_type: 'usage_discount';
+
+      /**
+       * @deprecated The price IDs that this adjustment applies to.
+       */
+      applies_to_price_ids: Array<string>;
+
+      /**
+       * The filters that determine which prices to apply this adjustment to.
+       */
+      filters: Array<PlanPhaseUsageDiscountAdjustment.Filter>;
+
+      /**
+       * True for adjustments that apply to an entire invocice, false for adjustments
+       * that apply to only one price.
+       */
+      is_invoice_level: boolean;
+
+      /**
+       * The plan phase in which this adjustment is active.
+       */
+      plan_phase_order: number | null;
+
+      /**
+       * The reason for the adjustment.
+       */
+      reason: string | null;
+
+      /**
+       * The number of usage units by which to discount the price this adjustment applies
+       * to in a given billing period.
+       */
+      usage_discount: number;
+    }
+
+    export namespace PlanPhaseUsageDiscountAdjustment {
+      export interface Filter {
+        /**
+         * The property of the price to filter on.
+         */
+        field: 'price_id' | 'item_id' | 'price_type' | 'currency' | 'pricing_unit_id';
+
+        /**
+         * Should prices that match the filter be included or excluded.
+         */
+        operator: 'includes' | 'excludes';
+
+        /**
+         * The IDs or values that match this filter.
+         */
+        values: Array<string>;
+      }
+    }
+
+    export interface PlanPhaseAmountDiscountAdjustment {
+      id: string;
+
+      adjustment_type: 'amount_discount';
+
+      /**
+       * The amount by which to discount the prices this adjustment applies to in a given
+       * billing period.
+       */
+      amount_discount: string;
+
+      /**
+       * @deprecated The price IDs that this adjustment applies to.
+       */
+      applies_to_price_ids: Array<string>;
+
+      /**
+       * The filters that determine which prices to apply this adjustment to.
+       */
+      filters: Array<PlanPhaseAmountDiscountAdjustment.Filter>;
+
+      /**
+       * True for adjustments that apply to an entire invocice, false for adjustments
+       * that apply to only one price.
+       */
+      is_invoice_level: boolean;
+
+      /**
+       * The plan phase in which this adjustment is active.
+       */
+      plan_phase_order: number | null;
+
+      /**
+       * The reason for the adjustment.
+       */
+      reason: string | null;
+    }
+
+    export namespace PlanPhaseAmountDiscountAdjustment {
+      export interface Filter {
+        /**
+         * The property of the price to filter on.
+         */
+        field: 'price_id' | 'item_id' | 'price_type' | 'currency' | 'pricing_unit_id';
+
+        /**
+         * Should prices that match the filter be included or excluded.
+         */
+        operator: 'includes' | 'excludes';
+
+        /**
+         * The IDs or values that match this filter.
+         */
+        values: Array<string>;
+      }
+    }
+
+    export interface PlanPhasePercentageDiscountAdjustment {
+      id: string;
+
+      adjustment_type: 'percentage_discount';
+
+      /**
+       * @deprecated The price IDs that this adjustment applies to.
+       */
+      applies_to_price_ids: Array<string>;
+
+      /**
+       * The filters that determine which prices to apply this adjustment to.
+       */
+      filters: Array<PlanPhasePercentageDiscountAdjustment.Filter>;
+
+      /**
+       * True for adjustments that apply to an entire invocice, false for adjustments
+       * that apply to only one price.
+       */
+      is_invoice_level: boolean;
+
+      /**
+       * The percentage (as a value between 0 and 1) by which to discount the price
+       * intervals this adjustment applies to in a given billing period.
+       */
+      percentage_discount: number;
+
+      /**
+       * The plan phase in which this adjustment is active.
+       */
+      plan_phase_order: number | null;
+
+      /**
+       * The reason for the adjustment.
+       */
+      reason: string | null;
+    }
+
+    export namespace PlanPhasePercentageDiscountAdjustment {
+      export interface Filter {
+        /**
+         * The property of the price to filter on.
+         */
+        field: 'price_id' | 'item_id' | 'price_type' | 'currency' | 'pricing_unit_id';
+
+        /**
+         * Should prices that match the filter be included or excluded.
+         */
+        operator: 'includes' | 'excludes';
+
+        /**
+         * The IDs or values that match this filter.
+         */
+        values: Array<string>;
+      }
+    }
+
+    export interface PlanPhaseMinimumAdjustment {
+      id: string;
+
+      adjustment_type: 'minimum';
+
+      /**
+       * @deprecated The price IDs that this adjustment applies to.
+       */
+      applies_to_price_ids: Array<string>;
+
+      /**
+       * The filters that determine which prices to apply this adjustment to.
+       */
+      filters: Array<PlanPhaseMinimumAdjustment.Filter>;
+
+      /**
+       * True for adjustments that apply to an entire invocice, false for adjustments
+       * that apply to only one price.
+       */
+      is_invoice_level: boolean;
+
+      /**
+       * The item ID that revenue from this minimum will be attributed to.
+       */
+      item_id: string;
+
+      /**
+       * The minimum amount to charge in a given billing period for the prices this
+       * adjustment applies to.
+       */
+      minimum_amount: string;
+
+      /**
+       * The plan phase in which this adjustment is active.
+       */
+      plan_phase_order: number | null;
+
+      /**
+       * The reason for the adjustment.
+       */
+      reason: string | null;
+    }
+
+    export namespace PlanPhaseMinimumAdjustment {
+      export interface Filter {
+        /**
+         * The property of the price to filter on.
+         */
+        field: 'price_id' | 'item_id' | 'price_type' | 'currency' | 'pricing_unit_id';
+
+        /**
+         * Should prices that match the filter be included or excluded.
+         */
+        operator: 'includes' | 'excludes';
+
+        /**
+         * The IDs or values that match this filter.
+         */
+        values: Array<string>;
+      }
+    }
+
+    export interface PlanPhaseMaximumAdjustment {
+      id: string;
+
+      adjustment_type: 'maximum';
+
+      /**
+       * @deprecated The price IDs that this adjustment applies to.
+       */
+      applies_to_price_ids: Array<string>;
+
+      /**
+       * The filters that determine which prices to apply this adjustment to.
+       */
+      filters: Array<PlanPhaseMaximumAdjustment.Filter>;
+
+      /**
+       * True for adjustments that apply to an entire invocice, false for adjustments
+       * that apply to only one price.
+       */
+      is_invoice_level: boolean;
+
+      /**
+       * The maximum amount to charge in a given billing period for the prices this
+       * adjustment applies to.
+       */
+      maximum_amount: string;
+
+      /**
+       * The plan phase in which this adjustment is active.
+       */
+      plan_phase_order: number | null;
+
+      /**
+       * The reason for the adjustment.
+       */
+      reason: string | null;
+    }
+
+    export namespace PlanPhaseMaximumAdjustment {
+      export interface Filter {
+        /**
+         * The property of the price to filter on.
+         */
+        field: 'price_id' | 'item_id' | 'price_type' | 'currency' | 'pricing_unit_id';
+
+        /**
+         * Should prices that match the filter be included or excluded.
+         */
+        operator: 'includes' | 'excludes';
+
+        /**
+         * The IDs or values that match this filter.
+         */
+        values: Array<string>;
+      }
+    }
+  }
+
+  export interface BillingCycleAnchorConfiguration {
+    /**
+     * The day of the month on which the billing cycle is anchored. If the maximum
+     * number of days in a month is greater than this value, the last day of the month
+     * is the billing cycle day (e.g. billing_cycle_day=31 for April means the billing
+     * period begins on the 30th.
+     */
+    day: number;
+
+    /**
+     * The month on which the billing cycle is anchored (e.g. a quarterly price
+     * anchored in February would have cycles starting February, May, August, and
+     * November).
+     */
+    month?: number | null;
+
+    /**
+     * The year on which the billing cycle is anchored (e.g. a 2 year billing cycle
+     * anchored on 2021 would have cycles starting on 2021, 2023, 2025, etc.).
+     */
+    year?: number | null;
+  }
+
+  export interface AmountDiscountInterval {
+    /**
+     * Only available if discount_type is `amount`.
+     */
+    amount_discount: string;
+
+    /**
+     * The price interval ids that this discount interval applies to.
+     */
+    applies_to_price_interval_ids: Array<string>;
+
+    discount_type: 'amount';
+
+    /**
+     * The end date of the discount interval.
+     */
+    end_date: string | null;
+
+    /**
+     * The filters that determine which prices this discount interval applies to.
+     */
+    filters: Array<AmountDiscountInterval.Filter>;
+
+    /**
+     * The start date of the discount interval.
+     */
+    start_date: string;
+  }
+
+  export namespace AmountDiscountInterval {
+    export interface Filter {
+      /**
+       * The property of the price to filter on.
+       */
+      field: 'price_id' | 'item_id' | 'price_type' | 'currency' | 'pricing_unit_id';
+
+      /**
+       * Should prices that match the filter be included or excluded.
+       */
+      operator: 'includes' | 'excludes';
+
+      /**
+       * The IDs or values that match this filter.
+       */
+      values: Array<string>;
+    }
+  }
+
+  export interface PercentageDiscountInterval {
+    /**
+     * The price interval ids that this discount interval applies to.
+     */
+    applies_to_price_interval_ids: Array<string>;
+
+    discount_type: 'percentage';
+
+    /**
+     * The end date of the discount interval.
+     */
+    end_date: string | null;
+
+    /**
+     * The filters that determine which prices this discount interval applies to.
+     */
+    filters: Array<PercentageDiscountInterval.Filter>;
+
+    /**
+     * Only available if discount_type is `percentage`.This is a number between 0
+     * and 1.
+     */
+    percentage_discount: number;
+
+    /**
+     * The start date of the discount interval.
+     */
+    start_date: string;
+  }
+
+  export namespace PercentageDiscountInterval {
+    export interface Filter {
+      /**
+       * The property of the price to filter on.
+       */
+      field: 'price_id' | 'item_id' | 'price_type' | 'currency' | 'pricing_unit_id';
+
+      /**
+       * Should prices that match the filter be included or excluded.
+       */
+      operator: 'includes' | 'excludes';
+
+      /**
+       * The IDs or values that match this filter.
+       */
+      values: Array<string>;
+    }
+  }
+
+  export interface UsageDiscountInterval {
+    /**
+     * The price interval ids that this discount interval applies to.
+     */
+    applies_to_price_interval_ids: Array<string>;
+
+    discount_type: 'usage';
+
+    /**
+     * The end date of the discount interval.
+     */
+    end_date: string | null;
+
+    /**
+     * The filters that determine which prices this discount interval applies to.
+     */
+    filters: Array<UsageDiscountInterval.Filter>;
+
+    /**
+     * The start date of the discount interval.
+     */
+    start_date: string;
+
+    /**
+     * Only available if discount_type is `usage`. Number of usage units that this
+     * discount is for
+     */
+    usage_discount: number;
+  }
+
+  export namespace UsageDiscountInterval {
+    export interface Filter {
+      /**
+       * The property of the price to filter on.
+       */
+      field: 'price_id' | 'item_id' | 'price_type' | 'currency' | 'pricing_unit_id';
+
+      /**
+       * Should prices that match the filter be included or excluded.
+       */
+      operator: 'includes' | 'excludes';
+
+      /**
+       * The IDs or values that match this filter.
+       */
+      values: Array<string>;
+    }
+  }
+
+  export interface FixedFeeQuantitySchedule {
+    end_date: string | null;
+
+    price_id: string;
+
+    quantity: number;
+
+    start_date: string;
+  }
+
+  export interface MaximumInterval {
+    /**
+     * The price interval ids that this maximum interval applies to.
+     */
+    applies_to_price_interval_ids: Array<string>;
+
+    /**
+     * The end date of the maximum interval.
+     */
+    end_date: string | null;
+
+    /**
+     * The filters that determine which prices this maximum interval applies to.
+     */
+    filters: Array<MaximumInterval.Filter>;
+
+    /**
+     * The maximum amount to charge in a given billing period for the price intervals
+     * this transform applies to.
+     */
+    maximum_amount: string;
+
+    /**
+     * The start date of the maximum interval.
+     */
+    start_date: string;
+  }
+
+  export namespace MaximumInterval {
+    export interface Filter {
+      /**
+       * The property of the price to filter on.
+       */
+      field: 'price_id' | 'item_id' | 'price_type' | 'currency' | 'pricing_unit_id';
+
+      /**
+       * Should prices that match the filter be included or excluded.
+       */
+      operator: 'includes' | 'excludes';
+
+      /**
+       * The IDs or values that match this filter.
+       */
+      values: Array<string>;
+    }
+  }
+
+  export interface MinimumInterval {
+    /**
+     * The price interval ids that this minimum interval applies to.
+     */
+    applies_to_price_interval_ids: Array<string>;
+
+    /**
+     * The end date of the minimum interval.
+     */
+    end_date: string | null;
+
+    /**
+     * The filters that determine which prices this minimum interval applies to.
+     */
+    filters: Array<MinimumInterval.Filter>;
+
+    /**
+     * The minimum amount to charge in a given billing period for the price intervals
+     * this minimum applies to.
+     */
+    minimum_amount: string;
+
+    /**
+     * The start date of the minimum interval.
+     */
+    start_date: string;
+  }
+
+  export namespace MinimumInterval {
+    export interface Filter {
+      /**
+       * The property of the price to filter on.
+       */
+      field: 'price_id' | 'item_id' | 'price_type' | 'currency' | 'pricing_unit_id';
+
+      /**
+       * Should prices that match the filter be included or excluded.
+       */
+      operator: 'includes' | 'excludes';
+
+      /**
+       * The IDs or values that match this filter.
+       */
+      values: Array<string>;
+    }
+  }
+
+  /**
+   * A pending subscription change if one exists on this subscription.
+   */
+  export interface PendingSubscriptionChange {
+    id: string;
+  }
+
+  /**
+   * The Price Interval resource represents a period of time for which a price will
+   * bill on a subscription. A subscription’s price intervals define its billing
+   * behavior.
+   */
+  export interface PriceInterval {
+    id: string;
+
+    /**
+     * The day of the month that Orb bills for this price
+     */
+    billing_cycle_day: number;
+
+    /**
+     * The end of the current billing period. This is an exclusive timestamp, such that
+     * the instant returned is exactly the end of the billing period. Set to null if
+     * this price interval is not currently active.
+     */
+    current_billing_period_end_date: string | null;
+
+    /**
+     * The start date of the current billing period. This is an inclusive timestamp;
+     * the instant returned is exactly the beginning of the billing period. Set to null
+     * if this price interval is not currently active.
+     */
+    current_billing_period_start_date: string | null;
+
+    /**
+     * The end date of the price interval. This is the date that Orb stops billing for
+     * this price.
+     */
+    end_date: string | null;
+
+    /**
+     * An additional filter to apply to usage queries.
+     */
+    filter: string | null;
+
+    /**
+     * The fixed fee quantity transitions for this price interval. This is only
+     * relevant for fixed fees.
+     */
+    fixed_fee_quantity_transitions: Array<PriceInterval.FixedFeeQuantityTransition> | null;
+
+    /**
+     * The Price resource represents a price that can be billed on a subscription,
+     * resulting in a charge on an invoice in the form of an invoice line item. Prices
+     * take a quantity and determine an amount to bill.
+     *
+     * Orb supports a few different pricing models out of the box. Each of these models
+     * is serialized differently in a given Price object. The model_type field
+     * determines the key for the configuration object that is present.
+     *
+     * For more on the types of prices, see
+     * [the core concepts documentation](/core-concepts#plan-and-price)
+     */
+    price: PricesAPI.Price;
+
+    /**
+     * The start date of the price interval. This is the date that Orb starts billing
+     * for this price.
+     */
+    start_date: string;
+
+    /**
+     * A list of customer IDs whose usage events will be aggregated and billed under
+     * this price interval.
+     */
+    usage_customer_ids: Array<string> | null;
+  }
+
+  export namespace PriceInterval {
+    export interface FixedFeeQuantityTransition {
+      effective_date: string;
+
+      price_id: string;
+
+      quantity: number;
+    }
+  }
+
+  export interface RedeemedCoupon {
+    coupon_id: string;
+
+    end_date: string | null;
+
+    start_date: string;
+  }
+
+  export interface TrialInfo {
+    end_date: string | null;
+  }
 
-    pagination_metadata?: Shared.PaginationMetadata | null;
-  }
-
-  export namespace GroupedSubscriptionUsage {
-    export interface Data {
-      billable_metric: Data.BillableMetric;
-
-      metric_group: Data.MetricGroup;
-
-      usage: Array<Data.Usage>;
-
-      view_mode: 'periodic' | 'cumulative';
-    }
-
-    export namespace Data {
-      export interface BillableMetric {
-        id: string;
-
-        name: string;
-      }
-
-      export interface MetricGroup {
-        property_key: string;
-
-        property_value: string;
-      }
+  /**
+   * The resources that were changed as part of this operation. Only present when
+   * fetched through the subscription changes API or if the
+   * `include_changed_resources` parameter was passed in the request.
+   */
+  export interface ChangedResources {
+    /**
+     * The credit notes that were created as part of this operation.
+     */
+    created_credit_notes: Array<CreditNotesAPI.CreditNote>;
 
-      export interface Usage {
-        quantity: number;
+    /**
+     * The invoices that were created as part of this operation.
+     */
+    created_invoices: Array<InvoicesAPI.Invoice>;
 
-        timeframe_end: string;
+    /**
+     * The credit notes that were voided as part of this operation.
+     */
+    voided_credit_notes: Array<CreditNotesAPI.CreditNote>;
 
-        timeframe_start: string;
-      }
-    }
+    /**
+     * The invoices that were voided as part of this operation.
+     */
+    voided_invoices: Array<InvoicesAPI.Invoice>;
   }
 }
 
-export interface Subscriptions {
-  data: Array<Subscription>;
-
-  pagination_metadata: Shared.PaginationMetadata;
-}
-
-export interface SubscriptionCreateResponse {
+export interface SubscriptionCancelResponse {
   id: string;
 
   /**
@@ -2028,7 +2924,7 @@ export interface SubscriptionCreateResponse {
    * The adjustment intervals for this subscription sorted by the start_date of the
    * adjustment interval.
    */
-  adjustment_intervals: Array<SubscriptionCreateResponse.AdjustmentInterval>;
+  adjustment_intervals: Array<SubscriptionCancelResponse.AdjustmentInterval>;
 
   /**
    * Determines whether issued invoices for this subscription will automatically be
@@ -2037,7 +2933,7 @@ export interface SubscriptionCreateResponse {
    */
   auto_collection: boolean | null;
 
-  billing_cycle_anchor_configuration: SubscriptionCreateResponse.BillingCycleAnchorConfiguration;
+  billing_cycle_anchor_configuration: SubscriptionCancelResponse.BillingCycleAnchorConfiguration;
 
   /**
    * The day of the month on which the billing cycle is anchored. If the maximum
@@ -2096,9 +2992,9 @@ export interface SubscriptionCreateResponse {
    * start_date.
    */
   discount_intervals: Array<
-    | SubscriptionCreateResponse.AmountDiscountInterval
-    | SubscriptionCreateResponse.PercentageDiscountInterval
-    | SubscriptionCreateResponse.UsageDiscountInterval
+    | SubscriptionCancelResponse.AmountDiscountInterval
+    | SubscriptionCancelResponse.PercentageDiscountInterval
+    | SubscriptionCancelResponse.UsageDiscountInterval
   >;
 
   /**
@@ -2106,7 +3002,7 @@ export interface SubscriptionCreateResponse {
    */
   end_date: string | null;
 
-  fixed_fee_quantity_schedule: Array<SubscriptionCreateResponse.FixedFeeQuantitySchedule>;
+  fixed_fee_quantity_schedule: Array<SubscriptionCancelResponse.FixedFeeQuantitySchedule>;
 
   invoicing_threshold: string | null;
 
@@ -2114,7 +3010,7 @@ export interface SubscriptionCreateResponse {
    * @deprecated The maximum intervals for this subscription sorted by the
    * start_date.
    */
-  maximum_intervals: Array<SubscriptionCreateResponse.MaximumInterval>;
+  maximum_intervals: Array<SubscriptionCancelResponse.MaximumInterval>;
 
   /**
    * User specified key-value pairs for the resource. If not present, this defaults
@@ -2128,7 +3024,7 @@ export interface SubscriptionCreateResponse {
    * @deprecated The minimum intervals for this subscription sorted by the
    * start_date.
    */
-  minimum_intervals: Array<SubscriptionCreateResponse.MinimumInterval>;
+  minimum_intervals: Array<SubscriptionCancelResponse.MinimumInterval>;
 
   /**
    * The name of the subscription.
@@ -2146,7 +3042,7 @@ export interface SubscriptionCreateResponse {
   /**
    * A pending subscription change if one exists on this subscription.
    */
-  pending_subscription_change: SubscriptionCreateResponse.PendingSubscriptionChange | null;
+  pending_subscription_change: SubscriptionCancelResponse.PendingSubscriptionChange | null;
 
   /**
    * The [Plan](/core-concepts#plan-and-price) resource represents a plan that can be
@@ -2159,9 +3055,9 @@ export interface SubscriptionCreateResponse {
   /**
    * The price intervals for this subscription.
    */
-  price_intervals: Array<SubscriptionCreateResponse.PriceInterval>;
+  price_intervals: Array<SubscriptionCancelResponse.PriceInterval>;
 
-  redeemed_coupon: SubscriptionCreateResponse.RedeemedCoupon | null;
+  redeemed_coupon: SubscriptionCancelResponse.RedeemedCoupon | null;
 
   /**
    * The date Orb starts billing for this subscription.
@@ -2170,17 +3066,17 @@ export interface SubscriptionCreateResponse {
 
   status: 'active' | 'ended' | 'upcoming';
 
-  trial_info: SubscriptionCreateResponse.TrialInfo;
+  trial_info: SubscriptionCancelResponse.TrialInfo;
 
   /**
    * The resources that were changed as part of this operation. Only present when
    * fetched through the subscription changes API or if the
    * `include_changed_resources` parameter was passed in the request.
    */
-  changed_resources?: SubscriptionCreateResponse.ChangedResources | null;
+  changed_resources?: SubscriptionCancelResponse.ChangedResources | null;
 }
 
-export namespace SubscriptionCreateResponse {
+export namespace SubscriptionCancelResponse {
   export interface AdjustmentInterval {
     id: string;
 
@@ -2900,7 +3796,85 @@ export namespace SubscriptionCreateResponse {
   }
 }
 
-export interface SubscriptionCancelResponse {
+export interface SubscriptionFetchCostsResponse {
+  data: Array<SubscriptionFetchCostsResponse.Data>;
+}
+
+export namespace SubscriptionFetchCostsResponse {
+  export interface Data {
+    per_price_costs: Array<Data.PerPriceCost>;
+
+    /**
+     * Total costs for the timeframe, excluding any minimums and discounts.
+     */
+    subtotal: string;
+
+    timeframe_end: string;
+
+    timeframe_start: string;
+
+    /**
+     * Total costs for the timeframe, including any minimums and discounts.
+     */
+    total: string;
+  }
+
+  export namespace Data {
+    export interface PerPriceCost {
+      /**
+       * The price object
+       */
+      price: PricesAPI.Price;
+
+      /**
+       * The price the cost is associated with
+       */
+      price_id: string;
+
+      /**
+       * Price's contributions for the timeframe, excluding any minimums and discounts.
+       */
+      subtotal: string;
+
+      /**
+       * Price's contributions for the timeframe, including minimums and discounts.
+       */
+      total: string;
+
+      /**
+       * The price's quantity for the timeframe
+       */
+      quantity?: number | null;
+    }
+  }
+}
+
+export interface SubscriptionFetchScheduleResponse {
+  created_at: string;
+
+  end_date: string | null;
+
+  plan: SubscriptionFetchScheduleResponse.Plan | null;
+
+  start_date: string;
+}
+
+export namespace SubscriptionFetchScheduleResponse {
+  export interface Plan {
+    id: string | null;
+
+    /**
+     * An optional user-defined ID for this plan resource, used throughout the system
+     * as an alias for this Plan. Use this field to identify a plan by an existing
+     * identifier in your system.
+     */
+    external_plan_id: string | null;
+
+    name: string | null;
+  }
+}
+
+export interface SubscriptionPriceIntervalsResponse {
   id: string;
 
   /**
@@ -2913,7 +3887,7 @@ export interface SubscriptionCancelResponse {
    * The adjustment intervals for this subscription sorted by the start_date of the
    * adjustment interval.
    */
-  adjustment_intervals: Array<SubscriptionCancelResponse.AdjustmentInterval>;
+  adjustment_intervals: Array<SubscriptionPriceIntervalsResponse.AdjustmentInterval>;
 
   /**
    * Determines whether issued invoices for this subscription will automatically be
@@ -2922,7 +3896,7 @@ export interface SubscriptionCancelResponse {
    */
   auto_collection: boolean | null;
 
-  billing_cycle_anchor_configuration: SubscriptionCancelResponse.BillingCycleAnchorConfiguration;
+  billing_cycle_anchor_configuration: SubscriptionPriceIntervalsResponse.BillingCycleAnchorConfiguration;
 
   /**
    * The day of the month on which the billing cycle is anchored. If the maximum
@@ -2981,9 +3955,9 @@ export interface SubscriptionCancelResponse {
    * start_date.
    */
   discount_intervals: Array<
-    | SubscriptionCancelResponse.AmountDiscountInterval
-    | SubscriptionCancelResponse.PercentageDiscountInterval
-    | SubscriptionCancelResponse.UsageDiscountInterval
+    | SubscriptionPriceIntervalsResponse.AmountDiscountInterval
+    | SubscriptionPriceIntervalsResponse.PercentageDiscountInterval
+    | SubscriptionPriceIntervalsResponse.UsageDiscountInterval
   >;
 
   /**
@@ -2991,7 +3965,7 @@ export interface SubscriptionCancelResponse {
    */
   end_date: string | null;
 
-  fixed_fee_quantity_schedule: Array<SubscriptionCancelResponse.FixedFeeQuantitySchedule>;
+  fixed_fee_quantity_schedule: Array<SubscriptionPriceIntervalsResponse.FixedFeeQuantitySchedule>;
 
   invoicing_threshold: string | null;
 
@@ -2999,7 +3973,7 @@ export interface SubscriptionCancelResponse {
    * @deprecated The maximum intervals for this subscription sorted by the
    * start_date.
    */
-  maximum_intervals: Array<SubscriptionCancelResponse.MaximumInterval>;
+  maximum_intervals: Array<SubscriptionPriceIntervalsResponse.MaximumInterval>;
 
   /**
    * User specified key-value pairs for the resource. If not present, this defaults
@@ -3013,7 +3987,7 @@ export interface SubscriptionCancelResponse {
    * @deprecated The minimum intervals for this subscription sorted by the
    * start_date.
    */
-  minimum_intervals: Array<SubscriptionCancelResponse.MinimumInterval>;
+  minimum_intervals: Array<SubscriptionPriceIntervalsResponse.MinimumInterval>;
 
   /**
    * The name of the subscription.
@@ -3031,7 +4005,7 @@ export interface SubscriptionCancelResponse {
   /**
    * A pending subscription change if one exists on this subscription.
    */
-  pending_subscription_change: SubscriptionCancelResponse.PendingSubscriptionChange | null;
+  pending_subscription_change: SubscriptionPriceIntervalsResponse.PendingSubscriptionChange | null;
 
   /**
    * The [Plan](/core-concepts#plan-and-price) resource represents a plan that can be
@@ -3044,9 +4018,9 @@ export interface SubscriptionCancelResponse {
   /**
    * The price intervals for this subscription.
    */
-  price_intervals: Array<SubscriptionCancelResponse.PriceInterval>;
+  price_intervals: Array<SubscriptionPriceIntervalsResponse.PriceInterval>;
 
-  redeemed_coupon: SubscriptionCancelResponse.RedeemedCoupon | null;
+  redeemed_coupon: SubscriptionPriceIntervalsResponse.RedeemedCoupon | null;
 
   /**
    * The date Orb starts billing for this subscription.
@@ -3055,17 +4029,17 @@ export interface SubscriptionCancelResponse {
 
   status: 'active' | 'ended' | 'upcoming';
 
-  trial_info: SubscriptionCancelResponse.TrialInfo;
+  trial_info: SubscriptionPriceIntervalsResponse.TrialInfo;
 
   /**
    * The resources that were changed as part of this operation. Only present when
    * fetched through the subscription changes API or if the
    * `include_changed_resources` parameter was passed in the request.
    */
-  changed_resources?: SubscriptionCancelResponse.ChangedResources | null;
+  changed_resources?: SubscriptionPriceIntervalsResponse.ChangedResources | null;
 }
 
-export namespace SubscriptionCancelResponse {
+export namespace SubscriptionPriceIntervalsResponse {
   export interface AdjustmentInterval {
     id: string;
 
@@ -3785,85 +4759,7 @@ export namespace SubscriptionCancelResponse {
   }
 }
 
-export interface SubscriptionFetchCostsResponse {
-  data: Array<SubscriptionFetchCostsResponse.Data>;
-}
-
-export namespace SubscriptionFetchCostsResponse {
-  export interface Data {
-    per_price_costs: Array<Data.PerPriceCost>;
-
-    /**
-     * Total costs for the timeframe, excluding any minimums and discounts.
-     */
-    subtotal: string;
-
-    timeframe_end: string;
-
-    timeframe_start: string;
-
-    /**
-     * Total costs for the timeframe, including any minimums and discounts.
-     */
-    total: string;
-  }
-
-  export namespace Data {
-    export interface PerPriceCost {
-      /**
-       * The price object
-       */
-      price: PricesAPI.Price;
-
-      /**
-       * The price the cost is associated with
-       */
-      price_id: string;
-
-      /**
-       * Price's contributions for the timeframe, excluding any minimums and discounts.
-       */
-      subtotal: string;
-
-      /**
-       * Price's contributions for the timeframe, including minimums and discounts.
-       */
-      total: string;
-
-      /**
-       * The price's quantity for the timeframe
-       */
-      quantity?: number | null;
-    }
-  }
-}
-
-export interface SubscriptionFetchScheduleResponse {
-  created_at: string;
-
-  end_date: string | null;
-
-  plan: SubscriptionFetchScheduleResponse.Plan | null;
-
-  start_date: string;
-}
-
-export namespace SubscriptionFetchScheduleResponse {
-  export interface Plan {
-    id: string | null;
-
-    /**
-     * An optional user-defined ID for this plan resource, used throughout the system
-     * as an alias for this Plan. Use this field to identify a plan by an existing
-     * identifier in your system.
-     */
-    external_plan_id: string | null;
-
-    name: string | null;
-  }
-}
-
-export interface SubscriptionPriceIntervalsResponse {
+export interface SubscriptionRedeemCouponResponse {
   id: string;
 
   /**
@@ -3876,7 +4772,7 @@ export interface SubscriptionPriceIntervalsResponse {
    * The adjustment intervals for this subscription sorted by the start_date of the
    * adjustment interval.
    */
-  adjustment_intervals: Array<SubscriptionPriceIntervalsResponse.AdjustmentInterval>;
+  adjustment_intervals: Array<SubscriptionRedeemCouponResponse.AdjustmentInterval>;
 
   /**
    * Determines whether issued invoices for this subscription will automatically be
@@ -3885,7 +4781,7 @@ export interface SubscriptionPriceIntervalsResponse {
    */
   auto_collection: boolean | null;
 
-  billing_cycle_anchor_configuration: SubscriptionPriceIntervalsResponse.BillingCycleAnchorConfiguration;
+  billing_cycle_anchor_configuration: SubscriptionRedeemCouponResponse.BillingCycleAnchorConfiguration;
 
   /**
    * The day of the month on which the billing cycle is anchored. If the maximum
@@ -3944,9 +4840,9 @@ export interface SubscriptionPriceIntervalsResponse {
    * start_date.
    */
   discount_intervals: Array<
-    | SubscriptionPriceIntervalsResponse.AmountDiscountInterval
-    | SubscriptionPriceIntervalsResponse.PercentageDiscountInterval
-    | SubscriptionPriceIntervalsResponse.UsageDiscountInterval
+    | SubscriptionRedeemCouponResponse.AmountDiscountInterval
+    | SubscriptionRedeemCouponResponse.PercentageDiscountInterval
+    | SubscriptionRedeemCouponResponse.UsageDiscountInterval
   >;
 
   /**
@@ -3954,7 +4850,7 @@ export interface SubscriptionPriceIntervalsResponse {
    */
   end_date: string | null;
 
-  fixed_fee_quantity_schedule: Array<SubscriptionPriceIntervalsResponse.FixedFeeQuantitySchedule>;
+  fixed_fee_quantity_schedule: Array<SubscriptionRedeemCouponResponse.FixedFeeQuantitySchedule>;
 
   invoicing_threshold: string | null;
 
@@ -3962,7 +4858,7 @@ export interface SubscriptionPriceIntervalsResponse {
    * @deprecated The maximum intervals for this subscription sorted by the
    * start_date.
    */
-  maximum_intervals: Array<SubscriptionPriceIntervalsResponse.MaximumInterval>;
+  maximum_intervals: Array<SubscriptionRedeemCouponResponse.MaximumInterval>;
 
   /**
    * User specified key-value pairs for the resource. If not present, this defaults
@@ -3976,7 +4872,7 @@ export interface SubscriptionPriceIntervalsResponse {
    * @deprecated The minimum intervals for this subscription sorted by the
    * start_date.
    */
-  minimum_intervals: Array<SubscriptionPriceIntervalsResponse.MinimumInterval>;
+  minimum_intervals: Array<SubscriptionRedeemCouponResponse.MinimumInterval>;
 
   /**
    * The name of the subscription.
@@ -3994,7 +4890,7 @@ export interface SubscriptionPriceIntervalsResponse {
   /**
    * A pending subscription change if one exists on this subscription.
    */
-  pending_subscription_change: SubscriptionPriceIntervalsResponse.PendingSubscriptionChange | null;
+  pending_subscription_change: SubscriptionRedeemCouponResponse.PendingSubscriptionChange | null;
 
   /**
    * The [Plan](/core-concepts#plan-and-price) resource represents a plan that can be
@@ -4007,9 +4903,9 @@ export interface SubscriptionPriceIntervalsResponse {
   /**
    * The price intervals for this subscription.
    */
-  price_intervals: Array<SubscriptionPriceIntervalsResponse.PriceInterval>;
+  price_intervals: Array<SubscriptionRedeemCouponResponse.PriceInterval>;
 
-  redeemed_coupon: SubscriptionPriceIntervalsResponse.RedeemedCoupon | null;
+  redeemed_coupon: SubscriptionRedeemCouponResponse.RedeemedCoupon | null;
 
   /**
    * The date Orb starts billing for this subscription.
@@ -4018,17 +4914,17 @@ export interface SubscriptionPriceIntervalsResponse {
 
   status: 'active' | 'ended' | 'upcoming';
 
-  trial_info: SubscriptionPriceIntervalsResponse.TrialInfo;
+  trial_info: SubscriptionRedeemCouponResponse.TrialInfo;
 
   /**
    * The resources that were changed as part of this operation. Only present when
    * fetched through the subscription changes API or if the
    * `include_changed_resources` parameter was passed in the request.
    */
-  changed_resources?: SubscriptionPriceIntervalsResponse.ChangedResources | null;
+  changed_resources?: SubscriptionRedeemCouponResponse.ChangedResources | null;
 }
 
-export namespace SubscriptionPriceIntervalsResponse {
+export namespace SubscriptionRedeemCouponResponse {
   export interface AdjustmentInterval {
     id: string;
 
@@ -24891,6 +25787,28 @@ export namespace SubscriptionPriceIntervalsParams {
   }
 }
 
+export interface SubscriptionRedeemCouponParams {
+  change_option: 'requested_date' | 'end_of_subscription_term' | 'immediate';
+
+  /**
+   * Coupon ID to be redeemed for this subscription.
+   */
+  coupon_id: string;
+
+  /**
+   * If false, this request will fail if it would void an issued invoice or create a
+   * credit note. Consider using this as a safety mechanism if you do not expect
+   * existing invoices to be changed.
+   */
+  allow_invoice_credit_or_void?: boolean | null;
+
+  /**
+   * The date that the coupon discount should take effect. This parameter can only be
+   * passed if the `change_option` is `requested_date`.
+   */
+  change_date?: string | null;
+}
+
 export interface SubscriptionSchedulePlanChangeParams {
   change_option: 'requested_date' | 'end_of_subscription_term' | 'immediate';
 
@@ -34242,6 +35160,7 @@ export declare namespace Subscriptions {
     type SubscriptionFetchCostsResponse as SubscriptionFetchCostsResponse,
     type SubscriptionFetchScheduleResponse as SubscriptionFetchScheduleResponse,
     type SubscriptionPriceIntervalsResponse as SubscriptionPriceIntervalsResponse,
+    type SubscriptionRedeemCouponResponse as SubscriptionRedeemCouponResponse,
     type SubscriptionSchedulePlanChangeResponse as SubscriptionSchedulePlanChangeResponse,
     type SubscriptionTriggerPhaseResponse as SubscriptionTriggerPhaseResponse,
     type SubscriptionUnscheduleCancellationResponse as SubscriptionUnscheduleCancellationResponse,
@@ -34259,6 +35178,7 @@ export declare namespace Subscriptions {
     type SubscriptionFetchScheduleParams as SubscriptionFetchScheduleParams,
     type SubscriptionFetchUsageParams as SubscriptionFetchUsageParams,
     type SubscriptionPriceIntervalsParams as SubscriptionPriceIntervalsParams,
+    type SubscriptionRedeemCouponParams as SubscriptionRedeemCouponParams,
     type SubscriptionSchedulePlanChangeParams as SubscriptionSchedulePlanChangeParams,
     type SubscriptionTriggerPhaseParams as SubscriptionTriggerPhaseParams,
     type SubscriptionUnscheduleFixedFeeQuantityUpdatesParams as SubscriptionUnscheduleFixedFeeQuantityUpdatesParams,