dodopayments 1.51.1__py3-none-any.whl → 1.56.5__py3-none-any.whl

dodopayments/resources/subscriptions.py

@@ -16,8 +16,9 @@ from ..types import (
     subscription_create_params,
     subscription_update_params,
     subscription_change_plan_params,
+    subscription_retrieve_usage_history_params,
 )
-from .._types import NOT_GIVEN, Body, Query, Headers, NoneType, NotGiven
+from .._types import Body, Omit, Query, Headers, NoneType, NotGiven, omit, not_given
 from .._utils import maybe_transform, async_maybe_transform
 from .._compat import cached_property
 from .._resource import SyncAPIResource, AsyncAPIResource
@@ -40,6 +41,7 @@ from ..types.subscription_list_response import SubscriptionListResponse
 from ..types.on_demand_subscription_param import OnDemandSubscriptionParam
 from ..types.subscription_charge_response import SubscriptionChargeResponse
 from ..types.subscription_create_response import SubscriptionCreateResponse
+from ..types.subscription_retrieve_usage_history_response import SubscriptionRetrieveUsageHistoryResponse
 
 __all__ = ["SubscriptionsResource", "AsyncSubscriptionsResource"]
 
@@ -71,23 +73,24 @@ class SubscriptionsResource(SyncAPIResource):
         customer: CustomerRequestParam,
         product_id: str,
         quantity: int,
-        addons: Optional[Iterable[AttachAddonParam]] | NotGiven = NOT_GIVEN,
-        allowed_payment_method_types: Optional[List[PaymentMethodTypes]] | NotGiven = NOT_GIVEN,
-        billing_currency: Optional[Currency] | NotGiven = NOT_GIVEN,
-        discount_code: Optional[str] | NotGiven = NOT_GIVEN,
-        metadata: Dict[str, str] | NotGiven = NOT_GIVEN,
-        on_demand: Optional[OnDemandSubscriptionParam] | NotGiven = NOT_GIVEN,
-        payment_link: Optional[bool] | NotGiven = NOT_GIVEN,
-        return_url: Optional[str] | NotGiven = NOT_GIVEN,
-        show_saved_payment_methods: bool | NotGiven = NOT_GIVEN,
-        tax_id: Optional[str] | NotGiven = NOT_GIVEN,
-        trial_period_days: Optional[int] | NotGiven = NOT_GIVEN,
+        addons: Optional[Iterable[AttachAddonParam]] | Omit = omit,
+        allowed_payment_method_types: Optional[List[PaymentMethodTypes]] | Omit = omit,
+        billing_currency: Optional[Currency] | Omit = omit,
+        discount_code: Optional[str] | Omit = omit,
+        force_3ds: Optional[bool] | Omit = omit,
+        metadata: Dict[str, str] | Omit = omit,
+        on_demand: Optional[OnDemandSubscriptionParam] | Omit = omit,
+        payment_link: Optional[bool] | Omit = omit,
+        return_url: Optional[str] | Omit = omit,
+        show_saved_payment_methods: bool | Omit = omit,
+        tax_id: Optional[str] | Omit = omit,
+        trial_period_days: Optional[int] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
         extra_query: Query | None = None,
         extra_body: Body | None = None,
-        timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> SubscriptionCreateResponse:
         """
         Args:
@@ -113,6 +116,8 @@ class SubscriptionsResource(SyncAPIResource):
 
           discount_code: Discount Code to apply to the subscription
 
+          force_3ds: Override merchant default 3DS behaviour for this subscription
+
           metadata: Additional metadata for the subscription Defaults to empty if not specified
 
           payment_link: If true, generates a payment link. Defaults to false if not specified.
@@ -147,6 +152,7 @@ class SubscriptionsResource(SyncAPIResource):
                     "allowed_payment_method_types": allowed_payment_method_types,
                     "billing_currency": billing_currency,
                     "discount_code": discount_code,
+                    "force_3ds": force_3ds,
                     "metadata": metadata,
                     "on_demand": on_demand,
                     "payment_link": payment_link,
@@ -172,7 +178,7 @@ class SubscriptionsResource(SyncAPIResource):
         extra_headers: Headers | None = None,
         extra_query: Query | None = None,
         extra_body: Body | None = None,
-        timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> Subscription:
         """
         Args:
