get_subscription_transactions

Instructions

Implementation Reference

• src/hotmart_mcp/tools/subscriptions.py:137-211 (handler)

  The main handler function for 'get_subscription_transactions'. It makes a GET request to /payments/api/v1/subscriptions/transactions with optional filter parameters and returns JSON.

  async def get_subscription_transactions(
      max_results: Optional[int] = None,
      page_token: Optional[str] = None,
      product_id: Optional[int] = None,
      transaction: Optional[str] = None,
      subscriber_name: Optional[str] = None,
      subscriber_email: Optional[str] = None,
      billing_type: Optional[str] = None,
      subscription_status: Optional[str] = None,
      recurrency_status: Optional[str] = None,
      purchase_status: Optional[str] = None,
      transaction_date: Optional[int] = None,
      end_transaction_date: Optional[int] = None,
      offer_code: Optional[str] = None,
      purchase_payment_type: Optional[str] = None,
      subscriber_code: Optional[str] = None,
      select: Optional[str] = None,
  ) -> str:
      """Subscription Transactions
      
      Retorna as transações de assinatura. Dados com atraso de 24h. Por padrão retorna os últimos 30 dias.
      
      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
          transaction: Código da transação
          subscriber_name: Nome do assinante
          subscriber_email: E-mail do assinante
          billing_type: Tipo de cobrança. Values: SUBSCRIPTION, SMART_INSTALLMENT, SMART_RECOVERY
          subscription_status: Status da assinatura. Values: STARTED, INACTIVE, ACTIVE, DELAYED, CANCELLED, CANCELLED_BY_ADMIN, CANCELLED_BY_CUSTOMER, CANCELLED_BY_SELLER, OVERDUE
          recurrency_status: Status da recorrência. Values: PAID, NOT_PAID, CLAIMED, REFUNDED, CHARGEBACK
          purchase_status: Status da compra
          transaction_date: Data da transação inicial (timestamp em milissegundos)
          end_transaction_date: Data da transação final (timestamp em milissegundos)
          offer_code: Código da oferta
          purchase_payment_type: Tipo de pagamento da compra. Values: BILLET, CASH_PAYMENT, CREDIT_CARD, DIRECT_BANK_TRANSFER, DIRECT_DEBIT, FINANCED_BILLET, FINANCED_INSTALLMENT, GOOGLE_PAY, HOTCARD, HYBRID, MANUAL_TRANSFER, PAYPAL, PAYPAL_INTERNACIONAL, PICPAY, PIX, SAMSUNG_PAY, WALLET
          subscriber_code: Código do assinante
          select: Seleção de campos customizados na resposta"""
      endpoint = "/payments/api/v1/subscriptions/transactions"
      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 transaction is not None:
          params["transaction"] = transaction
      if subscriber_name is not None:
          params["subscriber_name"] = subscriber_name
      if subscriber_email is not None:
          params["subscriber_email"] = subscriber_email
      if billing_type is not None:
          params["billing_type"] = billing_type
      if subscription_status is not None:
          params["subscription_status"] = subscription_status
      if recurrency_status is not None:
          params["recurrency_status"] = recurrency_status
      if purchase_status is not None:
          params["purchase_status"] = purchase_status
      if transaction_date is not None:
          params["transaction_date"] = transaction_date
      if end_transaction_date is not None:
          params["end_transaction_date"] = end_transaction_date
      if offer_code is not None:
          params["offer_code"] = offer_code
      if purchase_payment_type is not None:
          params["purchase_payment_type"] = purchase_payment_type
      if subscriber_code is not None:
          params["subscriber_code"] = subscriber_code
      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)

  Auto-registration mechanism: any async function in hotmart_mcp.tools.* modules (including get_subscription_transactions) is discovered and registered as an 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/_shared.py:10-14 (helper)

  Singleton helper that provides the HTTP client instance used by get_subscription_transactions to make API calls.

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