> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base39.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Listar assinaturas da conta com saldo, produtos e uso



## OpenAPI

````yaml /api-reference/openapi.json get /v2/billing/subscriptions
openapi: 3.1.0
info:
  title: Base39 API
  description: Base39 API
  version: 1.0.0
  contact:
    name: Base39 Team
    url: https://base39.com.br
    email: suporte@base39.com.br
  termsOfService: https://base39.com.br/termos
  license:
    name: Proprietary
    url: https://base39.com.br/termos
servers:
  - url: http://localhost:3000
    description: Local
  - url: https://api.dev.base39.cloud
    description: Development
  - url: https://api.base39.com.br
    description: Production
security:
  - OAuth2: []
tags:
  - name: pages
    description: Profiles and reports pages
  - name: pipelines
    description: Pipeline boards (kanban) of pages
  - name: blocks
    description: Blocks operations
  - name: search
    description: Search across content
  - name: targets
    description: Lookup targets via datasets
  - name: CognitoTriggers
    description: Cognito triggers
paths:
  /v2/billing/subscriptions:
    get:
      tags:
        - billing
      summary: Listar assinaturas da conta com saldo, produtos e uso
      operationId: billing_get_subscriptions
      parameters:
        - name: include_breakdown
          required: false
          in: query
          description: Include dataset cost breakdown for billing summary tables.
          schema:
            type: boolean
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionListOutput'
components:
  schemas:
    SubscriptionListOutput:
      type: object
      properties:
        object:
          type: string
          description: Object type identifier
          default: list
        results:
          description: Assinaturas visíveis para a organização
          type: array
          items:
            $ref: '#/components/schemas/AccountSubscriptionOutput'
        next_cursor:
          type: string
          description: Opaque cursor for next page. null if no more results.
          nullable: true
        has_more:
          type: boolean
          description: Whether more results exist beyond this page
        type:
          type: string
          description: Tipo dos itens retornados
          example: subscription
        currentSubscriptionId:
          type: string
          description: ID da assinatura corrente
          nullable: true
        hasActiveSubscription:
          type: boolean
          description: Se existe assinatura ativa corrente
          example: true
        creditBalance:
          type: number
          description: Saldo disponível de créditos em centavos
          example: 10000
        currentBillTotal:
          type: number
          description: Total atual agregado da fatura em centavos
          example: 9900
        currentPlanTotal:
          type: number
          description: Parcela atual agregada de plano em centavos
          example: 7900
        currentExcessTotal:
          type: number
          description: Parcela atual agregada excedente em centavos
          example: 2000
        billingPeriod:
          description: Período de cobrança corrente
          nullable: true
          allOf:
            - $ref: '#/components/schemas/SubscriptionBillingPeriodOutput'
        usageSummary:
          type: object
          description: Resumo de uso agregado por meter
          additionalProperties:
            type: object
      required:
        - object
        - results
        - has_more
        - currentSubscriptionId
        - hasActiveSubscription
        - creditBalance
        - currentBillTotal
        - currentPlanTotal
        - currentExcessTotal
        - billingPeriod
        - usageSummary
    AccountSubscriptionOutput:
      type: object
      properties:
        object:
          type: string
          description: Object type
          example: subscription
          enum:
            - subscription
        id:
          type: string
          description: ID da assinatura no Stripe
          example: sub_xxx
          nullable: true
        status:
          type: string
          description: Status da assinatura
          example: active
        customerId:
          type: object
          description: ID do customer no Stripe
          nullable: true
          example: cus_xxx
        priceId:
          type: object
          description: ID do preço no Stripe
          nullable: true
          example: price_xxx
        hasActiveSubscription:
          type: boolean
          description: Se a assinatura está ativa
          example: true
        currentPeriodStart:
          type: string
          description: Início do período atual
          format: date-time
          nullable: true
        currentPeriodEnd:
          type: string
          description: Fim do período atual
          format: date-time
          nullable: true
        cancelAtPeriodEnd:
          type: boolean
          description: Cancelamento ao fim do período
          example: false
        trialEnd:
          type: string
          description: Fim do trial
          format: date-time
          nullable: true
        credits:
          description: Saldo de créditos do período atual
          nullable: true
          allOf:
            - $ref: '#/components/schemas/CreditsOutput'
        currentBillTotal:
          type: number
          description: Total atual da fatura em aberto/próxima fatura em centavos
          example: 9900
        currentPlanTotal:
          type: number
          description: >-
            Parcela atual de plano da fatura em aberto/próxima fatura em
            centavos
          example: 7900
        currentExcessTotal:
          type: number
          description: >-
            Parcela atual excedente da fatura em aberto/próxima fatura em
            centavos
          example: 2000
        creditGrants:
          description: Credit grants globais aplicáveis a produtos medidos
          type: array
          items:
            $ref: '#/components/schemas/CreditGrantOutput'
        trialDaysRemaining:
          type: integer
          description: Dias restantes de trial
          example: 7
          nullable: true
        defaultPaymentMethod:
          type: string
          description: Método de pagamento padrão
          nullable: true
          example: Cartão •••• 4242
        products:
          description: Produtos contratados com uso
          type: array
          items:
            $ref: '#/components/schemas/BillingProductOutput'
        productQuotas:
          description: Quotas incluídas por produto na assinatura
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionProductQuotaOutput'
        addons:
          description: Add-ons disponíveis
          type: array
          items:
            $ref: '#/components/schemas/BillingAddonOutput'
        billingInterval:
          type: string
          description: Intervalo de cobrança
          example: month
        pastDueInvoices:
          description: Faturas em aberto com valor a pagar para esta assinatura
          type: array
          items:
            $ref: '#/components/schemas/PastDueInvoiceRefOutput'
        hasPastDueInvoices:
          type: boolean
          description: Indica se existem faturas em aberto para esta assinatura
          example: false
        isCurrent:
          type: boolean
          description: Se esta assinatura é a assinatura corrente da organização
          example: true
        orgId:
          type: string
          description: ID da organização associada à assinatura
          nullable: true
        name:
          type: string
          description: Nome exibível da assinatura (produto principal)
          example: Plano por consumo
        type:
          type: string
          description: Tipo de cobrança da assinatura
          enum:
            - metered
            - credits
          example: metered
        editable:
          type: boolean
          description: >-
            Se a conta atual pode gerenciar esta assinatura (dona do customer
            Stripe)
          example: true
        customerName:
          type: string
          description: >-
            Nome do customer Stripe quando difere do customer da org atual (null
            se for o mesmo)
          nullable: true
          example: Base39 Holding S.A.
        metadata:
          type: object
          description: Metadata da assinatura no Stripe
          additionalProperties:
            type: string
          example:
            plan: pay_as_you_go
            billing_mode: prepaid
      required:
        - object
        - id
        - status
        - hasActiveSubscription
        - currentPeriodStart
        - currentPeriodEnd
        - cancelAtPeriodEnd
        - trialEnd
        - currentBillTotal
        - currentPlanTotal
        - currentExcessTotal
        - creditGrants
        - trialDaysRemaining
        - defaultPaymentMethod
        - products
        - addons
        - billingInterval
        - pastDueInvoices
        - hasPastDueInvoices
        - isCurrent
        - orgId
        - name
        - type
        - editable
        - customerName
        - metadata
    SubscriptionBillingPeriodOutput:
      type: object
      properties:
        currentPeriodStart:
          type: string
          description: Início do período corrente
          format: date-time
          nullable: true
        currentPeriodEnd:
          type: string
          description: Fim do período corrente
          format: date-time
          nullable: true
        interval:
          type: string
          description: Intervalo de cobrança
          nullable: true
          example: month
      required:
        - currentPeriodStart
        - currentPeriodEnd
        - interval
    CreditsOutput:
      type: object
      properties:
        name:
          type: string
          description: Nome exibível do saldo de créditos
          example: Créditos
        used:
          type: number
          description: Centavos consumidos no período atual
          example: 4250
        included:
          type: number
          description: Créditos incluídos no período atual em centavos
          example: 10000
        granted:
          type: number
          description: Créditos concedidos (grants globais) aplicáveis em centavos
          example: 5000
        remaining:
          type: number
          description: Créditos restantes no período atual em centavos
          example: 5750
        exceeded:
          type: number
          description: Créditos excedentes no período atual em centavos
          example: 250
        currency:
          type: string
          description: Moeda
          example: brl
        currentPeriodStart:
          type: string
          description: Início do período atual de créditos
          format: date-time
        currentPeriodEnd:
          type: string
          description: Fim do período atual de créditos
          format: date-time
      required:
        - name
        - used
        - included
        - granted
        - remaining
        - exceeded
        - currency
        - currentPeriodStart
        - currentPeriodEnd
    CreditGrantOutput:
      type: object
      properties:
        id:
          type: string
          description: ID do credit grant Stripe
          example: credgr_xxx
        name:
          type: string
          description: Nome exibível do credit grant
          example: Recarga de saldo
          nullable: true
        amount:
          type: number
          description: Valor concedido em centavos
          example: 10000
        category:
          type: string
          description: Categoria do credit grant Stripe
          example: promotional
          nullable: true
        effectiveAt:
          type: string
          description: Início da validade do credit grant
          format: date-time
          nullable: true
        expiresAt:
          type: string
          description: Fim da validade do credit grant
          format: date-time
          nullable: true
      required:
        - id
        - name
        - amount
        - category
        - effectiveAt
        - expiresAt
    BillingProductOutput:
      type: object
      properties:
        productGroup:
          type: string
          description: Grupo lógico do produto para agrupamento visual
          example: queries
        slug:
          type: string
          description: Slug do produto
          example: entities
        name:
          type: string
          description: Nome do produto
          example: Agente IA
        description:
          type: object
          description: Descrição do produto
          nullable: true
        meters:
          description: Meters de uso do produto
          type: array
          items:
            $ref: '#/components/schemas/ProductUsageMeterOutput'
        amountMtd:
          type: number
          description: Custo acumulado no mês em centavos
          example: 0
        grantedShared:
          type: number
          description: Créditos compartilhados (grants globais) em centavos
          example: 0
        currency:
          type: string
          description: Moeda
          example: brl
        spendLimit:
          type: integer
          description: >-
            Limite de gasto mensal cobrável para este produto em centavos (null
            = ilimitado)
          nullable: true
          example: 50000
      required:
        - productGroup
        - slug
        - name
        - description
        - meters
        - amountMtd
        - grantedShared
        - currency
        - spendLimit
    SubscriptionProductQuotaOutput:
      type: object
      properties:
        productSlug:
          type: string
          description: Produto da assinatura que concede a quota
          example: entities_tier_2
        included:
          type: number
          description: Quantidade incluída no período
          example: 100
      required:
        - productSlug
        - included
    BillingAddonOutput:
      type: object
      properties:
        slug:
          type: string
          description: Slug do addon
          example: premium_support
        name:
          type: string
          description: Nome do addon
          example: Segurança avançada
        description:
          type: object
          description: Descrição do addon
          nullable: true
        active:
          type: boolean
          description: Se o addon está ativo
          example: false
        price:
          type: object
          description: Preço recorrente mensal em centavos
          nullable: true
          example: 350000
        setupPrice:
          type: object
          description: Preço único de implementação em centavos
          nullable: true
          example: 500000
        marketingFeatures:
          description: Marketing features do addon
          nullable: true
          type: array
          items:
            type: string
      required:
        - slug
        - name
        - description
        - active
        - price
    PastDueInvoiceRefOutput:
      type: object
      properties:
        id:
          type: string
          description: ID da fatura no Stripe
          example: in_xxx
        dueDate:
          type: string
          description: Data de vencimento
          format: date-time
          nullable: true
        amount:
          type: number
          description: Valor em reais
          example: 99.9
      required:
        - id
        - dueDate
        - amount
    ProductUsageMeterOutput:
      type: object
      properties:
        slug:
          type: string
          description: Slug do meter
          example: entity_retrieved
        eventName:
          type: string
          description: Nome do evento Stripe Billing Meter
          example: entity.retrieved
        name:
          type: string
          description: Nome exibível
          example: Execuções
        current:
          type: number
          description: Uso atual no período
          example: 42
        granted:
          type: number
          description: Quantidade concedida (credit grant)
          example: 100
        limit:
          type: object
          description: Limite de cobrança configurado
          example: 500
          nullable: true
        amountMtd:
          type: number
          description: Custo acumulado no mês em centavos para este meter
          example: 0
        unit:
          type: string
          description: Unidade de medida
          example: execuções
        included:
          type: number
          description: Quantidade incluída no plano (tier contratado)
          example: 85
        unitPrice:
          type: object
          description: Preço unitário em centavos (da assinatura do cliente)
          example: 499
          nullable: true
        tiers:
          type: array
          description: >-
            Tiers graduados do price (em ordem). flatAmount = faixa de franquia
            paga; unitAmount = faixa por unidade. upTo null = ilimitado.
          items:
            type: object
            properties:
              upTo:
                type: number
                nullable: true
              flatAmount:
                type: number
                nullable: true
              unitAmount:
                type: number
                nullable: true
        datasets:
          description: Slugs de datasets incluídos neste meter
          type: array
          items:
            type: string
        includedDatasets:
          type: array
          description: Datasets incluídos neste meter
          items:
            type: object
            properties:
              slug:
                type: string
              name:
                type: string
            required:
              - slug
              - name
        breakdown:
          type: array
          description: Detalhamento por dataset (apenas para consultas avulsas)
          items:
            type: object
            properties:
              datasetName:
                type: string
              quantity:
                type: number
              amount:
                type: number
        capacitySources:
          description: Fontes de capacidade disponíveis para este meter
          type: array
          items:
            $ref: '#/components/schemas/BillingCapacitySourceOutput'
        selectedCapacitySource:
          description: Fonte de capacidade selecionada para o próximo uso deste meter
          nullable: true
          allOf:
            - $ref: '#/components/schemas/BillingCapacitySourceOutput'
      required:
        - slug
        - eventName
        - name
        - current
        - granted
        - limit
        - amountMtd
        - unit
        - capacitySources
    BillingCapacitySourceOutput:
      type: object
      properties:
        sourceId:
          type: string
          description: Identificador estável da fonte de capacidade
          example: subscription_item:si_123
        sourceType:
          type: string
          description: Tipo de fonte
          enum:
            - subscription_item
            - credit_grant
        orgId:
          type: string
          description: Org dona da fonte
          example: org_123
        customerId:
          type: string
          description: Customer Stripe dono da fonte
          example: cus_123
        subscriptionId:
          type: object
          description: Subscription Stripe associada
          nullable: true
          example: sub_123
        subscriptionItemId:
          type: object
          description: Subscription item Stripe associado
          nullable: true
          example: si_123
        priceId:
          type: object
          description: Price Stripe associado
          nullable: true
          example: price_123
        productSlug:
          type: string
          description: Produto Base39 coberto pela fonte
          example: entities_tier_2
        meterEventName:
          type: string
          description: Meter event coberto pela fonte
          example: entity.retrieved
        billingMode:
          type: string
          description: Modo de cobrança da subscription
          enum:
            - prepaid
            - postpaid
        priority:
          type: number
          description: Prioridade de seleção. Menor número vence.
          example: 10
        eligible:
          type: boolean
          description: Se a fonte cobre este meter/produto
          example: true
        usage:
          $ref: '#/components/schemas/BillingCapacityUsageOutput'
        limits:
          $ref: '#/components/schemas/BillingCapacityLimitsOutput'
        availability:
          $ref: '#/components/schemas/BillingCapacityAvailabilityOutput'
      required:
        - sourceId
        - sourceType
        - orgId
        - customerId
        - productSlug
        - meterEventName
        - billingMode
        - priority
        - eligible
        - usage
        - limits
        - availability
    BillingCapacityUsageOutput:
      type: object
      properties:
        amountMtd:
          type: number
          description: Valor cobrável acumulado no mês em centavos
          example: 1490
        quantityMtd:
          type: number
          description: Quantidade acumulada no mês
          example: 1
      required:
        - amountMtd
        - quantityMtd
    BillingCapacityLimitsOutput:
      type: object
      properties:
        spendLimit:
          type: object
          description: Spend limit em centavos para o produto nesta conta
          nullable: true
          example: 100000
        includedRemainingQuantity:
          type: object
          description: Quantidade incluída restante nesta fonte
          nullable: true
          example: 50
        creditRemainingAmount:
          type: number
          description: Créditos Stripe restantes aplicáveis em centavos
          example: 50000
        remainingSpendLimit:
          type: object
          description: Spend limit restante em centavos
          nullable: true
          example: 25000
      required:
        - spendLimit
        - includedRemainingQuantity
        - creditRemainingAmount
        - remainingSpendLimit
    BillingCapacityAvailabilityOutput:
      type: object
      properties:
        available:
          type: boolean
          description: Se esta fonte pode receber o próximo uso
          example: true
        blocker:
          type: string
          description: Motivo de bloqueio quando a fonte não está disponível
          nullable: true
          enum:
            - product_not_available
            - subscription_inactive
            - spend_limit_reached
            - prepaid_balance_depleted
      required:
        - available
        - blocker
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://id.local.base39.cloud/oauth2/authorize
          tokenUrl: https://id.local.base39.cloud/oauth2/token
          scopes:
            profile: Read user profile
            email: Read user email
            openid: OpenID authentication
      description: OAuth2 Authorization Code flow

````