@@ -198,19 +204,20 @@ class SubscriptionsResource(SyncAPIResource):
         self,
         subscription_id: str,
         *,
-        billing: Optional[BillingAddressParam] | NotGiven = NOT_GIVEN,
-        cancel_at_next_billing_date: Optional[bool] | NotGiven = NOT_GIVEN,
-        disable_on_demand: Optional[subscription_update_params.DisableOnDemand] | NotGiven = NOT_GIVEN,
-        metadata: Optional[Dict[str, str]] | NotGiven = NOT_GIVEN,
-        next_billing_date: Union[str, datetime, None] | NotGiven = NOT_GIVEN,
-        status: Optional[SubscriptionStatus] | NotGiven = NOT_GIVEN,
-        tax_id: Optional[str] | NotGiven = NOT_GIVEN,
+        billing: Optional[BillingAddressParam] | Omit = omit,
+        cancel_at_next_billing_date: Optional[bool] | Omit = omit,
+        customer_name: Optional[str] | Omit = omit,
+        disable_on_demand: Optional[subscription_update_params.DisableOnDemand] | Omit = omit,
+        metadata: Optional[Dict[str, str]] | Omit = omit,
+        next_billing_date: Union[str, datetime, None] | Omit = omit,
+        status: Optional[SubscriptionStatus] | Omit = omit,
+        tax_id: Optional[str] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
         extra_query: Query | None = None,
         extra_body: Body | None = None,
-        timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> Subscription:
         """
         Args:
@@ -232,6 +239,7 @@ class SubscriptionsResource(SyncAPIResource):
                 {
                     "billing": billing,
                     "cancel_at_next_billing_date": cancel_at_next_billing_date,
+                    "customer_name": customer_name,
                     "disable_on_demand": disable_on_demand,
                     "metadata": metadata,
                     "next_billing_date": next_billing_date,
@@ -249,19 +257,19 @@ class SubscriptionsResource(SyncAPIResource):
     def list(
         self,
         *,
-        brand_id: str | NotGiven = NOT_GIVEN,
-        created_at_gte: Union[str, datetime] | NotGiven = NOT_GIVEN,
-        created_at_lte: Union[str, datetime] | NotGiven = NOT_GIVEN,
-        customer_id: str | NotGiven = NOT_GIVEN,
-        page_number: int | NotGiven = NOT_GIVEN,
-        page_size: int | NotGiven = NOT_GIVEN,
-        status: Literal["pending", "active", "on_hold", "cancelled", "failed", "expired"] | NotGiven = NOT_GIVEN,
+        brand_id: str | Omit = omit,
+        created_at_gte: Union[str, datetime] | Omit = omit,
+        created_at_lte: Union[str, datetime] | Omit = omit,
+        customer_id: str | Omit = omit,
+        page_number: int | Omit = omit,
+        page_size: int | Omit = omit,
+        status: Literal["pending", "active", "on_hold", "cancelled", "failed", "expired"] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
         extra_query: Query | None = None,
         extra_body: Body | None = None,
-        timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> SyncDefaultPageNumberPagination[SubscriptionListResponse]:
         """
         Args:
@@ -318,13 +326,13 @@ class SubscriptionsResource(SyncAPIResource):
         product_id: str,
         proration_billing_mode: Literal["prorated_immediately", "full_immediately", "difference_immediately"],
         quantity: int,
-        addons: Optional[Iterable[AttachAddonParam]] | NotGiven = NOT_GIVEN,
+        addons: Optional[Iterable[AttachAddonParam]] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
         extra_query: Query | None = None,
         extra_body: Body | None = None,
