pinelabs-python 0.1.0__py3-none-any.whl

pinelabs/subscriptions_subscriptions/client.py

@@ -0,0 +1,1014 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import datetime as dt
+import typing
+
+from ..core.client_wrapper import AsyncClientWrapper, SyncClientWrapper
+from ..core.request_options import RequestOptions
+from ..types.bank_account import BankAccount
+from ..types.create_subscription_response import CreateSubscriptionResponse
+from ..types.list_subscriptions_response import ListSubscriptionsResponse
+from ..types.subscription_detail import SubscriptionDetail
+from .raw_client import AsyncRawSubscriptionsSubscriptionsClient, RawSubscriptionsSubscriptionsClient
+from .types.create_subscription_request_allowed_payment_methods_item import (
+    CreateSubscriptionRequestAllowedPaymentMethodsItem,
+)
+from .types.create_subscription_request_integration_mode import CreateSubscriptionRequestIntegrationMode
+from .types.list_subscriptions_request_amount_range import ListSubscriptionsRequestAmountRange
+
+# this is used as the default value for optional parameters
+OMIT = typing.cast(typing.Any, ...)
+
+
+class SubscriptionsSubscriptionsClient:
+    def __init__(self, *, client_wrapper: SyncClientWrapper):
+        self._raw_client = RawSubscriptionsSubscriptionsClient(client_wrapper=client_wrapper)
+
+    @property
+    def with_raw_response(self) -> RawSubscriptionsSubscriptionsClient:
+        """
+        Retrieves a raw implementation of this client that returns raw responses.
+
+        Returns
+        -------
+        RawSubscriptionsSubscriptionsClient
+        """
+        return self._raw_client
+
+    def list_subscriptions(
+        self,
+        *,
+        plan_id: typing.Optional[str] = None,
+        status: typing.Optional[str] = None,
+        amount: typing.Optional[int] = None,
+        amount_range: typing.Optional[ListSubscriptionsRequestAmountRange] = None,
+        start_date: typing.Optional[dt.datetime] = None,
+        end_date: typing.Optional[dt.datetime] = None,
+        size: typing.Optional[int] = None,
+        page: typing.Optional[int] = None,
+        sort: typing.Optional[str] = None,
+        frequency: typing.Optional[str] = None,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> ListSubscriptionsResponse:
+        """
+        Retrieves all subscriptions. Supports filtering by plan_id, status,
+        amount, date range, frequency, and pagination.
+
+        Parameters
+        ----------
+        plan_id : typing.Optional[str]
+            Filter by plan ID.
+
+        status : typing.Optional[str]
+            Filter by subscription status.
+
+        amount : typing.Optional[int]
+            Filter by amount value.
+
+        amount_range : typing.Optional[ListSubscriptionsRequestAmountRange]
+            Amount comparison operator.
+
+        start_date : typing.Optional[dt.datetime]
+            Filter subscriptions with start date after this value.
+
+        end_date : typing.Optional[dt.datetime]
+            Filter subscriptions with end date before this value.
+
+        size : typing.Optional[int]
+            Number of items per page.
+
+        page : typing.Optional[int]
+            Page number.
+
+        sort : typing.Optional[str]
+            Sort field and direction.
+
+        frequency : typing.Optional[str]
+            Filter by billing frequency.
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        ListSubscriptionsResponse
+            Subscriptions retrieved successfully.
+
+        Examples
+        --------
+        import datetime
+
+        from pinelabs import PinelabsApi
+
+        client = PinelabsApi(
+            request_timestamp="YOUR_REQUEST_TIMESTAMP",
+            request_id="YOUR_REQUEST_ID",
+            token="YOUR_TOKEN",
+        )
+        client.subscriptions_subscriptions.list_subscriptions(
+            plan_id="v1-plan-4405071524-aa-qlAtAf",
+            status="ACTIVE",
+            start_date=datetime.datetime.fromisoformat(
+                "2022-02-01 17:32:28+00:00",
+            ),
+            end_date=datetime.datetime.fromisoformat(
+                "2025-12-31 23:59:59+00:00",
+            ),
+            sort="id,asc",
+            frequency="Month",
+        )
+        """
+        _response = self._raw_client.list_subscriptions(
+            plan_id=plan_id,
+            status=status,
+            amount=amount,
+            amount_range=amount_range,
+            start_date=start_date,
+            end_date=end_date,
+            size=size,
+            page=page,
+            sort=sort,
+            frequency=frequency,
+            request_options=request_options,
+        )
+        return _response.data
+
+    def create_subscription(
+        self,
+        *,
+        merchant_subscription_reference: str,
+        plan_id: str,
+        start_date: dt.datetime,
+        end_date: dt.datetime,
+        customer_id: str,
+        integration_mode: CreateSubscriptionRequestIntegrationMode,
+        enable_notification: typing.Optional[bool] = OMIT,
+        allowed_payment_methods: typing.Optional[
+            typing.Sequence[CreateSubscriptionRequestAllowedPaymentMethodsItem]
+        ] = OMIT,
+        merchant_metadata: typing.Optional[typing.Dict[str, str]] = OMIT,
+        is_tpv_enabled: typing.Optional[bool] = OMIT,
+        bank_account: typing.Optional[BankAccount] = OMIT,
+        callback_url: typing.Optional[str] = OMIT,
+        failure_callback_url: typing.Optional[str] = OMIT,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> CreateSubscriptionResponse:
+        """
+        Creates a new subscription against an existing plan. The subscription
+        defines the recurring billing cycle for a customer based on the
+        selected plan's pricing and frequency.
+
+        Parameters
+        ----------
+        merchant_subscription_reference : str
+            **Idempotency Key.** Unique identifier of the merchant subscription reference. Duplicate requests with the same `merchant_subscription_reference` will return the existing subscription instead of creating a new one.
+
+        plan_id : str
+            Unique identifier for the subscription plan.
+
+        start_date : dt.datetime
+            The ISO 8601 UTC Timestamp when the subscription starts.
+
+        end_date : dt.datetime
+            The ISO 8601 UTC Timestamp when the subscription expires.
+
+        customer_id : str
+            Unique identifier of the customer in the Pine Labs Online database.
+
+        integration_mode : CreateSubscriptionRequestIntegrationMode
+            Type of integration.
+
+        enable_notification : typing.Optional[bool]
+            Indicates if notifications are enabled.
+
+        allowed_payment_methods : typing.Optional[typing.Sequence[CreateSubscriptionRequestAllowedPaymentMethodsItem]]
+            The type of payment methods you want to offer customers.
+
+        merchant_metadata : typing.Optional[typing.Dict[str, str]]
+            Key-value pairs for additional information. Max 10 pairs, 256 chars each.
+
+        is_tpv_enabled : typing.Optional[bool]
+            Indicates if Third-Party Validation (TPV) is enabled.
+
+        bank_account : typing.Optional[BankAccount]
+
+        callback_url : typing.Optional[str]
+            URL to redirect customers to specific success or failure pages.
+
+        failure_callback_url : typing.Optional[str]
+            URL specifically used to redirect customers to a failure page.
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        CreateSubscriptionResponse
+            Subscription created successfully.
+
+        Examples
+        --------
+        import datetime
+
+        from pinelabs import PinelabsApi
+
+        client = PinelabsApi(
+            request_timestamp="YOUR_REQUEST_TIMESTAMP",
+            request_id="YOUR_REQUEST_ID",
+            token="YOUR_TOKEN",
+        )
+        client.subscriptions_subscriptions.create_subscription(
+            merchant_subscription_reference="f5d77ef9-fa11-4f58-a9f4-543e4a7022c5",
+            plan_id="v1-pla-250612061639-aa-666Zge",
+            start_date=datetime.datetime.fromisoformat(
+                "2025-06-12 06:22:21+00:00",
+            ),
+            end_date=datetime.datetime.fromisoformat(
+                "2025-06-21 17:32:28+00:00",
+            ),
+            customer_id="cust-v1-250519171901-aa-dPF6mg",
+            integration_mode="SEAMLESS",
+        )
+        """
+        _response = self._raw_client.create_subscription(
+            merchant_subscription_reference=merchant_subscription_reference,
+            plan_id=plan_id,
+            start_date=start_date,
+            end_date=end_date,
+            customer_id=customer_id,
+            integration_mode=integration_mode,
+            enable_notification=enable_notification,
+            allowed_payment_methods=allowed_payment_methods,
+            merchant_metadata=merchant_metadata,
+            is_tpv_enabled=is_tpv_enabled,
+            bank_account=bank_account,
+            callback_url=callback_url,
+            failure_callback_url=failure_callback_url,
+            request_options=request_options,
+        )
+        return _response.data
+
+    def get_subscription_by_id(
+        self, subscription_id: str, *, request_options: typing.Optional[RequestOptions] = None
+    ) -> SubscriptionDetail:
+        """
+        Retrieves a specific subscription by its subscription ID.
+
+        Parameters
+        ----------
+        subscription_id : str
+            Unique identifier for the subscription.
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        SubscriptionDetail
+            Subscription retrieved successfully.
+
+        Examples
+        --------
+        from pinelabs import PinelabsApi
+
+        client = PinelabsApi(
+            request_timestamp="YOUR_REQUEST_TIMESTAMP",
+            request_id="YOUR_REQUEST_ID",
+            token="YOUR_TOKEN",
+        )
+        client.subscriptions_subscriptions.get_subscription_by_id(
+            subscription_id="v1-sub-4405071524-aa-qlAtAf",
+        )
+        """
+        _response = self._raw_client.get_subscription_by_id(subscription_id, request_options=request_options)
+        return _response.data
+
+    def update_subscription(
+        self,
+        subscription_id: str,
+        *,
+        reason: str,
+        new_plan_id: typing.Optional[str] = OMIT,
+        new_end_date: typing.Optional[dt.datetime] = OMIT,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> SubscriptionDetail:
+        """
+        Updates an existing subscription. You can switch to a new plan
+        or update the end date. A reason is required.
+
+        Parameters
+        ----------
+        subscription_id : str
+            Unique identifier for the subscription.
+
+        reason : str
+            Reason for the update.
+
+        new_plan_id : typing.Optional[str]
+            New plan ID to switch the subscription to.
+
+        new_end_date : typing.Optional[dt.datetime]
+            New end date in ISO 8601 UTC.
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        SubscriptionDetail
+            Subscription updated successfully.
+
+        Examples
+        --------
+        from pinelabs import PinelabsApi
+
+        client = PinelabsApi(
+            request_timestamp="YOUR_REQUEST_TIMESTAMP",
+            request_id="YOUR_REQUEST_ID",
+            token="YOUR_TOKEN",
+        )
+        client.subscriptions_subscriptions.update_subscription(
+            subscription_id="v1-sub-4405071524-aa-qlAtAf",
+            reason="Switching to annual plan",
+        )
+        """
+        _response = self._raw_client.update_subscription(
+            subscription_id,
+            reason=reason,
+            new_plan_id=new_plan_id,
+            new_end_date=new_end_date,
+            request_options=request_options,
+        )
+        return _response.data
+
+    def get_subscription_by_merchant_reference(
+        self, merchant_subscription_reference: str, *, request_options: typing.Optional[RequestOptions] = None
+    ) -> SubscriptionDetail:
+        """
+        Retrieves a specific subscription by the merchant subscription reference.
+
+        Parameters
+        ----------
+        merchant_subscription_reference : str
+            Unique identifier of the merchant subscription reference.
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        SubscriptionDetail
+            Subscription retrieved successfully.
+
+        Examples
+        --------
+        from pinelabs import PinelabsApi
+
+        client = PinelabsApi(
+            request_timestamp="YOUR_REQUEST_TIMESTAMP",
+            request_id="YOUR_REQUEST_ID",
+            token="YOUR_TOKEN",
+        )
+        client.subscriptions_subscriptions.get_subscription_by_merchant_reference(
+            merchant_subscription_reference="1234567890",
+        )
+        """
+        _response = self._raw_client.get_subscription_by_merchant_reference(
+            merchant_subscription_reference, request_options=request_options
+        )
+        return _response.data
+
+    def cancel_subscription(
+        self, subscription_id: str, *, request_options: typing.Optional[RequestOptions] = None
+    ) -> SubscriptionDetail:
+        """
+        Cancels an active subscription. Once cancelled, the subscription
+        can no longer process recurring payments.
+
+        Parameters
+        ----------
+        subscription_id : str
+            Unique identifier for the subscription.
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        SubscriptionDetail
+            Subscription cancelled successfully.
+
+        Examples
+        --------
+        from pinelabs import PinelabsApi
+
+        client = PinelabsApi(
+            request_timestamp="YOUR_REQUEST_TIMESTAMP",
+            request_id="YOUR_REQUEST_ID",
+            token="YOUR_TOKEN",
+        )
+        client.subscriptions_subscriptions.cancel_subscription(
+            subscription_id="v1-sub-4405071524-aa-qlAtAf",
+        )
+        """
+        _response = self._raw_client.cancel_subscription(subscription_id, request_options=request_options)
+        return _response.data
+
+    def pause_subscription(
+        self, subscription_id: str, *, request_options: typing.Optional[RequestOptions] = None
+    ) -> SubscriptionDetail:
+        """
+        Pauses an active subscription. The subscription must be in an
+        active, inactive, trial, or resumed state to be paused.
+
+        Parameters
+        ----------
+        subscription_id : str
+            Unique identifier for the subscription.
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        SubscriptionDetail
+            Subscription paused successfully.
+
+        Examples
+        --------
+        from pinelabs import PinelabsApi
+
+        client = PinelabsApi(
+            request_timestamp="YOUR_REQUEST_TIMESTAMP",
+            request_id="YOUR_REQUEST_ID",
+            token="YOUR_TOKEN",
+        )
+        client.subscriptions_subscriptions.pause_subscription(
+            subscription_id="v1-sub-4405071524-aa-qlAtAf",
+        )
+        """
+        _response = self._raw_client.pause_subscription(subscription_id, request_options=request_options)
+        return _response.data
+
+    def resume_subscription(
+        self, subscription_id: str, *, request_options: typing.Optional[RequestOptions] = None
+    ) -> SubscriptionDetail:
+        """
+        Resumes a paused or halted subscription.
+
+        Parameters
+        ----------
+        subscription_id : str
+            Unique identifier for the subscription.
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        SubscriptionDetail
+            Subscription resumed successfully.
+
+        Examples
+        --------
+        from pinelabs import PinelabsApi
+
+        client = PinelabsApi(
+            request_timestamp="YOUR_REQUEST_TIMESTAMP",
+            request_id="YOUR_REQUEST_ID",
+            token="YOUR_TOKEN",
+        )
+        client.subscriptions_subscriptions.resume_subscription(
+            subscription_id="v1-sub-4405071524-aa-qlAtAf",
+        )
+        """
+        _response = self._raw_client.resume_subscription(subscription_id, request_options=request_options)
+        return _response.data
+
+
+class AsyncSubscriptionsSubscriptionsClient:
+    def __init__(self, *, client_wrapper: AsyncClientWrapper):
+        self._raw_client = AsyncRawSubscriptionsSubscriptionsClient(client_wrapper=client_wrapper)
+
+    @property
+    def with_raw_response(self) -> AsyncRawSubscriptionsSubscriptionsClient:
+        """
+        Retrieves a raw implementation of this client that returns raw responses.
+
+        Returns
+        -------
+        AsyncRawSubscriptionsSubscriptionsClient
+        """
+        return self._raw_client
+
+    async def list_subscriptions(
+        self,
+        *,
+        plan_id: typing.Optional[str] = None,
+        status: typing.Optional[str] = None,
+        amount: typing.Optional[int] = None,
+        amount_range: typing.Optional[ListSubscriptionsRequestAmountRange] = None,
+        start_date: typing.Optional[dt.datetime] = None,
+        end_date: typing.Optional[dt.datetime] = None,
+        size: typing.Optional[int] = None,
+        page: typing.Optional[int] = None,
+        sort: typing.Optional[str] = None,
+        frequency: typing.Optional[str] = None,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> ListSubscriptionsResponse:
+        """
+        Retrieves all subscriptions. Supports filtering by plan_id, status,
+        amount, date range, frequency, and pagination.
+
+        Parameters
+        ----------
+        plan_id : typing.Optional[str]
+            Filter by plan ID.
+
+        status : typing.Optional[str]
+            Filter by subscription status.
+
+        amount : typing.Optional[int]
+            Filter by amount value.
+
+        amount_range : typing.Optional[ListSubscriptionsRequestAmountRange]
+            Amount comparison operator.
+
+        start_date : typing.Optional[dt.datetime]
+            Filter subscriptions with start date after this value.
+
+        end_date : typing.Optional[dt.datetime]
+            Filter subscriptions with end date before this value.
+
+        size : typing.Optional[int]
+            Number of items per page.
+
+        page : typing.Optional[int]
+            Page number.
+
+        sort : typing.Optional[str]
+            Sort field and direction.
+
+        frequency : typing.Optional[str]
+            Filter by billing frequency.
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        ListSubscriptionsResponse
+            Subscriptions retrieved successfully.
+
+        Examples
+        --------
+        import asyncio
+        import datetime
+
+        from pinelabs import AsyncPinelabsApi
+
+        client = AsyncPinelabsApi(
+            request_timestamp="YOUR_REQUEST_TIMESTAMP",
+            request_id="YOUR_REQUEST_ID",
+            token="YOUR_TOKEN",
+        )
+
+
+        async def main() -> None:
+            await client.subscriptions_subscriptions.list_subscriptions(
+                plan_id="v1-plan-4405071524-aa-qlAtAf",
+                status="ACTIVE",
+                start_date=datetime.datetime.fromisoformat(
+                    "2022-02-01 17:32:28+00:00",
+                ),
+                end_date=datetime.datetime.fromisoformat(
+                    "2025-12-31 23:59:59+00:00",
+                ),
+                sort="id,asc",
+                frequency="Month",
+            )
+
+
+        asyncio.run(main())
+        """
+        _response = await self._raw_client.list_subscriptions(
+            plan_id=plan_id,
+            status=status,
+            amount=amount,
+            amount_range=amount_range,
+            start_date=start_date,
+            end_date=end_date,
+            size=size,
+            page=page,
+            sort=sort,
+            frequency=frequency,
+            request_options=request_options,
+        )
+        return _response.data
+
+    async def create_subscription(
+        self,
+        *,
+        merchant_subscription_reference: str,
+        plan_id: str,
+        start_date: dt.datetime,
+        end_date: dt.datetime,
+        customer_id: str,
+        integration_mode: CreateSubscriptionRequestIntegrationMode,
+        enable_notification: typing.Optional[bool] = OMIT,
+        allowed_payment_methods: typing.Optional[
+            typing.Sequence[CreateSubscriptionRequestAllowedPaymentMethodsItem]
+        ] = OMIT,
+        merchant_metadata: typing.Optional[typing.Dict[str, str]] = OMIT,
+        is_tpv_enabled: typing.Optional[bool] = OMIT,
+        bank_account: typing.Optional[BankAccount] = OMIT,
+        callback_url: typing.Optional[str] = OMIT,
+        failure_callback_url: typing.Optional[str] = OMIT,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> CreateSubscriptionResponse:
+        """
+        Creates a new subscription against an existing plan. The subscription
+        defines the recurring billing cycle for a customer based on the
+        selected plan's pricing and frequency.
+
+        Parameters
+        ----------
+        merchant_subscription_reference : str
+            **Idempotency Key.** Unique identifier of the merchant subscription reference. Duplicate requests with the same `merchant_subscription_reference` will return the existing subscription instead of creating a new one.
+
+        plan_id : str
+            Unique identifier for the subscription plan.
+
+        start_date : dt.datetime
+            The ISO 8601 UTC Timestamp when the subscription starts.
+
+        end_date : dt.datetime
+            The ISO 8601 UTC Timestamp when the subscription expires.
+
+        customer_id : str
+            Unique identifier of the customer in the Pine Labs Online database.
+
+        integration_mode : CreateSubscriptionRequestIntegrationMode
+            Type of integration.
+
+        enable_notification : typing.Optional[bool]
+            Indicates if notifications are enabled.
+
+        allowed_payment_methods : typing.Optional[typing.Sequence[CreateSubscriptionRequestAllowedPaymentMethodsItem]]
+            The type of payment methods you want to offer customers.
+
+        merchant_metadata : typing.Optional[typing.Dict[str, str]]
+            Key-value pairs for additional information. Max 10 pairs, 256 chars each.
+
+        is_tpv_enabled : typing.Optional[bool]
+            Indicates if Third-Party Validation (TPV) is enabled.
+
+        bank_account : typing.Optional[BankAccount]
+
+        callback_url : typing.Optional[str]
+            URL to redirect customers to specific success or failure pages.
+
+        failure_callback_url : typing.Optional[str]
+            URL specifically used to redirect customers to a failure page.
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        CreateSubscriptionResponse
+            Subscription created successfully.
+
+        Examples
+        --------
+        import asyncio
+        import datetime
+
+        from pinelabs import AsyncPinelabsApi
+
+        client = AsyncPinelabsApi(
+            request_timestamp="YOUR_REQUEST_TIMESTAMP",
+            request_id="YOUR_REQUEST_ID",
+            token="YOUR_TOKEN",
+        )
+
+
+        async def main() -> None:
+            await client.subscriptions_subscriptions.create_subscription(
+                merchant_subscription_reference="f5d77ef9-fa11-4f58-a9f4-543e4a7022c5",
+                plan_id="v1-pla-250612061639-aa-666Zge",
+                start_date=datetime.datetime.fromisoformat(
+                    "2025-06-12 06:22:21+00:00",
+                ),
+                end_date=datetime.datetime.fromisoformat(
+                    "2025-06-21 17:32:28+00:00",
+                ),
+                customer_id="cust-v1-250519171901-aa-dPF6mg",
+                integration_mode="SEAMLESS",
+            )
+
+
+        asyncio.run(main())
+        """
+        _response = await self._raw_client.create_subscription(
+            merchant_subscription_reference=merchant_subscription_reference,
+            plan_id=plan_id,
+            start_date=start_date,
+            end_date=end_date,
+            customer_id=customer_id,
+            integration_mode=integration_mode,
+            enable_notification=enable_notification,
+            allowed_payment_methods=allowed_payment_methods,
+            merchant_metadata=merchant_metadata,
+            is_tpv_enabled=is_tpv_enabled,
+            bank_account=bank_account,
+            callback_url=callback_url,
+            failure_callback_url=failure_callback_url,
+            request_options=request_options,
+        )
+        return _response.data
+
+    async def get_subscription_by_id(
+        self, subscription_id: str, *, request_options: typing.Optional[RequestOptions] = None
+    ) -> SubscriptionDetail:
+        """
+        Retrieves a specific subscription by its subscription ID.
+
+        Parameters
+        ----------
+        subscription_id : str
+            Unique identifier for the subscription.
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        SubscriptionDetail
+            Subscription retrieved successfully.
+
+        Examples
+        --------
+        import asyncio
+
+        from pinelabs import AsyncPinelabsApi
+
+        client = AsyncPinelabsApi(
+            request_timestamp="YOUR_REQUEST_TIMESTAMP",
+            request_id="YOUR_REQUEST_ID",
+            token="YOUR_TOKEN",
+        )
+
+
+        async def main() -> None:
+            await client.subscriptions_subscriptions.get_subscription_by_id(
+                subscription_id="v1-sub-4405071524-aa-qlAtAf",
+            )
+
+
+        asyncio.run(main())
+        """
+        _response = await self._raw_client.get_subscription_by_id(subscription_id, request_options=request_options)
+        return _response.data
+
+    async def update_subscription(
+        self,
+        subscription_id: str,
+        *,
+        reason: str,
+        new_plan_id: typing.Optional[str] = OMIT,
+        new_end_date: typing.Optional[dt.datetime] = OMIT,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> SubscriptionDetail:
+        """
+        Updates an existing subscription. You can switch to a new plan
+        or update the end date. A reason is required.
+
+        Parameters
+        ----------
+        subscription_id : str
+            Unique identifier for the subscription.
+
+        reason : str
+            Reason for the update.
+
+        new_plan_id : typing.Optional[str]
+            New plan ID to switch the subscription to.
+
+        new_end_date : typing.Optional[dt.datetime]
+            New end date in ISO 8601 UTC.
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        SubscriptionDetail
+            Subscription updated successfully.
+
+        Examples
+        --------
+        import asyncio
+
+        from pinelabs import AsyncPinelabsApi
+
+        client = AsyncPinelabsApi(
+            request_timestamp="YOUR_REQUEST_TIMESTAMP",
+            request_id="YOUR_REQUEST_ID",
+            token="YOUR_TOKEN",
+        )
+
+
+        async def main() -> None:
+            await client.subscriptions_subscriptions.update_subscription(
+                subscription_id="v1-sub-4405071524-aa-qlAtAf",
+                reason="Switching to annual plan",
+            )
+
+
+        asyncio.run(main())
+        """
+        _response = await self._raw_client.update_subscription(
+            subscription_id,
+            reason=reason,
+            new_plan_id=new_plan_id,
+            new_end_date=new_end_date,
+            request_options=request_options,
+        )
+        return _response.data
+
+    async def get_subscription_by_merchant_reference(
+        self, merchant_subscription_reference: str, *, request_options: typing.Optional[RequestOptions] = None
+    ) -> SubscriptionDetail:
+        """
+        Retrieves a specific subscription by the merchant subscription reference.
+
+        Parameters
+        ----------
+        merchant_subscription_reference : str
+            Unique identifier of the merchant subscription reference.
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        SubscriptionDetail
+            Subscription retrieved successfully.
+
+        Examples
+        --------
+        import asyncio
+
+        from pinelabs import AsyncPinelabsApi
+
+        client = AsyncPinelabsApi(
+            request_timestamp="YOUR_REQUEST_TIMESTAMP",
+            request_id="YOUR_REQUEST_ID",
+            token="YOUR_TOKEN",
+        )
+
+
+        async def main() -> None:
+            await client.subscriptions_subscriptions.get_subscription_by_merchant_reference(
+                merchant_subscription_reference="1234567890",
+            )
+
+
+        asyncio.run(main())
+        """
+        _response = await self._raw_client.get_subscription_by_merchant_reference(
+            merchant_subscription_reference, request_options=request_options
+        )
+        return _response.data
+
+    async def cancel_subscription(
+        self, subscription_id: str, *, request_options: typing.Optional[RequestOptions] = None
+    ) -> SubscriptionDetail:
+        """
+        Cancels an active subscription. Once cancelled, the subscription
+        can no longer process recurring payments.
+
+        Parameters
+        ----------
+        subscription_id : str
+            Unique identifier for the subscription.
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        SubscriptionDetail
+            Subscription cancelled successfully.
+
+        Examples
+        --------
+        import asyncio
+
+        from pinelabs import AsyncPinelabsApi
+
+        client = AsyncPinelabsApi(
+            request_timestamp="YOUR_REQUEST_TIMESTAMP",
+            request_id="YOUR_REQUEST_ID",
+            token="YOUR_TOKEN",
+        )
+
+
+        async def main() -> None:
+            await client.subscriptions_subscriptions.cancel_subscription(
+                subscription_id="v1-sub-4405071524-aa-qlAtAf",
+            )
+
+
+        asyncio.run(main())
+        """
+        _response = await self._raw_client.cancel_subscription(subscription_id, request_options=request_options)
+        return _response.data
+
+    async def pause_subscription(
+        self, subscription_id: str, *, request_options: typing.Optional[RequestOptions] = None
+    ) -> SubscriptionDetail:
+        """
+        Pauses an active subscription. The subscription must be in an
+        active, inactive, trial, or resumed state to be paused.
+
+        Parameters
+        ----------
+        subscription_id : str
+            Unique identifier for the subscription.
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        SubscriptionDetail
+            Subscription paused successfully.
+
+        Examples
+        --------
+        import asyncio
+
+        from pinelabs import AsyncPinelabsApi
+
+        client = AsyncPinelabsApi(
+            request_timestamp="YOUR_REQUEST_TIMESTAMP",
+            request_id="YOUR_REQUEST_ID",
+            token="YOUR_TOKEN",
+        )
+
+
+        async def main() -> None:
+            await client.subscriptions_subscriptions.pause_subscription(
+                subscription_id="v1-sub-4405071524-aa-qlAtAf",
+            )
+
+
+        asyncio.run(main())
+        """
+        _response = await self._raw_client.pause_subscription(subscription_id, request_options=request_options)
+        return _response.data
+
+    async def resume_subscription(
+        self, subscription_id: str, *, request_options: typing.Optional[RequestOptions] = None
+    ) -> SubscriptionDetail:
+        """
+        Resumes a paused or halted subscription.
+
+        Parameters
+        ----------
+        subscription_id : str
+            Unique identifier for the subscription.
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        SubscriptionDetail
+            Subscription resumed successfully.
+
+        Examples
+        --------
+        import asyncio
+
+        from pinelabs import AsyncPinelabsApi
+
+        client = AsyncPinelabsApi(
+            request_timestamp="YOUR_REQUEST_TIMESTAMP",
+            request_id="YOUR_REQUEST_ID",
+            token="YOUR_TOKEN",
+        )
+
+
+        async def main() -> None:
+            await client.subscriptions_subscriptions.resume_subscription(
+                subscription_id="v1-sub-4405071524-aa-qlAtAf",
+            )
+
+
+        asyncio.run(main())
+        """
+        _response = await self._raw_client.resume_subscription(subscription_id, request_options=request_options)
+        return _response.data