pinelabs-python 0.1.0__py3-none-any.whl

pinelabs/subscriptions_plans/client.py

@@ -0,0 +1,872 @@
+# 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.list_plans_response import ListPlansResponse
+from ..types.plan_response import PlanResponse
+from ..types.subscription_amount import SubscriptionAmount
+from .raw_client import AsyncRawSubscriptionsPlansClient, RawSubscriptionsPlansClient
+from .types.create_plan_request_frequency import CreatePlanRequestFrequency
+from .types.list_plans_request_amount_range import ListPlansRequestAmountRange
+
+# this is used as the default value for optional parameters
+OMIT = typing.cast(typing.Any, ...)
+
+
+class SubscriptionsPlansClient:
+    def __init__(self, *, client_wrapper: SyncClientWrapper):
+        self._raw_client = RawSubscriptionsPlansClient(client_wrapper=client_wrapper)
+
+    @property
+    def with_raw_response(self) -> RawSubscriptionsPlansClient:
+        """
+        Retrieves a raw implementation of this client that returns raw responses.
+
+        Returns
+        -------
+        RawSubscriptionsPlansClient
+        """
+        return self._raw_client
+
+    def list_plans(
+        self,
+        *,
+        plan_id: typing.Optional[str] = None,
+        start_date: typing.Optional[dt.datetime] = None,
+        end_date: typing.Optional[dt.datetime] = None,
+        amount: typing.Optional[int] = None,
+        amount_range: typing.Optional[ListPlansRequestAmountRange] = None,
+        frequency: typing.Optional[str] = None,
+        size: typing.Optional[int] = None,
+        page: typing.Optional[int] = None,
+        sort: typing.Optional[str] = None,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> ListPlansResponse:
+        """
+        Retrieves all subscription plans. Supports filtering by plan_id,
+        date range, amount, frequency, and pagination.
+
+        Parameters
+        ----------
+        plan_id : typing.Optional[str]
+            Filter by plan ID.
+
+        start_date : typing.Optional[dt.datetime]
+            Filter plans with start date after this value (ISO 8601 UTC).
+
+        end_date : typing.Optional[dt.datetime]
+            Filter plans with end date before this value (ISO 8601 UTC).
+
+        amount : typing.Optional[int]
+            Filter by amount value.
+
+        amount_range : typing.Optional[ListPlansRequestAmountRange]
+            Amount comparison operator.
+
+        frequency : typing.Optional[str]
+            Filter by billing frequency.
+
+        size : typing.Optional[int]
+            Number of items per page.
+
+        page : typing.Optional[int]
+            Page number.
+
+        sort : typing.Optional[str]
+            Sort field and direction.
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        ListPlansResponse
+            Plans 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_plans.list_plans(
+            plan_id="v1-plan-4405071524-aa-qlAtAf",
+            start_date=datetime.datetime.fromisoformat(
+                "2022-02-01 17:32:28+00:00",
+            ),
+            end_date=datetime.datetime.fromisoformat(
+                "2026-10-21 12:02:28+00:00",
+            ),
+            frequency="Month",
+            sort="id,asc",
+        )
+        """
+        _response = self._raw_client.list_plans(
+            plan_id=plan_id,
+            start_date=start_date,
+            end_date=end_date,
+            amount=amount,
+            amount_range=amount_range,
+            frequency=frequency,
+            size=size,
+            page=page,
+            sort=sort,
+            request_options=request_options,
+        )
+        return _response.data
+
+    def create_plan(
+        self,
+        *,
+        plan_name: str,
+        frequency: CreatePlanRequestFrequency,
+        amount: SubscriptionAmount,
+        max_limit_amount: SubscriptionAmount,
+        end_date: dt.datetime,
+        merchant_plan_reference: str,
+        plan_description: typing.Optional[str] = OMIT,
+        initial_debit_amount: typing.Optional[SubscriptionAmount] = OMIT,
+        trial_period_in_days: typing.Optional[int] = OMIT,
+        start_date: typing.Optional[dt.datetime] = OMIT,
+        merchant_metadata: typing.Optional[typing.Dict[str, str]] = OMIT,
+        auto_debit_ot: typing.Optional[str] = OMIT,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> PlanResponse:
+        """
+        Creates a new subscription plan that serves as a reusable template
+        defining the pricing structure, billing frequency, and payment terms.
+        Plans must be created before subscriptions can be set up.
+
+        Parameters
+        ----------
+        plan_name : str
+            Subscription plan name.
+
+        frequency : CreatePlanRequestFrequency
+            Frequency of recurring transactions for this particular plan.
+
+        amount : SubscriptionAmount
+
+        max_limit_amount : SubscriptionAmount
+
+        end_date : dt.datetime
+            The ISO 8601 UTC Timestamp when the subscription plan expires.
+
+        merchant_plan_reference : str
+            **Idempotency Key.** Unique identifier of the merchant plan reference. Duplicate requests with the same `merchant_plan_reference` will return the existing plan instead of creating a new one.
+
+        plan_description : typing.Optional[str]
+            Corresponding description for a plan.
+
+        initial_debit_amount : typing.Optional[SubscriptionAmount]
+
+        trial_period_in_days : typing.Optional[int]
+            Duration of the trial period in days.
+
+        start_date : typing.Optional[dt.datetime]
+            The ISO 8601 UTC Timestamp when the subscription plan is active and available for use.
+
+        merchant_metadata : typing.Optional[typing.Dict[str, str]]
+            Key-value pairs for additional information. Max 10 pairs, 256 chars each.
+
+        auto_debit_ot : typing.Optional[str]
+            Indicates whether auto-debit is enabled for one-time payments under the subscription plan.
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        PlanResponse
+            Plan created successfully.
+
+        Examples
+        --------
+        import datetime
+
+        from pinelabs import PinelabsApi, SubscriptionAmount
+
+        client = PinelabsApi(
+            request_timestamp="YOUR_REQUEST_TIMESTAMP",
+            request_id="YOUR_REQUEST_ID",
+            token="YOUR_TOKEN",
+        )
+        client.subscriptions_plans.create_plan(
+            plan_name="Monthly Plan 2025-06-12T06:16:37.364Z",
+            plan_description="Diwali dhammaka plan intended to attract customers on diwali time",
+            frequency="Month",
+            amount=SubscriptionAmount(
+                value=100,
+                currency="INR",
+            ),
+            max_limit_amount=SubscriptionAmount(
+                value=210,
+                currency="INR",
+            ),
+            initial_debit_amount=SubscriptionAmount(
+                value=110,
+                currency="INR",
+            ),
+            trial_period_in_days=0,
+            end_date=datetime.datetime.fromisoformat(
+                "2026-10-21 12:02:28+00:00",
+            ),
+            merchant_metadata={"key1": "DD"},
+            merchant_plan_reference="b41770ac-cd3a-48d3-9e93-7dc9246b4751",
+            auto_debit_ot="false",
+        )
+        """
+        _response = self._raw_client.create_plan(
+            plan_name=plan_name,
+            frequency=frequency,
+            amount=amount,
+            max_limit_amount=max_limit_amount,
+            end_date=end_date,
+            merchant_plan_reference=merchant_plan_reference,
+            plan_description=plan_description,
+            initial_debit_amount=initial_debit_amount,
+            trial_period_in_days=trial_period_in_days,
+            start_date=start_date,
+            merchant_metadata=merchant_metadata,
+            auto_debit_ot=auto_debit_ot,
+            request_options=request_options,
+        )
+        return _response.data
+
+    def get_plan_by_id(self, plan_id: str, *, request_options: typing.Optional[RequestOptions] = None) -> PlanResponse:
+        """
+        Retrieves a specific subscription plan by its plan ID.
+
+        Parameters
+        ----------
+        plan_id : str
+            Unique identifier for the subscription plan.
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        PlanResponse
+            Plan retrieved successfully.
+
+        Examples
+        --------
+        from pinelabs import PinelabsApi
+
+        client = PinelabsApi(
+            request_timestamp="YOUR_REQUEST_TIMESTAMP",
+            request_id="YOUR_REQUEST_ID",
+            token="YOUR_TOKEN",
+        )
+        client.subscriptions_plans.get_plan_by_id(
+            plan_id="v1-plan-4405071524-aa-qlAtAf",
+        )
+        """
+        _response = self._raw_client.get_plan_by_id(plan_id, request_options=request_options)
+        return _response.data
+
+    def delete_plan(self, plan_id: str, *, request_options: typing.Optional[RequestOptions] = None) -> None:
+        """
+        Deletes a subscription plan by its plan ID.
+
+        Parameters
+        ----------
+        plan_id : str
+            Unique identifier for the subscription plan.
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        None
+
+        Examples
+        --------
+        from pinelabs import PinelabsApi
+
+        client = PinelabsApi(
+            request_timestamp="YOUR_REQUEST_TIMESTAMP",
+            request_id="YOUR_REQUEST_ID",
+            token="YOUR_TOKEN",
+        )
+        client.subscriptions_plans.delete_plan(
+            plan_id="v1-plan-4405071524-aa-qlAtAf",
+        )
+        """
+        _response = self._raw_client.delete_plan(plan_id, request_options=request_options)
+        return _response.data
+
+    def update_plan(
+        self,
+        plan_id: str,
+        *,
+        plan_name: typing.Optional[str] = OMIT,
+        plan_description: typing.Optional[str] = OMIT,
+        amount: typing.Optional[SubscriptionAmount] = OMIT,
+        max_limit_amount: typing.Optional[SubscriptionAmount] = OMIT,
+        trial_period_in_days: typing.Optional[int] = OMIT,
+        end_date: typing.Optional[dt.datetime] = OMIT,
+        merchant_metadata: typing.Optional[typing.Dict[str, str]] = OMIT,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> PlanResponse:
+        """
+        Updates an existing subscription plan. Existing subscriptions under
+        this plan will remain unaffected. The changes will apply only to
+        new subscriptions created under this plan.
+
+        Parameters
+        ----------
+        plan_id : str
+            Unique identifier for the subscription plan.
+
+        plan_name : typing.Optional[str]
+            Subscription plan name.
+
+        plan_description : typing.Optional[str]
+            Corresponding description for a plan.
+
+        amount : typing.Optional[SubscriptionAmount]
+
+        max_limit_amount : typing.Optional[SubscriptionAmount]
+
+        trial_period_in_days : typing.Optional[int]
+            Duration of the trial period in days.
+
+        end_date : typing.Optional[dt.datetime]
+            The ISO 8601 UTC Timestamp when the subscription plan expires.
+
+        merchant_metadata : typing.Optional[typing.Dict[str, str]]
+            Key-value pairs for additional information. Max 10 pairs, 256 chars each.
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        PlanResponse
+            Plan updated successfully.
+
+        Examples
+        --------
+        from pinelabs import PinelabsApi
+
+        client = PinelabsApi(
+            request_timestamp="YOUR_REQUEST_TIMESTAMP",
+            request_id="YOUR_REQUEST_ID",
+            token="YOUR_TOKEN",
+        )
+        client.subscriptions_plans.update_plan(
+            plan_id="v1-plan-4405071524-aa-qlAtAf",
+        )
+        """
+        _response = self._raw_client.update_plan(
+            plan_id,
+            plan_name=plan_name,
+            plan_description=plan_description,
+            amount=amount,
+            max_limit_amount=max_limit_amount,
+            trial_period_in_days=trial_period_in_days,
+            end_date=end_date,
+            merchant_metadata=merchant_metadata,
+            request_options=request_options,
+        )
+        return _response.data
+
+    def get_plan_by_merchant_reference(
+        self, merchant_plan_reference: str, *, request_options: typing.Optional[RequestOptions] = None
+    ) -> PlanResponse:
+        """
+        Retrieves a specific subscription plan by the merchant plan reference.
+
+        Parameters
+        ----------
+        merchant_plan_reference : str
+            Unique identifier of the merchant plan reference.
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        PlanResponse
+            Plan retrieved successfully.
+
+        Examples
+        --------
+        from pinelabs import PinelabsApi
+
+        client = PinelabsApi(
+            request_timestamp="YOUR_REQUEST_TIMESTAMP",
+            request_id="YOUR_REQUEST_ID",
+            token="YOUR_TOKEN",
+        )
+        client.subscriptions_plans.get_plan_by_merchant_reference(
+            merchant_plan_reference="1234567890",
+        )
+        """
+        _response = self._raw_client.get_plan_by_merchant_reference(
+            merchant_plan_reference, request_options=request_options
+        )
+        return _response.data
+
+
+class AsyncSubscriptionsPlansClient:
+    def __init__(self, *, client_wrapper: AsyncClientWrapper):
+        self._raw_client = AsyncRawSubscriptionsPlansClient(client_wrapper=client_wrapper)
+
+    @property
+    def with_raw_response(self) -> AsyncRawSubscriptionsPlansClient:
+        """
+        Retrieves a raw implementation of this client that returns raw responses.
+
+        Returns
+        -------
+        AsyncRawSubscriptionsPlansClient
+        """
+        return self._raw_client
+
+    async def list_plans(
+        self,
+        *,
+        plan_id: typing.Optional[str] = None,
+        start_date: typing.Optional[dt.datetime] = None,
+        end_date: typing.Optional[dt.datetime] = None,
+        amount: typing.Optional[int] = None,
+        amount_range: typing.Optional[ListPlansRequestAmountRange] = None,
+        frequency: typing.Optional[str] = None,
+        size: typing.Optional[int] = None,
+        page: typing.Optional[int] = None,
+        sort: typing.Optional[str] = None,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> ListPlansResponse:
+        """
+        Retrieves all subscription plans. Supports filtering by plan_id,
+        date range, amount, frequency, and pagination.
+
+        Parameters
+        ----------
+        plan_id : typing.Optional[str]
+            Filter by plan ID.
+
+        start_date : typing.Optional[dt.datetime]
+            Filter plans with start date after this value (ISO 8601 UTC).
+
+        end_date : typing.Optional[dt.datetime]
+            Filter plans with end date before this value (ISO 8601 UTC).
+
+        amount : typing.Optional[int]
+            Filter by amount value.
+
+        amount_range : typing.Optional[ListPlansRequestAmountRange]
+            Amount comparison operator.
+
+        frequency : typing.Optional[str]
+            Filter by billing frequency.
+
+        size : typing.Optional[int]
+            Number of items per page.
+
+        page : typing.Optional[int]
+            Page number.
+
+        sort : typing.Optional[str]
+            Sort field and direction.
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        ListPlansResponse
+            Plans 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_plans.list_plans(
+                plan_id="v1-plan-4405071524-aa-qlAtAf",
+                start_date=datetime.datetime.fromisoformat(
+                    "2022-02-01 17:32:28+00:00",
+                ),
+                end_date=datetime.datetime.fromisoformat(
+                    "2026-10-21 12:02:28+00:00",
+                ),
+                frequency="Month",
+                sort="id,asc",
+            )
+
+
+        asyncio.run(main())
+        """
+        _response = await self._raw_client.list_plans(
+            plan_id=plan_id,
+            start_date=start_date,
+            end_date=end_date,
+            amount=amount,
+            amount_range=amount_range,
+            frequency=frequency,
+            size=size,
+            page=page,
+            sort=sort,
+            request_options=request_options,
+        )
+        return _response.data
+
+    async def create_plan(
+        self,
+        *,
+        plan_name: str,
+        frequency: CreatePlanRequestFrequency,
+        amount: SubscriptionAmount,
+        max_limit_amount: SubscriptionAmount,
+        end_date: dt.datetime,
+        merchant_plan_reference: str,
+        plan_description: typing.Optional[str] = OMIT,
+        initial_debit_amount: typing.Optional[SubscriptionAmount] = OMIT,
+        trial_period_in_days: typing.Optional[int] = OMIT,
+        start_date: typing.Optional[dt.datetime] = OMIT,
+        merchant_metadata: typing.Optional[typing.Dict[str, str]] = OMIT,
+        auto_debit_ot: typing.Optional[str] = OMIT,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> PlanResponse:
+        """
+        Creates a new subscription plan that serves as a reusable template
+        defining the pricing structure, billing frequency, and payment terms.
+        Plans must be created before subscriptions can be set up.
+
+        Parameters
+        ----------
+        plan_name : str
+            Subscription plan name.
+
+        frequency : CreatePlanRequestFrequency
+            Frequency of recurring transactions for this particular plan.
+
+        amount : SubscriptionAmount
+
+        max_limit_amount : SubscriptionAmount
+
+        end_date : dt.datetime
+            The ISO 8601 UTC Timestamp when the subscription plan expires.
+
+        merchant_plan_reference : str
+            **Idempotency Key.** Unique identifier of the merchant plan reference. Duplicate requests with the same `merchant_plan_reference` will return the existing plan instead of creating a new one.
+
+        plan_description : typing.Optional[str]
+            Corresponding description for a plan.
+
+        initial_debit_amount : typing.Optional[SubscriptionAmount]
+
+        trial_period_in_days : typing.Optional[int]
+            Duration of the trial period in days.
+
+        start_date : typing.Optional[dt.datetime]
+            The ISO 8601 UTC Timestamp when the subscription plan is active and available for use.
+
+        merchant_metadata : typing.Optional[typing.Dict[str, str]]
+            Key-value pairs for additional information. Max 10 pairs, 256 chars each.
+
+        auto_debit_ot : typing.Optional[str]
+            Indicates whether auto-debit is enabled for one-time payments under the subscription plan.
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        PlanResponse
+            Plan created successfully.
+
+        Examples
+        --------
+        import asyncio
+        import datetime
+
+        from pinelabs import AsyncPinelabsApi, SubscriptionAmount
+
+        client = AsyncPinelabsApi(
+            request_timestamp="YOUR_REQUEST_TIMESTAMP",
+            request_id="YOUR_REQUEST_ID",
+            token="YOUR_TOKEN",
+        )
+
+
+        async def main() -> None:
+            await client.subscriptions_plans.create_plan(
+                plan_name="Monthly Plan 2025-06-12T06:16:37.364Z",
+                plan_description="Diwali dhammaka plan intended to attract customers on diwali time",
+                frequency="Month",
+                amount=SubscriptionAmount(
+                    value=100,
+                    currency="INR",
+                ),
+                max_limit_amount=SubscriptionAmount(
+                    value=210,
+                    currency="INR",
+                ),
+                initial_debit_amount=SubscriptionAmount(
+                    value=110,
+                    currency="INR",
+                ),
+                trial_period_in_days=0,
+                end_date=datetime.datetime.fromisoformat(
+                    "2026-10-21 12:02:28+00:00",
+                ),
+                merchant_metadata={"key1": "DD"},
+                merchant_plan_reference="b41770ac-cd3a-48d3-9e93-7dc9246b4751",
+                auto_debit_ot="false",
+            )
+
+
+        asyncio.run(main())
+        """
+        _response = await self._raw_client.create_plan(
+            plan_name=plan_name,
+            frequency=frequency,
+            amount=amount,
+            max_limit_amount=max_limit_amount,
+            end_date=end_date,
+            merchant_plan_reference=merchant_plan_reference,
+            plan_description=plan_description,
+            initial_debit_amount=initial_debit_amount,
+            trial_period_in_days=trial_period_in_days,
+            start_date=start_date,
+            merchant_metadata=merchant_metadata,
+            auto_debit_ot=auto_debit_ot,
+            request_options=request_options,
+        )
+        return _response.data
+
+    async def get_plan_by_id(
+        self, plan_id: str, *, request_options: typing.Optional[RequestOptions] = None
+    ) -> PlanResponse:
+        """
+        Retrieves a specific subscription plan by its plan ID.
+
+        Parameters
+        ----------
+        plan_id : str
+            Unique identifier for the subscription plan.
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        PlanResponse
+            Plan 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_plans.get_plan_by_id(
+                plan_id="v1-plan-4405071524-aa-qlAtAf",
+            )
+
+
+        asyncio.run(main())
+        """
+        _response = await self._raw_client.get_plan_by_id(plan_id, request_options=request_options)
+        return _response.data
+
+    async def delete_plan(self, plan_id: str, *, request_options: typing.Optional[RequestOptions] = None) -> None:
+        """
+        Deletes a subscription plan by its plan ID.
+
+        Parameters
+        ----------
+        plan_id : str
+            Unique identifier for the subscription plan.
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        None
+
+        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_plans.delete_plan(
+                plan_id="v1-plan-4405071524-aa-qlAtAf",
+            )
+
+
+        asyncio.run(main())
+        """
+        _response = await self._raw_client.delete_plan(plan_id, request_options=request_options)
+        return _response.data
+
+    async def update_plan(
+        self,
+        plan_id: str,
+        *,
+        plan_name: typing.Optional[str] = OMIT,
+        plan_description: typing.Optional[str] = OMIT,
+        amount: typing.Optional[SubscriptionAmount] = OMIT,
+        max_limit_amount: typing.Optional[SubscriptionAmount] = OMIT,
+        trial_period_in_days: typing.Optional[int] = OMIT,
+        end_date: typing.Optional[dt.datetime] = OMIT,
+        merchant_metadata: typing.Optional[typing.Dict[str, str]] = OMIT,
+        request_options: typing.Optional[RequestOptions] = None,
+    ) -> PlanResponse:
+        """
+        Updates an existing subscription plan. Existing subscriptions under
+        this plan will remain unaffected. The changes will apply only to
+        new subscriptions created under this plan.
+
+        Parameters
+        ----------
+        plan_id : str
+            Unique identifier for the subscription plan.
+
+        plan_name : typing.Optional[str]
+            Subscription plan name.
+
+        plan_description : typing.Optional[str]
+            Corresponding description for a plan.
+
+        amount : typing.Optional[SubscriptionAmount]
+
+        max_limit_amount : typing.Optional[SubscriptionAmount]
+
+        trial_period_in_days : typing.Optional[int]
+            Duration of the trial period in days.
+
+        end_date : typing.Optional[dt.datetime]
+            The ISO 8601 UTC Timestamp when the subscription plan expires.
+
+        merchant_metadata : typing.Optional[typing.Dict[str, str]]
+            Key-value pairs for additional information. Max 10 pairs, 256 chars each.
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        PlanResponse
+            Plan 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_plans.update_plan(
+                plan_id="v1-plan-4405071524-aa-qlAtAf",
+            )
+
+
+        asyncio.run(main())
+        """
+        _response = await self._raw_client.update_plan(
+            plan_id,
+            plan_name=plan_name,
+            plan_description=plan_description,
+            amount=amount,
+            max_limit_amount=max_limit_amount,
+            trial_period_in_days=trial_period_in_days,
+            end_date=end_date,
+            merchant_metadata=merchant_metadata,
+            request_options=request_options,
+        )
+        return _response.data
+
+    async def get_plan_by_merchant_reference(
+        self, merchant_plan_reference: str, *, request_options: typing.Optional[RequestOptions] = None
+    ) -> PlanResponse:
+        """
+        Retrieves a specific subscription plan by the merchant plan reference.
+
+        Parameters
+        ----------
+        merchant_plan_reference : str
+            Unique identifier of the merchant plan reference.
+
+        request_options : typing.Optional[RequestOptions]
+            Request-specific configuration.
+
+        Returns
+        -------
+        PlanResponse
+            Plan 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_plans.get_plan_by_merchant_reference(
+                merchant_plan_reference="1234567890",
+            )
+
+
+        asyncio.run(main())
+        """
+        _response = await self._raw_client.get_plan_by_merchant_reference(
+            merchant_plan_reference, request_options=request_options
+        )
+        return _response.data