-        timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> None:
         """
         Args:
@@ -370,16 +378,17 @@ class SubscriptionsResource(SyncAPIResource):
         subscription_id: str,
         *,
         product_price: int,
-        adaptive_currency_fees_inclusive: Optional[bool] | NotGiven = NOT_GIVEN,
-        metadata: Optional[Dict[str, str]] | NotGiven = NOT_GIVEN,
-        product_currency: Optional[Currency] | NotGiven = NOT_GIVEN,
-        product_description: Optional[str] | NotGiven = NOT_GIVEN,
+        adaptive_currency_fees_inclusive: Optional[bool] | Omit = omit,
+        customer_balance_config: Optional[subscription_charge_params.CustomerBalanceConfig] | Omit = omit,
+        metadata: Optional[Dict[str, str]] | Omit = omit,
+        product_currency: Optional[Currency] | Omit = omit,
+        product_description: Optional[str] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
         extra_query: Query | None = None,
         extra_body: Body | None = None,
-        timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> SubscriptionChargeResponse:
         """Args:
           product_price: The product price.
@@ -391,6 +400,8 @@ class SubscriptionsResource(SyncAPIResource):
               added on top (false). This field is ignored if adaptive pricing is not enabled
               for the business.
 
+          customer_balance_config: Specify how customer balance is used for the payment
+
           metadata: Metadata for the payment. If not passed, the metadata of the subscription will
               be taken
 
@@ -416,6 +427,7 @@ class SubscriptionsResource(SyncAPIResource):
                 {
                     "product_price": product_price,
                     "adaptive_currency_fees_inclusive": adaptive_currency_fees_inclusive,
+                    "customer_balance_config": customer_balance_config,
                     "metadata": metadata,
                     "product_currency": product_currency,
                     "product_description": product_description,
@@ -428,6 +440,109 @@ class SubscriptionsResource(SyncAPIResource):
             cast_to=SubscriptionChargeResponse,
         )
 
