Listar assinaturas

Retorna uma lista paginada das suas assinaturas, com filtros por status, cliente, referência externa e intervalo de datas. Use esta operação para painéis de cobrança recorrente, conciliação e acompanhamento de MRR e churn — sem precisar consultar uma a uma.

GET /v1/subscriptions

Como funciona

A listagem devolve um objeto paginado (não um array cru): no nível raiz vêm os metadados de paginação (offset, limit, total, hasMore, page), o array data, o objeto merchant e os links HATEOAS (_links). A estrutura de paginação é a mesma de todas as listas da API — veja Paginação.

Cada item de data é uma projeção leve (do inglês, um resumo): traz os campos de identificação e agenda de cobrança da assinatura, mas não os blocos pesados como customer completo, billing.address, items, splits, discount ou currentCycle. Para o objeto completo de uma assinatura, use Consultar.

Os filtros se combinam (lógica E): por exemplo, status=active junto com customerid=cus_01hqzvabc retorna apenas as assinaturas ativas daquele cliente. Filtros e paginação podem ser usados juntos na mesma requisição.

Quando usar

• Montar painéis e relatórios de cobrança recorrente (carteira de assinantes, inadimplência, churn).
• Reconciliar assinaturas do seu sistema com a Selectwin via externalreference.
• Listar todas as assinaturas de um cliente específico com customerid.
• Auditar criações/alterações dentro de um intervalo de datas.

Quando NÃO usar: não use a listagem em laço (polling) para detectar mudanças de status. Reaja aos webhooks subscription.* em tempo real — veja Proibição de Polling. Para o detalhe completo de uma assinatura conhecida, use Consultar, que é mais barato que filtrar a lista.

Requisição

Headers

Esta é uma operação de leitura (GET), sem corpo — não precisa de Content-Type nem de X-Idempotency-Key.

Parâmetros de consulta (query)

Todos os parâmetros são opcionais. Os de paginação (limit, offset, sort) são comuns a todas as listas; os demais são filtros específicos de assinaturas.

Exemplo curl

Listagem simples, 20 por página, mais recentes primeiro:

curl -X GET "https://api.selectwin.io/v1/subscriptions?limit=20&offset=0&sort=descending" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Filtrando por status e cliente, dentro de um intervalo de datas:

curl -X GET "https://api.selectwin.io/v1/subscriptions?status=active&customerid=cus_01hqzvabc&daterangegte=2026-04-01T00:00:00Z&daterangelte=2026-04-30T23:59:59Z" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Resposta 200 OK

{
  "offset": 0,
  "limit": 20,
  "total": 50,
  "page": {
    "offset": { "first": 0, "prev": null, "next": 20, "last": 40 },
    "current": 1,
    "total": 3
  },
  "data": [
    {
      "id": "subs_01hqzvabc",
      "customerId": "cus_01hqzvabc",
      "name": "Plano Premium Mensal",
      "status": "active",
      "method": "credit",
      "type": "prepaid",
      "currency": "BRL",
      "frequency": "monthly",
      "frequencyCount": 1,
      "freeTrialDays": 0,
      "endDate": null,
      "exactDay": null,
      "manualBilling": false,
      "externalReference": null,
      "metadata": { "source": "website" },
      "updatedAt": "2026-04-12T17:56:33.000Z",
      "createdAt": "2026-04-12T17:56:33.000Z"
    }
  ],
  "hasMore": true,
  "merchant": {
    "name": "Seller Name",
    "merchantId": "bus_1234567890",
    "isSubAccount": false
  },
  "_links": {
    "self": { "href": "https://api.selectwin.io/v1/subscriptions", "method": "GET", "description": "List all subscriptions." },
    "create": { "href": "https://api.selectwin.io/v1/subscriptions", "method": "POST", "description": "Create a new subscription." }
  }
}

Campos de cada item de data

Os campos pesados (customer completo, billing, items, splits, discount, callback, currentCycle) não vêm na lista. Para eles, consulte o objeto individual em Consultar.

Para o significado de offset, limit, total, hasMore e page.*, veja Paginação. Prefira navegar usando os valores de page.offset.next/prev em vez de calcular offsets na mão.

Erros

Tabela com os códigos transversais aplicáveis a esta operação de leitura. Trate sempre pelo error.code, nunca pela message — veja o Catálogo de Códigos de Erro e Tratamento de Erros.

Boas práticas

1. Pagine com page.offset.next. Use os valores retornados em page.offset.* para navegar; pare quando hasMore for false (ou page.offset.next for null).
2. Filtre no servidor, não no cliente. Combine status, customerid e os daterange* para reduzir o volume trafegado em vez de buscar tudo e filtrar localmente.
3. Use daterangegte + daterangelte para janelas (ex.: "criadas em abril"); reserve daterange para um único dia.
4. Correlacione por externalReference. Grave sua referência na criação e recupere a assinatura depois via externalreference — evita guardar o subs_... de cada uma.
5. Não use a lista como polling. Para reagir a active, pastdue, canceled, etc., assine os webhooks subscription.* — veja Visão Geral e Proibição de Polling.
6. Trate IDs como opacos. Não faça parsing de id/customerId; armazene a string inteira (veja Convenções).
7. Respeite os limites de taxa. Ao iterar muitas páginas, espace as requisições para não atingir o 429.

Veja também

• Visão Geral — modelo do objeto, status e ciclo de vida.
• Criar — cria uma nova assinatura (modelo Stripe-strict).
• Consultar — objeto completo de uma assinatura.
• Cancelar — encerra uma assinatura.
• Ciclos · Itens · Splits — sub-recursos.
• Paginação · Convenções · Códigos de Erro