get_subscriptions

Instructions

Implementation Reference

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

  The main handler function for the 'get_subscriptions' tool. It accepts optional filter parameters (max_results, page_token, product_id, plan, plan_id, accession_date, status, subscriber_code, etc.), builds a params dict, makes a GET request to the Hotmart API endpoint '/payments/api/v1/subscriptions', and returns the JSON response.

  async def get_subscriptions(
      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
      
      Retorna a lista de assinaturas.
      
      Args:
          max_results: Número máximo de resultados por página
          page_token: Token de paginação para a próxima página
          product_id: ID do produto
          plan: Nomes dos planos
          plan_id: ID do plano
          accession_date: Data de adesão inicial (timestamp em milissegundos)
          end_accession_date: Data de adesão final (timestamp em milissegundos)
          status: Status da assinatura. Values: ACTIVE, INACTIVE, DELAYED, CANCELLED_BY_CUSTOMER, CANCELLED_BY_SELLER, CANCELLED_BY_ADMIN, STARTED, OVERDUE
          subscriber_code: Código do assinante
          subscriber_email: E-mail do assinante
          transaction: Código da transação
          trial: Filtrar por trial
          cancelation_date: Data de cancelamento inicial (timestamp em milissegundos)
          end_cancelation_date: Data de cancelamento final (timestamp em milissegundos)
          date_next_charge: Data da próxima cobrança inicial (timestamp em milissegundos)
          end_date_next_charge: Data da próxima cobrança final (timestamp em milissegundos)
          select: Seleção de campos customizados na resposta"""
      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:21-37 (registration)

  Tool registration via auto-discovery. '_discover_and_register_tools' iterates over all modules in hotmart_mcp.tools and registers every public async function (including get_subscriptions) as a FastMCP tool using mcp.tool()(obj).

  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-29 (schema)

  The function signature defines the input schema: all optional parameters with types (Optional[int], Optional[str], Optional[list[str]], Optional[bool]) and the status enum values documented in the docstring.

  async def get_subscriptions(
      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:

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

  Helper function 'get_client()' that provides the shared HotmartClient singleton used by get_subscriptions to make the API call.

  def get_client() -> HotmartClient:
      global _client
      if _client is None:
          _client = HotmartClient()
      return _client