hotmart_subscriptions_list

Instructions

Implementation Reference

• src/hotmart_mcp/tools/subscriptions.py:11-96 (handler)

  The async function `hotmart_subscriptions_list` that implements the tool logic. It builds query params from optional arguments and calls the GET /payments/api/v1/subscriptions endpoint via the shared client, returning JSON.

  async def hotmart_subscriptions_list(
      max_results: Optional[int] = None,
      page_token: Optional[str] = None,
      product_id: Optional[int] = None,
      plan: Optional[list[str]] = None,
      plan_id: Optional[int] = None,
      accession_date: Optional[int] = None,
      end_accession_date: Optional[int] = None,
      status: Optional[str] = None,
      subscriber_code: Optional[str] = None,
      subscriber_email: Optional[str] = None,
      transaction: Optional[str] = None,
      trial: Optional[bool] = None,
      cancelation_date: Optional[int] = None,
      end_cancelation_date: Optional[int] = None,
      date_next_charge: Optional[int] = None,
      end_date_next_charge: Optional[int] = None,
      select: Optional[str] = None,
  ) -> str:
      """Get Subscriptions. Example: hotmart_subscriptions_list(max_results=10). Don't use this for payment events — use `hotmart_subscription_transactions_list` for charges/refunds per subscription.
      
      Args:
          max_results: Max results per page
          page_token: Pagination token for the next page
          product_id: Product ID
          plan: Nomes dos planos. Pass a JSON array of strings, e.g. `['ABC123XY', 'DEF456ZW']`.
          plan_id: ID do plano
          accession_date: Subscription start date (lower bound). Unix timestamp in **milliseconds** (not seconds, not ISO). Ex: `1730419200000` = 2024-11-01 00:00 UTC. Python: `int(datetime(2024,11,1).timestamp() * 1000)`.
          end_accession_date: Subscription start date (upper bound). Unix timestamp in **milliseconds** (not seconds, not ISO). Ex: `1730419200000` = 2024-11-01 00:00 UTC. Python: `int(datetime(2024,11,1).timestamp() * 1000)`.
          status: Subscription status.
          Allowed values (case-sensitive, pass EXACTLY as listed):
            - `ACTIVE`
            - `INACTIVE`
            - `DELAYED`
            - `CANCELLED_BY_CUSTOMER`
            - `CANCELLED_BY_SELLER`
            - `CANCELLED_BY_ADMIN`
            - `STARTED`
            - `OVERDUE`
          subscriber_code: Subscriber code. Format: alphanumeric Hotmart code (ex: `H123A4B5`, not UUID, not int)
          subscriber_email: Email do assinante
          transaction: Transaction code
          trial: Filtrar por trial
          cancelation_date: Data de cancelamento inicial. Unix timestamp in **milliseconds** (not seconds, not ISO). Ex: `1730419200000` = 2024-11-01 00:00 UTC. Python: `int(datetime(2024,11,1).timestamp() * 1000)`.
          end_cancelation_date: Data de cancelamento final. Unix timestamp in **milliseconds** (not seconds, not ISO). Ex: `1730419200000` = 2024-11-01 00:00 UTC. Python: `int(datetime(2024,11,1).timestamp() * 1000)`.
          date_next_charge: Data da próxima cobrança inicial. Unix timestamp in **milliseconds** (not seconds, not ISO). Ex: `1730419200000` = 2024-11-01 00:00 UTC. Python: `int(datetime(2024,11,1).timestamp() * 1000)`.
          end_date_next_charge: Data da próxima cobrança final. Unix timestamp in **milliseconds** (not seconds, not ISO). Ex: `1730419200000` = 2024-11-01 00:00 UTC. Python: `int(datetime(2024,11,1).timestamp() * 1000)`.
          select: Custom field selection in response"""
      endpoint = "/payments/api/v1/subscriptions"
      params = {}
      if max_results is not None:
          params["max_results"] = max_results
      if page_token is not None:
          params["page_token"] = page_token
      if product_id is not None:
          params["product_id"] = product_id
      if plan is not None:
          params["plan"] = plan
      if plan_id is not None:
          params["plan_id"] = plan_id
      if accession_date is not None:
          params["accession_date"] = accession_date
      if end_accession_date is not None:
          params["end_accession_date"] = end_accession_date
      if status is not None:
          params["status"] = status
      if subscriber_code is not None:
          params["subscriber_code"] = subscriber_code
      if subscriber_email is not None:
          params["subscriber_email"] = subscriber_email
      if transaction is not None:
          params["transaction"] = transaction
      if trial is not None:
          params["trial"] = trial
      if cancelation_date is not None:
          params["cancelation_date"] = cancelation_date
      if end_cancelation_date is not None:
          params["end_cancelation_date"] = end_cancelation_date
      if date_next_charge is not None:
          params["date_next_charge"] = date_next_charge
      if end_date_next_charge is not None:
          params["end_date_next_charge"] = end_date_next_charge
      if select is not None:
          params["select"] = select
      result = await get_client().get(endpoint, params=params)
      return json.dumps(result, indent=2)