+    def retrieve_usage_history(
+        self,
+        subscription_id: str,
+        *,
+        end_date: Union[str, datetime, None] | Omit = omit,
+        meter_id: Optional[str] | Omit = omit,
+        page_number: Optional[int] | Omit = omit,
+        page_size: Optional[int] | Omit = omit,
+        start_date: Union[str, datetime, None] | Omit = omit,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> SyncDefaultPageNumberPagination[SubscriptionRetrieveUsageHistoryResponse]:
+        """
+        Get detailed usage history for a subscription that includes usage-based billing
+        (metered components). This endpoint provides insights into customer usage
+        patterns and billing calculations over time.
+
+        ## What You'll Get:
+
+        - **Billing periods**: Each item represents a billing cycle with start and end
+          dates
+        - **Meter usage**: Detailed breakdown of usage for each meter configured on the
+          subscription
+        - **Usage calculations**: Total units consumed, free threshold units, and
+          chargeable units
+        - **Historical tracking**: Complete audit trail of usage-based charges
+
+        ## Use Cases:
+
+        - **Customer support**: Investigate billing questions and usage discrepancies
+        - **Usage analytics**: Analyze customer consumption patterns over time
+        - **Billing transparency**: Provide customers with detailed usage breakdowns
+        - **Revenue optimization**: Identify usage trends to optimize pricing strategies
+
+        ## Filtering Options:
+
+        - **Date range filtering**: Get usage history for specific time periods
+        - **Meter-specific filtering**: Focus on usage for a particular meter
+        - **Pagination**: Navigate through large usage histories efficiently
+
+        ## Important Notes:
+
+        - Only returns data for subscriptions with usage-based (metered) components
+        - Usage history is organized by billing periods (subscription cycles)
+        - Free threshold units are calculated and displayed separately from chargeable
+          units
+        - Historical data is preserved even if meter configurations change
+
+        ## Example Query Patterns:
+
+        - Get last 3 months:
+          `?start_date=2024-01-01T00:00:00Z&end_date=2024-03-31T23:59:59Z`
+        - Filter by meter: `?meter_id=mtr_api_requests`
+        - Paginate results: `?page_size=20&page_number=1`
+        - Recent usage: `?start_date=2024-03-01T00:00:00Z` (from March 1st to now)
+
+        Args:
+          end_date: Filter by end date (inclusive)
+
+          meter_id: Filter by specific meter ID
+
+          page_number: Page number (default: 0)
+
+          page_size: Page size (default: 10, max: 100)
+
+          start_date: Filter by start date (inclusive)
+
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        if not subscription_id:
+            raise ValueError(f"Expected a non-empty value for `subscription_id` but received {subscription_id!r}")
+        return self._get_api_list(
+            f"/subscriptions/{subscription_id}/usage-history",
+            page=SyncDefaultPageNumberPagination[SubscriptionRetrieveUsageHistoryResponse],
+            options=make_request_options(
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                query=maybe_transform(
+                    {
+                        "end_date": end_date,
+                        "meter_id": meter_id,
+                        "page_number": page_number,
+                        "page_size": page_size,
+                        "start_date": start_date,
+                    },
+                    subscription_retrieve_usage_history_params.SubscriptionRetrieveUsageHistoryParams,
+                ),
+            ),
+            model=SubscriptionRetrieveUsageHistoryResponse,
+        )
+
 
 class AsyncSubscriptionsResource(AsyncAPIResource):
     @cached_property
@@ -456,23 +571,24 @@ class AsyncSubscriptionsResource(AsyncAPIResource):
         customer: CustomerRequestParam,
         product_id: str,
         quantity: int,
-        addons: Optional[Iterable[AttachAddonParam]] | NotGiven = NOT_GIVEN,
-        allowed_payment_method_types: Optional[List[PaymentMethodTypes]] | NotGiven = NOT_GIVEN,
-        billing_currency: Optional[Currency] | NotGiven = NOT_GIVEN,
-        discount_code: Optional[str] | NotGiven = NOT_GIVEN,
-        metadata: Dict[str, str] | NotGiven = NOT_GIVEN,
-        on_demand: Optional[OnDemandSubscriptionParam] | NotGiven = NOT_GIVEN,
-        payment_link: Optional[bool] | NotGiven = NOT_GIVEN,
-        return_url: Optional[str] | NotGiven = NOT_GIVEN,
-        show_saved_payment_methods: bool | NotGiven = NOT_GIVEN,
-        tax_id: Optional[str] | NotGiven = NOT_GIVEN,
-        trial_period_days: Optional[int] | NotGiven = NOT_GIVEN,
+        addons: Optional[Iterable[AttachAddonParam]] | Omit = omit,
+        allowed_payment_method_types: Optional[List[PaymentMethodTypes]] | Omit = omit,
+        billing_currency: Optional[Currency] | Omit = omit,
+        discount_code: Optional[str] | Omit = omit,
+        force_3ds: Optional[bool] | Omit = omit,
+        metadata: Dict[str, str] | Omit = omit,
+        on_demand: Optional[OnDemandSubscriptionParam] | Omit = omit,
+        payment_link: Optional[bool] | Omit = omit,
+        return_url: Optional[str] | Omit = omit,
+        show_saved_payment_methods: bool | Omit = omit,
+        tax_id: Optional[str] | Omit = omit,
+        trial_period_days: Optional[int] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
         extra_query: Query | None = None,
         extra_body: Body | None = None,
-        timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> SubscriptionCreateResponse:
         """
         Args:
@@ -498,6 +614,8 @@ class AsyncSubscriptionsResource(AsyncAPIResource):
 
           discount_code: Discount Code to apply to the subscription
 
+          force_3ds: Override merchant default 3DS behaviour for this subscription
+
           metadata: Additional metadata for the subscription Defaults to empty if not specified
 
           payment_link: If true, generates a payment link. Defaults to false if not specified.
@@ -532,6 +650,7 @@ class AsyncSubscriptionsResource(AsyncAPIResource):
                     "allowed_payment_method_types": allowed_payment_method_types,
                     "billing_currency": billing_currency,
                     "discount_code": discount_code,
+                    "force_3ds": force_3ds,
                     "metadata": metadata,
                     "on_demand": on_demand,
                     "payment_link": payment_link,
@@ -557,7 +676,7 @@ class AsyncSubscriptionsResource(AsyncAPIResource):
         extra_headers: Headers | None = None,
         extra_query: Query | None = None,
         extra_body: Body | None = None,
-        timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> Subscription:
         """
         Args:
@@ -583,19 +702,20 @@ class AsyncSubscriptionsResource(AsyncAPIResource):
         self,
         subscription_id: str,
         *,
-        billing: Optional[BillingAddressParam] | NotGiven = NOT_GIVEN,
-        cancel_at_next_billing_date: Optional[bool] | NotGiven = NOT_GIVEN,
-        disable_on_demand: Optional[subscription_update_params.DisableOnDemand] | NotGiven = NOT_GIVEN,
-        metadata: Optional[Dict[str, str]] | NotGiven = NOT_GIVEN,
-        next_billing_date: Union[str, datetime, None] | NotGiven = NOT_GIVEN,
-        status: Optional[SubscriptionStatus] | NotGiven = NOT_GIVEN,
-        tax_id: Optional[str] | NotGiven = NOT_GIVEN,
+        billing: Optional[BillingAddressParam] | Omit = omit,
+        cancel_at_next_billing_date: Optional[bool] | Omit = omit,
+        customer_name: Optional[str] | Omit = omit,
+        disable_on_demand: Optional[subscription_update_params.DisableOnDemand] | Omit = omit,
+        metadata: Optional[Dict[str, str]] | Omit = omit,
+        next_billing_date: Union[str, datetime, None] | Omit = omit,
+        status: Optional[SubscriptionStatus] | Omit = omit,
+        tax_id: Optional[str] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
         extra_query: Query | None = None,
         extra_body: Body | None = None,
-        timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> Subscription:
         """
         Args:
@@ -617,6 +737,7 @@ class AsyncSubscriptionsResource(AsyncAPIResource):
                 {
                     "billing": billing,
                     "cancel_at_next_billing_date": cancel_at_next_billing_date,
+                    "customer_name": customer_name,
                     "disable_on_demand": disable_on_demand,
                     "metadata": metadata,
                     "next_billing_date": next_billing_date,
@@ -634,19 +755,19 @@ class AsyncSubscriptionsResource(AsyncAPIResource):
     def list(
         self,
         *,
-        brand_id: str | NotGiven = NOT_GIVEN,
-        created_at_gte: Union[str, datetime] | NotGiven = NOT_GIVEN,
-        created_at_lte: Union[str, datetime] | NotGiven = NOT_GIVEN,
-        customer_id: str | NotGiven = NOT_GIVEN,
-        page_number: int | NotGiven = NOT_GIVEN,
-        page_size: int | NotGiven = NOT_GIVEN,
-        status: Literal["pending", "active", "on_hold", "cancelled", "failed", "expired"] | NotGiven = NOT_GIVEN,
+        brand_id: str | Omit = omit,
+        created_at_gte: Union[str, datetime] | Omit = omit,
+        created_at_lte: Union[str, datetime] | Omit = omit,
+        customer_id: str | Omit = omit,
+        page_number: int | Omit = omit,
+        page_size: int | Omit = omit,
+        status: Literal["pending", "active", "on_hold", "cancelled", "failed", "expired"] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
         extra_query: Query | None = None,
         extra_body: Body | None = None,
-        timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> AsyncPaginator[SubscriptionListResponse, AsyncDefaultPageNumberPagination[SubscriptionListResponse]]:
         """
         Args:
@@ -703,13 +824,13 @@ class AsyncSubscriptionsResource(AsyncAPIResource):
         product_id: str,
         proration_billing_mode: Literal["prorated_immediately", "full_immediately", "difference_immediately"],
         quantity: int,
-        addons: Optional[Iterable[AttachAddonParam]] | NotGiven = NOT_GIVEN,
+        addons: Optional[Iterable[AttachAddonParam]] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
         extra_query: Query | None = None,
         extra_body: Body | None = None,
-        timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> None:
         """
         Args:
@@ -755,16 +876,17 @@ class AsyncSubscriptionsResource(AsyncAPIResource):
         subscription_id: str,
         *,
         product_price: int,
-        adaptive_currency_fees_inclusive: Optional[bool] | NotGiven = NOT_GIVEN,
-        metadata: Optional[Dict[str, str]] | NotGiven = NOT_GIVEN,
-        product_currency: Optional[Currency] | NotGiven = NOT_GIVEN,
-        product_description: Optional[str] | NotGiven = NOT_GIVEN,
+        adaptive_currency_fees_inclusive: Optional[bool] | Omit = omit,
+        customer_balance_config: Optional[subscription_charge_params.CustomerBalanceConfig] | Omit = omit,
+        metadata: Optional[Dict[str, str]] | Omit = omit,
+        product_currency: Optional[Currency] | Omit = omit,
+        product_description: Optional[str] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
         extra_query: Query | None = None,
         extra_body: Body | None = None,
-        timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> SubscriptionChargeResponse:
         """Args:
           product_price: The product price.
@@ -776,6 +898,8 @@ class AsyncSubscriptionsResource(AsyncAPIResource):
               added on top (false). This field is ignored if adaptive pricing is not enabled
               for the business.
 
+          customer_balance_config: Specify how customer balance is used for the payment
+
           metadata: Metadata for the payment. If not passed, the metadata of the subscription will
               be taken
 
@@ -801,6 +925,7 @@ class AsyncSubscriptionsResource(AsyncAPIResource):
                 {
                     "product_price": product_price,
                     "adaptive_currency_fees_inclusive": adaptive_currency_fees_inclusive,
+                    "customer_balance_config": customer_balance_config,
                     "metadata": metadata,
                     "product_currency": product_currency,
                     "product_description": product_description,
@@ -813,6 +938,112 @@ class AsyncSubscriptionsResource(AsyncAPIResource):
             cast_to=SubscriptionChargeResponse,
         )
 
+    def retrieve_usage_history(
+        self,
+        subscription_id: str,
+        *,
+        end_date: Union[str, datetime, None] | Omit = omit,
+        meter_id: Optional[str] | Omit = omit,
+        page_number: Optional[int] | Omit = omit,
+        page_size: Optional[int] | Omit = omit,
+        start_date: Union[str, datetime, None] | Omit = omit,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> AsyncPaginator[
+        SubscriptionRetrieveUsageHistoryResponse,
+        AsyncDefaultPageNumberPagination[SubscriptionRetrieveUsageHistoryResponse],
+    ]:
+        """
+        Get detailed usage history for a subscription that includes usage-based billing
+        (metered components). This endpoint provides insights into customer usage
+        patterns and billing calculations over time.
+
+        ## What You'll Get:
+
+        - **Billing periods**: Each item represents a billing cycle with start and end
+          dates
+        - **Meter usage**: Detailed breakdown of usage for each meter configured on the
+          subscription
+        - **Usage calculations**: Total units consumed, free threshold units, and
+          chargeable units
+        - **Historical tracking**: Complete audit trail of usage-based charges
+
+        ## Use Cases:
+
+        - **Customer support**: Investigate billing questions and usage discrepancies
+        - **Usage analytics**: Analyze customer consumption patterns over time
+        - **Billing transparency**: Provide customers with detailed usage breakdowns
+        - **Revenue optimization**: Identify usage trends to optimize pricing strategies
+
+        ## Filtering Options:
+
+        - **Date range filtering**: Get usage history for specific time periods
+        - **Meter-specific filtering**: Focus on usage for a particular meter
+        - **Pagination**: Navigate through large usage histories efficiently
+
+        ## Important Notes:
+
+        - Only returns data for subscriptions with usage-based (metered) components
+        - Usage history is organized by billing periods (subscription cycles)
+        - Free threshold units are calculated and displayed separately from chargeable
+          units
+        - Historical data is preserved even if meter configurations change
+
+        ## Example Query Patterns:
+
+        - Get last 3 months:
+          `?start_date=2024-01-01T00:00:00Z&end_date=2024-03-31T23:59:59Z`
+        - Filter by meter: `?meter_id=mtr_api_requests`
+        - Paginate results: `?page_size=20&page_number=1`
+        - Recent usage: `?start_date=2024-03-01T00:00:00Z` (from March 1st to now)
+
+        Args:
+          end_date: Filter by end date (inclusive)
+
+          meter_id: Filter by specific meter ID
+
+          page_number: Page number (default: 0)
+
+          page_size: Page size (default: 10, max: 100)
+
+          start_date: Filter by start date (inclusive)
+
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        if not subscription_id:
+            raise ValueError(f"Expected a non-empty value for `subscription_id` but received {subscription_id!r}")
+        return self._get_api_list(
+            f"/subscriptions/{subscription_id}/usage-history",
+            page=AsyncDefaultPageNumberPagination[SubscriptionRetrieveUsageHistoryResponse],
+            options=make_request_options(
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                query=maybe_transform(
+                    {
+                        "end_date": end_date,
+                        "meter_id": meter_id,
+                        "page_number": page_number,
+                        "page_size": page_size,
+                        "start_date": start_date,
+                    },
+                    subscription_retrieve_usage_history_params.SubscriptionRetrieveUsageHistoryParams,
+                ),
+            ),
+            model=SubscriptionRetrieveUsageHistoryResponse,
+        )
+
 
 class SubscriptionsResourceWithRawResponse:
     def __init__(self, subscriptions: SubscriptionsResource) -> None:
@@ -836,6 +1067,9 @@ class SubscriptionsResourceWithRawResponse:
         self.charge = to_raw_response_wrapper(
             subscriptions.charge,
         )
+        self.retrieve_usage_history = to_raw_response_wrapper(
+            subscriptions.retrieve_usage_history,
+        )
 
 
 class AsyncSubscriptionsResourceWithRawResponse:
@@ -860,6 +1094,9 @@ class AsyncSubscriptionsResourceWithRawResponse:
         self.charge = async_to_raw_response_wrapper(
             subscriptions.charge,
         )
+        self.retrieve_usage_history = async_to_raw_response_wrapper(
+            subscriptions.retrieve_usage_history,
+        )
 
 
 class SubscriptionsResourceWithStreamingResponse:
@@ -884,6 +1121,9 @@ class SubscriptionsResourceWithStreamingResponse:
         self.charge = to_streamed_response_wrapper(
             subscriptions.charge,
         )
+        self.retrieve_usage_history = to_streamed_response_wrapper(
+            subscriptions.retrieve_usage_history,
+        )
 
 
 class AsyncSubscriptionsResourceWithStreamingResponse:
@@ -908,3 +1148,6 @@ class AsyncSubscriptionsResourceWithStreamingResponse:
         self.charge = async_to_streamed_response_wrapper(
             subscriptions.charge,
         )
+        self.retrieve_usage_history = async_to_streamed_response_wrapper(
+            subscriptions.retrieve_usage_history,
+        )