> ## Documentation Index > Fetch the complete documentation index at: https://docs.besimplo.com/llms.txt > Use this file to discover all available pages before exploring further. # Listar assinaturas > Retorna uma lista paginada de assinaturas da conta. ## OpenAPI ````yaml /api-reference/openapi.yml get /api/v1/subscriptions openapi: 3.1.0 info: title: API - Simplo version: 1.0.0 description: API para cobrança e assinaturas para contas Simplo contact: name: Simplo url: https://besimplo.com email: team@besimplo.com servers: - url: https://besimplo.com description: Produção security: - apiKeyAuth: [] tags: - name: Clientes description: Clientes são as pessoas que pagarão pelos produtos da sua conta - name: Produtos description: Produtos representam os bens ou serviços que você vende - name: Preços description: Preços definem quanto cobrar e a frequência de cobrança de um Produto - name: Assinaturas description: Assinaturas conectam clientes aos seus planos para cobrança recorrente - name: Checkout description: >- Sessões de checkout permitem que clientes completem pagamentos e assinaturas através de uma interface web - name: Faturas description: Faturas representam cobranças geradas para clientes - name: Reembolsos description: Reembolsos permitem devolver pagamentos já realizados aos clientes - name: Webhooks description: > Eventos enviados via HTTP POST para a URL configurada na sua conta. Responda com status 2xx rapidamente. Processe o evento de forma assincrona. Use o campo `event.id` para garantir idempotencia. paths: /api/v1/subscriptions: get: tags: - Assinaturas summary: Listar assinaturas description: Retorna uma lista paginada de assinaturas da conta. operationId: listSubscriptions parameters: - name: customer in: query schema: type: string pattern: ^cus_[0-9a-z]{26}$ example: cus_01h455vb4pex5vsknk084sn02p description: Filtrar pelo ID do cliente (TypeID com prefixo `cus_`). - name: status in: query schema: type: string enum: - pending - active - inactive - suspended description: Filtrar por status da assinatura. - name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 20 description: Resultados por página - name: page in: query schema: type: string description: Cursor para próxima página responses: '200': description: Lista de assinaturas content: application/json: schema: type: object description: Lista paginada de assinaturas. required: - object - data - has_more - url properties: object: type: string description: Tipo do objeto. Sempre 'list'. enum: - list example: list data: type: array description: Assinaturas retornadas. items: allOf: - type: object required: - id - live_mode - status - start_date - payment_method_type - installments - item - customer properties: id: type: string pattern: ^sub_[0-9a-z]{26}$ readOnly: true description: >- ID único da assinatura, no formato TypeID com prefixo `sub_`. example: sub_01h455vb4pex5vsknk084sn02s object: type: string description: Tipo do objeto. Sempre 'subscription'. enum: - subscription example: subscription live_mode: type: boolean description: >- Indica ambiente de produção (true) ou sandbox (false). Dados de sandbox são limpos periodicamente. example: true status: type: string description: > Status da assinatura: - pending: Assinatura criada, aguardando primeiro pagamento. - active: Primeiro pagamento confirmado. Assinatura ativa. - inactive: Assinatura cancelada. - suspended: Assinatura suspensa por falha de pagamento. example: active enum: - pending - active - inactive - suspended external_code: type: - string - 'null' nullable: true description: >- Código externo para integração com outros sistemas. example: ACCOUNT-SUB-XYZ start_date: type: integer format: int64 description: Data de início da assinatura (timestamp Unix). example: 1764039600 ended: type: - integer - 'null' format: int64 nullable: true description: >- Data de término da assinatura (timestamp Unix). Null se ainda ativa. example: 1795575600 billing_cycle_anchor: type: integer format: int64 description: >- Data de referência para o ciclo de cobrança (timestamp Unix). example: 1764039600 payment_method_type: oneOf: - type: string enum: - card - pix - type: 'null' description: > Método de pagamento da assinatura: - card: Cartão de crédito. - pix: Pagamento instantâneo via PIX. - null: Ainda não definido até a confirmação do primeiro pagamento. example: null installments: type: integer description: > Quantidade de parcelas para cobrança no cartão de crédito. Valor 1 indica pagamento à vista. minimum: 1 maximum: 12 default: 1 example: 1 current_period_start: type: - integer - 'null' format: int64 nullable: true description: >- Início do período atual (timestamp Unix). `null` se a assinatura ainda não iniciou seu primeiro ciclo. example: 1764039600 latest_invoice: type: - string - 'null' pattern: ^in_[0-9a-z]{26}$ nullable: true description: >- ID da última fatura gerada, no formato TypeID com prefixo `in_`. example: in_01h455vb4pex5vsknk084sn02q created: type: integer format: int64 readOnly: true description: Data de criação da assinatura (timestamp Unix). example: 1764040287 customer: type: string pattern: ^cus_[0-9a-z]{26}$ description: >- ID do cliente associado, no formato TypeID com prefixo `cus_`. example: cus_01h455vb4pex5vsknk084sn02p item: type: object required: - id - object - quantity - price properties: id: type: string pattern: ^si_[0-9a-z]{26}$ description: >- ID único do item, no formato TypeID com prefixo `si_`. example: si_01h455vb4pex5vsknk084sn02i object: type: string description: Tipo do objeto. Sempre 'subscription_item'. example: subscription_item created: type: integer format: int64 description: Data de criação do item (timestamp Unix). example: 1764040287 current_period_end: type: - integer - 'null' format: int64 nullable: true description: >- Fim do período atual (timestamp Unix). `null` se a assinatura ainda não iniciou seu primeiro ciclo. example: 1764039600 current_period_start: type: - integer - 'null' format: int64 nullable: true description: >- Início do período atual (timestamp Unix). `null` se a assinatura ainda não iniciou seu primeiro ciclo. example: 1764039600 price: type: object required: - id - object - unit_amount - currency - product properties: id: type: string pattern: ^price_[0-9a-z]{26}$ description: >- ID único do preço, no formato TypeID com prefixo `price_`. example: price_01h455vb4pex5vsknk084sn02q object: type: string description: Tipo do objeto. Sempre 'price'. example: price active: type: boolean description: Indica se o preço está ativo. currency: type: string description: >- Moeda do valor. Sempre 'brl' (Real brasileiro). enum: - brl example: brl type: type: string description: | Tipo de cobrança: - recurring: Cobrança recorrente. - one_time: Cobrança única. enum: - recurring - one_time unit_amount: type: integer description: Valor em centavos. R$ 5,00 = 500. unit_amount_decimal: type: string description: Valor em formato decimal. example: '500' recurring_interval: type: string description: | Intervalo de recorrência: - day: Diário. - week: Semanal. - month: Mensal. - year: Anual. enum: - day - week - month - year recurring_interval_count: type: integer description: >- Quantidade de intervalos entre cobranças. created: type: integer format: int64 description: >- Data de criação do preço (timestamp Unix). example: 1764040287 product: type: string pattern: ^prod_[0-9a-z]{26}$ description: >- ID do produto associado, no formato TypeID com prefixo `prod_`. example: prod_01h455vb4pex5vsknk084sn02q nickname: type: - string - 'null' nullable: true description: >- Apelido do preço para fácil identificação. example: Preço mensal básico quantity: type: integer description: Quantidade de unidades contratadas. subscription: type: string pattern: ^sub_[0-9a-z]{26}$ description: >- ID da assinatura associada, no formato TypeID com prefixo `sub_`. example: sub_01h455vb4pex5vsknk084sn02s discounts: type: object properties: object: type: string example: list data: type: array items: type: object properties: id: type: string pattern: ^sdi_[0-9a-z]{26}$ description: >- ID único do desconto, no formato TypeID com prefixo `sdi_`. example: sdi_01h455vb4pex5vsknk084sn02d object: type: string description: Tipo do objeto. Sempre 'discount'. example: discount has_more: type: boolean description: Indica se existem mais páginas de resultados. example: false url: type: string format: uri-reference description: Endpoint da listagem. example: /api/v1/subscriptions additionalProperties: false '404': description: Não encontrado content: application/problem+json: schema: type: object required: - type - status - title - detail - code properties: type: type: string description: URI que identifica o tipo de problema format: uri enum: - https://problems-registry.smartbear.com/not-found status: type: integer description: O código de status HTTP format: int32 enum: - 404 title: type: string description: O nome do status HTTP enum: - Not Found detail: type: string description: Mensagem descritiva do erro code: type: string description: Código de erro interno da API enum: - NOT_FOUND - RESOURCE_MISSING examples: not_found: summary: Recurso não encontrado value: type: https://problems-registry.smartbear.com/not-found status: 404 title: Not Found detail: The requested resource was not found code: NOT_FOUND customer_not_found: summary: Cliente não encontrado value: type: https://problems-registry.smartbear.com/not-found status: 404 title: Not Found detail: 'No such customer: ''019abc12-3456-7890-abcd-ef1234567890''' code: RESOURCE_MISSING components: securitySchemes: apiKeyAuth: type: apiKey in: header name: Authorization description: > A chave de API usada para autenticar a requisição e identificar a sua conta. **Exemplo:** `Authorization: ApiKey my-secure-key` ````