• src/hotmart_mcp/server.py:25-37 (registration)

  Auto-discovery registration: `_discover_and_register_tools` iterates all modules in `hotmart_mcp.tools` and registers every public async function (including `hotmart_subscriptions_list`) via `mcp.tool()`.

  def _discover_and_register_tools() -> int:
      """Import all modules under hotmart_mcp.tools and register async functions."""
      registered = 0
      for module_info in pkgutil.iter_modules(tools_pkg.__path__, prefix=f"{tools_pkg.__name__}."):
          if module_info.name.endswith("__init__"):
              continue
          module = importlib.import_module(module_info.name)
          for name, obj in inspect.getmembers(module, iscoroutinefunction):
              if name.startswith("_"):
                  continue
              mcp.tool()(obj)
              registered += 1
      return registered

• src/hotmart_mcp/tools/subscriptions.py:11-28 (schema)

  The function signature acts as the schema: parameters like max_results, status, subscriber_code, dates (all Optional) define the input schema for the tool.

  async def hotmart_subscriptions_list(
      max_results: Optional[int] = None,
      page_token: Optional[str] = None,
      product_id: Optional[int] = None,
      plan: Optional[list[str]] = None,
      plan_id: Optional[int] = None,
      accession_date: Optional[int] = None,
      end_accession_date: Optional[int] = None,
      status: Optional[str] = None,
      subscriber_code: Optional[str] = None,
      subscriber_email: Optional[str] = None,
      transaction: Optional[str] = None,
      trial: Optional[bool] = None,
      cancelation_date: Optional[int] = None,
      end_cancelation_date: Optional[int] = None,
      date_next_charge: Optional[int] = None,
      end_date_next_charge: Optional[int] = None,
      select: Optional[str] = None,

• src/hotmart_mcp/_shared.py:1-14 (helper)

  `get_client()` is the helper that provides the shared HotmartClient singleton used by the handler to make the HTTP request.

  """Shared lazy singleton for the Hotmart API client."""
  
  from __future__ import annotations
  
  from hotmart_mcp.client import HotmartClient
  
  _client: HotmartClient | None = None
  
  
  def get_client() -> HotmartClient:
      global _client
      if _client is None:
          _client = HotmartClient()
      return _client

• src/hotmart_mcp/generator.py:318-321 (helper)

  Disambiguation hint in the code generator: maps `hotmart_subscriptions_list` to a hint telling the LLM not to use it for payment events.

  "hotmart_subscriptions_list":
      "Don't use this for payment events — use `hotmart_subscription_transactions_list` for charges/refunds per subscription.",
  "hotmart_subscription_transactions_list":
      "Don't use this for the subscription list itself — use `hotmart_subscriptions_list`.",