pinelabs-python 0.1.0__py3-none-any.whl

pinelabs/subscriptions_subscriptions/raw_client.py

@@ -0,0 +1,1281 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import datetime as dt
+import typing
+from json.decoder import JSONDecodeError
+
+from ..core.api_error import ApiError
+from ..core.client_wrapper import AsyncClientWrapper, SyncClientWrapper
+from ..core.datetime_utils import serialize_datetime
+from ..core.http_response import AsyncHttpResponse, HttpResponse
+from ..core.jsonable_encoder import encode_path_param
+from ..core.parse_error import ParsingError
+from ..core.pydantic_utilities import parse_obj_as
+from ..core.request_options import RequestOptions
+from ..core.serialization import convert_and_respect_annotation_metadata
+from ..errors.bad_request_error import BadRequestError
+from ..errors.internal_server_error import InternalServerError
+from ..errors.not_found_error import NotFoundError
+from ..errors.unprocessable_entity_error import UnprocessableEntityError
+from ..types.bank_account import BankAccount
+from ..types.create_subscription_response import CreateSubscriptionResponse
+from ..types.error_response import ErrorResponse
+from ..types.list_subscriptions_response import ListSubscriptionsResponse
+from ..types.subscription_detail import SubscriptionDetail
+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
+from pydantic import ValidationError
+
+# this is used as the default value for optional parameters
+OMIT = typing.cast(typing.Any, ...)
+
+
+class RawSubscriptionsSubscriptionsClient:
+    def __init__(self, *, client_wrapper: SyncClientWrapper):
+        self._client_wrapper = client_wrapper
+
+    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,
+    ) -> HttpResponse[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
+        -------
+        HttpResponse[ListSubscriptionsResponse]
+            Subscriptions retrieved successfully.
+        """
+        _response = self._client_wrapper.httpx_client.request(
+            "ps/api/v1/public/subscriptions",
+            method="GET",
+            params={
+                "plan_id": plan_id,
+                "status": status,
+                "amount": amount,
+                "amount_range": amount_range,
+                "start_date": serialize_datetime(start_date) if start_date is not None else None,
+                "end_date": serialize_datetime(end_date) if end_date is not None else None,
+                "size": size,
+                "page": page,
+                "sort": sort,
+                "frequency": frequency,
+            },
+            request_options=request_options,
+        )
+        try:
+            if 200 <= _response.status_code < 300:
+                _data = typing.cast(
+                    ListSubscriptionsResponse,
+                    parse_obj_as(
+                        type_=ListSubscriptionsResponse,  # type: ignore
+                        object_=_response.json(),
+                    ),
+                )
+                return HttpResponse(response=_response, data=_data)
+            if _response.status_code == 500:
+                raise InternalServerError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            _response_json = _response.json()
+        except JSONDecodeError:
+            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
+        except ValidationError as e:
+            raise ParsingError(
+                status_code=_response.status_code, headers=dict(_response.headers), body=_response.json(), cause=e
+            )
+        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
+
+    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,
+    ) -> HttpResponse[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
+        -------
+        HttpResponse[CreateSubscriptionResponse]
+            Subscription created successfully.
+        """
+        _response = self._client_wrapper.httpx_client.request(
+            "ps/api/v1/public/subscriptions",
+            method="POST",
+            json={
+                "merchant_subscription_reference": merchant_subscription_reference,
+                "plan_id": plan_id,
+                "enable_notification": enable_notification,
+                "start_date": start_date,
+                "end_date": end_date,
+                "customer_id": customer_id,
+                "allowed_payment_methods": allowed_payment_methods,
+                "integration_mode": integration_mode,
+                "merchant_metadata": merchant_metadata,
+                "is_tpv_enabled": is_tpv_enabled,
+                "bank_account": convert_and_respect_annotation_metadata(
+                    object_=bank_account, annotation=BankAccount, direction="write"
+                ),
+                "callback_url": callback_url,
+                "failure_callback_url": failure_callback_url,
+            },
+            headers={
+                "content-type": "application/json",
+            },
+            request_options=request_options,
+            omit=OMIT,
+        )
+        try:
+            if 200 <= _response.status_code < 300:
+                _data = typing.cast(
+                    CreateSubscriptionResponse,
+                    parse_obj_as(
+                        type_=CreateSubscriptionResponse,  # type: ignore
+                        object_=_response.json(),
+                    ),
+                )
+                return HttpResponse(response=_response, data=_data)
+            if _response.status_code == 404:
+                raise NotFoundError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 422:
+                raise UnprocessableEntityError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        typing.Any,
+                        parse_obj_as(
+                            type_=typing.Any,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 500:
+                raise InternalServerError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            _response_json = _response.json()
+        except JSONDecodeError:
+            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
+        except ValidationError as e:
+            raise ParsingError(
+                status_code=_response.status_code, headers=dict(_response.headers), body=_response.json(), cause=e
+            )
+        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
+
+    def get_subscription_by_id(
+        self, subscription_id: str, *, request_options: typing.Optional[RequestOptions] = None
+    ) -> HttpResponse[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
+        -------
+        HttpResponse[SubscriptionDetail]
+            Subscription retrieved successfully.
+        """
+        _response = self._client_wrapper.httpx_client.request(
+            f"ps/api/v1/public/subscriptions/{encode_path_param(subscription_id)}",
+            method="GET",
+            request_options=request_options,
+        )
+        try:
+            if 200 <= _response.status_code < 300:
+                _data = typing.cast(
+                    SubscriptionDetail,
+                    parse_obj_as(
+                        type_=SubscriptionDetail,  # type: ignore
+                        object_=_response.json(),
+                    ),
+                )
+                return HttpResponse(response=_response, data=_data)
+            if _response.status_code == 500:
+                raise InternalServerError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            _response_json = _response.json()
+        except JSONDecodeError:
+            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
+        except ValidationError as e:
+            raise ParsingError(
+                status_code=_response.status_code, headers=dict(_response.headers), body=_response.json(), cause=e
+            )
+        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
+
+    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,
+    ) -> HttpResponse[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
+        -------
+        HttpResponse[SubscriptionDetail]
+            Subscription updated successfully.
+        """
+        _response = self._client_wrapper.httpx_client.request(
+            f"ps/api/v1/public/subscriptions/{encode_path_param(subscription_id)}",
+            method="PATCH",
+            json={
+                "new_plan_id": new_plan_id,
+                "new_end_date": new_end_date,
+                "reason": reason,
+            },
+            headers={
+                "content-type": "application/json",
+            },
+            request_options=request_options,
+            omit=OMIT,
+        )
+        try:
+            if 200 <= _response.status_code < 300:
+                _data = typing.cast(
+                    SubscriptionDetail,
+                    parse_obj_as(
+                        type_=SubscriptionDetail,  # type: ignore
+                        object_=_response.json(),
+                    ),
+                )
+                return HttpResponse(response=_response, data=_data)
+            if _response.status_code == 404:
+                raise NotFoundError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 500:
+                raise InternalServerError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            _response_json = _response.json()
+        except JSONDecodeError:
+            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
+        except ValidationError as e:
+            raise ParsingError(
+                status_code=_response.status_code, headers=dict(_response.headers), body=_response.json(), cause=e
+            )
+        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
+
+    def get_subscription_by_merchant_reference(
+        self, merchant_subscription_reference: str, *, request_options: typing.Optional[RequestOptions] = None
+    ) -> HttpResponse[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
+        -------
+        HttpResponse[SubscriptionDetail]
+            Subscription retrieved successfully.
+        """
+        _response = self._client_wrapper.httpx_client.request(
+            f"ps/api/v1/public/subscriptions/reference/{encode_path_param(merchant_subscription_reference)}",
+            method="GET",
+            request_options=request_options,
+        )
+        try:
+            if 200 <= _response.status_code < 300:
+                _data = typing.cast(
+                    SubscriptionDetail,
+                    parse_obj_as(
+                        type_=SubscriptionDetail,  # type: ignore
+                        object_=_response.json(),
+                    ),
+                )
+                return HttpResponse(response=_response, data=_data)
+            if _response.status_code == 500:
+                raise InternalServerError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            _response_json = _response.json()
+        except JSONDecodeError:
+            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
+        except ValidationError as e:
+            raise ParsingError(
+                status_code=_response.status_code, headers=dict(_response.headers), body=_response.json(), cause=e
+            )
+        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
+
+    def cancel_subscription(
+        self, subscription_id: str, *, request_options: typing.Optional[RequestOptions] = None
+    ) -> HttpResponse[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
+        -------
+        HttpResponse[SubscriptionDetail]
+            Subscription cancelled successfully.
+        """
+        _response = self._client_wrapper.httpx_client.request(
+            f"ps/api/v1/public/subscriptions/{encode_path_param(subscription_id)}/cancel",
+            method="POST",
+            request_options=request_options,
+        )
+        try:
+            if 200 <= _response.status_code < 300:
+                _data = typing.cast(
+                    SubscriptionDetail,
+                    parse_obj_as(
+                        type_=SubscriptionDetail,  # type: ignore
+                        object_=_response.json(),
+                    ),
+                )
+                return HttpResponse(response=_response, data=_data)
+            if _response.status_code == 400:
+                raise BadRequestError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        typing.Any,
+                        parse_obj_as(
+                            type_=typing.Any,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            _response_json = _response.json()
+        except JSONDecodeError:
+            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
+        except ValidationError as e:
+            raise ParsingError(
+                status_code=_response.status_code, headers=dict(_response.headers), body=_response.json(), cause=e
+            )
+        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
+
+    def pause_subscription(
+        self, subscription_id: str, *, request_options: typing.Optional[RequestOptions] = None
+    ) -> HttpResponse[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
+        -------
+        HttpResponse[SubscriptionDetail]
+            Subscription paused successfully.
+        """
+        _response = self._client_wrapper.httpx_client.request(
+            f"ps/api/v1/public/subscriptions/{encode_path_param(subscription_id)}/pause",
+            method="POST",
+            request_options=request_options,
+        )
+        try:
+            if 200 <= _response.status_code < 300:
+                _data = typing.cast(
+                    SubscriptionDetail,
+                    parse_obj_as(
+                        type_=SubscriptionDetail,  # type: ignore
+                        object_=_response.json(),
+                    ),
+                )
+                return HttpResponse(response=_response, data=_data)
+            if _response.status_code == 500:
+                raise InternalServerError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            _response_json = _response.json()
+        except JSONDecodeError:
+            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
+        except ValidationError as e:
+            raise ParsingError(
+                status_code=_response.status_code, headers=dict(_response.headers), body=_response.json(), cause=e
+            )
+        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
+
+    def resume_subscription(
+        self, subscription_id: str, *, request_options: typing.Optional[RequestOptions] = None
+    ) -> HttpResponse[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
+        -------
+        HttpResponse[SubscriptionDetail]
+            Subscription resumed successfully.
+        """
+        _response = self._client_wrapper.httpx_client.request(
+            f"ps/api/v1/public/subscriptions/{encode_path_param(subscription_id)}/resume",
+            method="POST",
+            request_options=request_options,
+        )
+        try:
+            if 200 <= _response.status_code < 300:
+                _data = typing.cast(
+                    SubscriptionDetail,
+                    parse_obj_as(
+                        type_=SubscriptionDetail,  # type: ignore
+                        object_=_response.json(),
+                    ),
+                )
+                return HttpResponse(response=_response, data=_data)
+            if _response.status_code == 500:
+                raise InternalServerError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            _response_json = _response.json()
+        except JSONDecodeError:
+            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
+        except ValidationError as e:
+            raise ParsingError(
+                status_code=_response.status_code, headers=dict(_response.headers), body=_response.json(), cause=e
+            )
+        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
+
+
+class AsyncRawSubscriptionsSubscriptionsClient:
+    def __init__(self, *, client_wrapper: AsyncClientWrapper):
+        self._client_wrapper = client_wrapper
+
+    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,
+    ) -> AsyncHttpResponse[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
+        -------
+        AsyncHttpResponse[ListSubscriptionsResponse]
+            Subscriptions retrieved successfully.
+        """
+        _response = await self._client_wrapper.httpx_client.request(
+            "ps/api/v1/public/subscriptions",
+            method="GET",
+            params={
+                "plan_id": plan_id,
+                "status": status,
+                "amount": amount,
+                "amount_range": amount_range,
+                "start_date": serialize_datetime(start_date) if start_date is not None else None,
+                "end_date": serialize_datetime(end_date) if end_date is not None else None,
+                "size": size,
+                "page": page,
+                "sort": sort,
+                "frequency": frequency,
+            },
+            request_options=request_options,
+        )
+        try:
+            if 200 <= _response.status_code < 300:
+                _data = typing.cast(
+                    ListSubscriptionsResponse,
+                    parse_obj_as(
+                        type_=ListSubscriptionsResponse,  # type: ignore
+                        object_=_response.json(),
+                    ),
+                )
+                return AsyncHttpResponse(response=_response, data=_data)
+            if _response.status_code == 500:
+                raise InternalServerError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            _response_json = _response.json()
+        except JSONDecodeError:
+            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
+        except ValidationError as e:
+            raise ParsingError(
+                status_code=_response.status_code, headers=dict(_response.headers), body=_response.json(), cause=e
+            )
+        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
+
+    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,
+    ) -> AsyncHttpResponse[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
+        -------
+        AsyncHttpResponse[CreateSubscriptionResponse]
+            Subscription created successfully.
+        """
+        _response = await self._client_wrapper.httpx_client.request(
+            "ps/api/v1/public/subscriptions",
+            method="POST",
+            json={
+                "merchant_subscription_reference": merchant_subscription_reference,
+                "plan_id": plan_id,
+                "enable_notification": enable_notification,
+                "start_date": start_date,
+                "end_date": end_date,
+                "customer_id": customer_id,
+                "allowed_payment_methods": allowed_payment_methods,
+                "integration_mode": integration_mode,
+                "merchant_metadata": merchant_metadata,
+                "is_tpv_enabled": is_tpv_enabled,
+                "bank_account": convert_and_respect_annotation_metadata(
+                    object_=bank_account, annotation=BankAccount, direction="write"
+                ),
+                "callback_url": callback_url,
+                "failure_callback_url": failure_callback_url,
+            },
+            headers={
+                "content-type": "application/json",
+            },
+            request_options=request_options,
+            omit=OMIT,
+        )
+        try:
+            if 200 <= _response.status_code < 300:
+                _data = typing.cast(
+                    CreateSubscriptionResponse,
+                    parse_obj_as(
+                        type_=CreateSubscriptionResponse,  # type: ignore
+                        object_=_response.json(),
+                    ),
+                )
+                return AsyncHttpResponse(response=_response, data=_data)
+            if _response.status_code == 404:
+                raise NotFoundError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 422:
+                raise UnprocessableEntityError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        typing.Any,
+                        parse_obj_as(
+                            type_=typing.Any,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 500:
+                raise InternalServerError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            _response_json = _response.json()
+        except JSONDecodeError:
+            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
+        except ValidationError as e:
+            raise ParsingError(
+                status_code=_response.status_code, headers=dict(_response.headers), body=_response.json(), cause=e
+            )
+        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
+
+    async def get_subscription_by_id(
+        self, subscription_id: str, *, request_options: typing.Optional[RequestOptions] = None
+    ) -> AsyncHttpResponse[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
+        -------
+        AsyncHttpResponse[SubscriptionDetail]
+            Subscription retrieved successfully.
+        """
+        _response = await self._client_wrapper.httpx_client.request(
+            f"ps/api/v1/public/subscriptions/{encode_path_param(subscription_id)}",
+            method="GET",
+            request_options=request_options,
+        )
+        try:
+            if 200 <= _response.status_code < 300:
+                _data = typing.cast(
+                    SubscriptionDetail,
+                    parse_obj_as(
+                        type_=SubscriptionDetail,  # type: ignore
+                        object_=_response.json(),
+                    ),
+                )
+                return AsyncHttpResponse(response=_response, data=_data)
+            if _response.status_code == 500:
+                raise InternalServerError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            _response_json = _response.json()
+        except JSONDecodeError:
+            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
+        except ValidationError as e:
+            raise ParsingError(
+                status_code=_response.status_code, headers=dict(_response.headers), body=_response.json(), cause=e
+            )
+        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
+
+    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,
+    ) -> AsyncHttpResponse[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
+        -------
+        AsyncHttpResponse[SubscriptionDetail]
+            Subscription updated successfully.
+        """
+        _response = await self._client_wrapper.httpx_client.request(
+            f"ps/api/v1/public/subscriptions/{encode_path_param(subscription_id)}",
+            method="PATCH",
+            json={
+                "new_plan_id": new_plan_id,
+                "new_end_date": new_end_date,
+                "reason": reason,
+            },
+            headers={
+                "content-type": "application/json",
+            },
+            request_options=request_options,
+            omit=OMIT,
+        )
+        try:
+            if 200 <= _response.status_code < 300:
+                _data = typing.cast(
+                    SubscriptionDetail,
+                    parse_obj_as(
+                        type_=SubscriptionDetail,  # type: ignore
+                        object_=_response.json(),
+                    ),
+                )
+                return AsyncHttpResponse(response=_response, data=_data)
+            if _response.status_code == 404:
+                raise NotFoundError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            if _response.status_code == 500:
+                raise InternalServerError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            _response_json = _response.json()
+        except JSONDecodeError:
+            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
+        except ValidationError as e:
+            raise ParsingError(
+                status_code=_response.status_code, headers=dict(_response.headers), body=_response.json(), cause=e
+            )
+        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
+
+    async def get_subscription_by_merchant_reference(
+        self, merchant_subscription_reference: str, *, request_options: typing.Optional[RequestOptions] = None
+    ) -> AsyncHttpResponse[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
+        -------
+        AsyncHttpResponse[SubscriptionDetail]
+            Subscription retrieved successfully.
+        """
+        _response = await self._client_wrapper.httpx_client.request(
+            f"ps/api/v1/public/subscriptions/reference/{encode_path_param(merchant_subscription_reference)}",
+            method="GET",
+            request_options=request_options,
+        )
+        try:
+            if 200 <= _response.status_code < 300:
+                _data = typing.cast(
+                    SubscriptionDetail,
+                    parse_obj_as(
+                        type_=SubscriptionDetail,  # type: ignore
+                        object_=_response.json(),
+                    ),
+                )
+                return AsyncHttpResponse(response=_response, data=_data)
+            if _response.status_code == 500:
+                raise InternalServerError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            _response_json = _response.json()
+        except JSONDecodeError:
+            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
+        except ValidationError as e:
+            raise ParsingError(
+                status_code=_response.status_code, headers=dict(_response.headers), body=_response.json(), cause=e
+            )
+        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
+
+    async def cancel_subscription(
+        self, subscription_id: str, *, request_options: typing.Optional[RequestOptions] = None
+    ) -> AsyncHttpResponse[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
+        -------
+        AsyncHttpResponse[SubscriptionDetail]
+            Subscription cancelled successfully.
+        """
+        _response = await self._client_wrapper.httpx_client.request(
+            f"ps/api/v1/public/subscriptions/{encode_path_param(subscription_id)}/cancel",
+            method="POST",
+            request_options=request_options,
+        )
+        try:
+            if 200 <= _response.status_code < 300:
+                _data = typing.cast(
+                    SubscriptionDetail,
+                    parse_obj_as(
+                        type_=SubscriptionDetail,  # type: ignore
+                        object_=_response.json(),
+                    ),
+                )
+                return AsyncHttpResponse(response=_response, data=_data)
+            if _response.status_code == 400:
+                raise BadRequestError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        typing.Any,
+                        parse_obj_as(
+                            type_=typing.Any,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            _response_json = _response.json()
+        except JSONDecodeError:
+            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
+        except ValidationError as e:
+            raise ParsingError(
+                status_code=_response.status_code, headers=dict(_response.headers), body=_response.json(), cause=e
+            )
+        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
+
+    async def pause_subscription(
+        self, subscription_id: str, *, request_options: typing.Optional[RequestOptions] = None
+    ) -> AsyncHttpResponse[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
+        -------
+        AsyncHttpResponse[SubscriptionDetail]
+            Subscription paused successfully.
+        """
+        _response = await self._client_wrapper.httpx_client.request(
+            f"ps/api/v1/public/subscriptions/{encode_path_param(subscription_id)}/pause",
+            method="POST",
+            request_options=request_options,
+        )
+        try:
+            if 200 <= _response.status_code < 300:
+                _data = typing.cast(
+                    SubscriptionDetail,
+                    parse_obj_as(
+                        type_=SubscriptionDetail,  # type: ignore
+                        object_=_response.json(),
+                    ),
+                )
+                return AsyncHttpResponse(response=_response, data=_data)
+            if _response.status_code == 500:
+                raise InternalServerError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            _response_json = _response.json()
+        except JSONDecodeError:
+            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
+        except ValidationError as e:
+            raise ParsingError(
+                status_code=_response.status_code, headers=dict(_response.headers), body=_response.json(), cause=e
+            )
+        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)
+
+    async def resume_subscription(
+        self, subscription_id: str, *, request_options: typing.Optional[RequestOptions] = None
+    ) -> AsyncHttpResponse[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
+        -------
+        AsyncHttpResponse[SubscriptionDetail]
+            Subscription resumed successfully.
+        """
+        _response = await self._client_wrapper.httpx_client.request(
+            f"ps/api/v1/public/subscriptions/{encode_path_param(subscription_id)}/resume",
+            method="POST",
+            request_options=request_options,
+        )
+        try:
+            if 200 <= _response.status_code < 300:
+                _data = typing.cast(
+                    SubscriptionDetail,
+                    parse_obj_as(
+                        type_=SubscriptionDetail,  # type: ignore
+                        object_=_response.json(),
+                    ),
+                )
+                return AsyncHttpResponse(response=_response, data=_data)
+            if _response.status_code == 500:
+                raise InternalServerError(
+                    headers=dict(_response.headers),
+                    body=typing.cast(
+                        ErrorResponse,
+                        parse_obj_as(
+                            type_=ErrorResponse,  # type: ignore
+                            object_=_response.json(),
+                        ),
+                    ),
+                )
+            _response_json = _response.json()
+        except JSONDecodeError:
+            raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response.text)
+        except ValidationError as e:
+            raise ParsingError(
+                status_code=_response.status_code, headers=dict(_response.headers), body=_response.json(), cause=e
+            )
+        raise ApiError(status_code=_response.status_code, headers=dict(_response.headers), body=_response_json)