Consultar uma assinatura

Recupera o estado completo e atual de uma assinatura pelo seu id, incluindo o ciclo de cobrança vigente, o cliente, os itens, o desconto, os splits e os links de ações disponíveis. Use sempre que precisar da "fonte da verdade" sobre uma recorrência — antes de cobrar, cancelar ou exibir o status para o cliente.

GET /v1/subscriptions/{subscriptionId}

Como funciona

Uma assinatura (subscription) é o objeto que representa uma cobrança recorrente: um cliente, um plano (derivado das variantes de produto) e uma cadência de cobrança (frequency, frequencyCount). A cada renovação a Selectwin abre um novo ciclo (cycle) e tenta gerar a cobrança correspondente.

Este endpoint é uma leitura síncrona e não destrutiva: não cria ciclos, não dispara cobranças e não altera estado. Ele apenas devolve o retrato atual do objeto no momento da consulta.

Pontos-chave do que você recebe:

• status — o estado atual da assinatura no ciclo de vida (active, pending, trialing, paused, pastdue, unpaid, canceled). É o campo que governa se a recorrência continua cobrando.
• currentCycle — o ciclo de cobrança vigente (número sequencial em cycle, janela startDate/endDate, vencimento dueDate e quando foi faturado em billedAt). É o "período atual" da assinatura.
• items — versão completa das linhas da assinatura, com name, unitPrice (centavos), pricingSchema, currency e images. Mais rico do que a projeção que aparece na listagem.
• _links — links HATEOAS para as próximas ações possíveis a partir deste objeto (ler novamente, criar outra, cancelar, listar).

Quando usar

• Para exibir o status de uma assinatura ao cliente (área "Minha assinatura", painel de suporte).
• Para confirmar o estado real antes de uma ação (ex.: verificar status e currentCycle antes de cancelar ou renovar um ciclo).
• Para reconciliar seu sistema com a Selectwin após receber um evento de webhook (o evento traz o id; você lê o objeto completo).

Quando não usar:

• Para monitorar mudanças de estado, não fique consultando este endpoint em laço (polling). Receba os eventos por webhook — veja Proibição de polling.
• Para buscar várias assinaturas (por cliente, status ou período), use Listar assinaturas.
• Para detalhar um ciclo específico ou os itens isoladamente, use Ciclos e Itens.

Requisição

Headers

Por ser uma leitura, não envie corpo nem Content-Type, e não há necessidade de X-Idempotency-Key (idempotência se aplica a escritas — veja Idempotência).

Parâmetros de caminho

Este endpoint não aceita parâmetros de query.

Exemplo curl

curl -X GET "https://api.selectwin.io/v1/subscriptions/subs_01hqzvabc" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Resposta

200 OK — o corpo é o objeto completo da assinatura.

{
  "id": "subs_01hqzvabc",
  "status": "active",
  "currency": "BRL",
  "method": "credit",
  "type": "prepaid",
  "currentCycle": {
    "id": "cyc_01hqzvabc",
    "cycle": 3,
    "status": "billed",
    "startDate": "2026-04-01T00:00:00.000Z",
    "endDate": "2026-04-30T23:59:59.000Z",
    "dueDate": "2026-04-01T00:00:00.000Z",
    "billedAt": "2026-04-01T10:15:00.000Z",
    "updatedAt": "2026-04-12T17:56:33.000Z",
    "createdAt": "2026-04-01T00:00:00.000Z"
  },
  "customer": {
    "id": "cus_01hqzvabc",
    "firstName": "João",
    "lastName": "Silva",
    "email": "[email protected]",
    "document": { "type": "cpf", "number": "12345678901" },
    "telephone": { "countryCode": "55", "areaCode": "11", "number": "999999999", "line": "5511999999999" },
    "available": true,
    "delinquent": false,
    "externalReference": "CRM-USER-001",
    "additionalEmails": ["[email protected]"],
    "metadata": { "crmId": "lead-42" },
    "updatedAt": "2026-04-12T17:56:33.000Z",
    "createdAt": "2026-04-10T09:15:25.000Z"
  },
  "billing": {
    "frequency": "monthly",
    "frequencyCount": 1,
    "endDate": null,
    "exactDay": null,
    "freeTrialDays": 0,
    "address": {
      "street": "Av. Paulista",
      "number": "1000",
      "complement": "Apt 42",
      "district": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "country": "BR",
      "postcode": "01310-100"
    }
  },
  "discount": { "value": 500, "type": "flat", "percentageOfAmount": null },
  "shippable": false,
  "shipping": null,
  "spplited": true,
  "splits": [
    {
      "id": "split_01hqzvabc",
      "recipient": "bus_9876543210",
      "type": "percentage",
      "value": 10,
      "chargeProcessingFee": false,
      "liable": true,
      "updatedAt": "2026-04-12T17:56:33.000Z",
      "createdAt": "2026-04-12T17:56:33.000Z"
    }
  ],
  "items": [
    {
      "id": "item_01hqzvabc",
      "quantity": 1,
      "unitPrice": 9900,
      "pricingSchema": "unit",
      "name": "Premium Plan",
      "description": "Plano Premium mensal",
      "enabled": true,
      "currency": "BRL",
      "metadata": null,
      "images": ["https://cdn.example.com/product.png"],
      "externalReference": null,
      "updatedAt": "2026-04-12T17:56:33.000Z",
      "createdAt": "2026-04-12T17:56:33.000Z"
    }
  ],
  "callback": { "webhookUrl": "https://example.com/webhook", "active": true },
  "geolocation": null,
  "externalReference": "SUB-1001",
  "metadata": { "campaign": "launch" },
  "updatedAt": "2026-04-12T17:56:33.000Z",
  "createdAt": "2026-04-12T17:56:33.000Z",
  "merchant": { "name": "Seller Name", "merchantId": "bus_1234567890", "isSubAccount": false },
  "_links": {
    "self": { "href": "https://api.selectwin.io/v1/subscriptions/subs_01hqzvabc", "method": "GET", "description": "Read a subscription." },
    "create": { "href": "https://api.selectwin.io/v1/subscriptions", "method": "POST", "description": "Create a new subscription." },
    "cancel": { "href": "https://api.selectwin.io/v1/subscriptions/subs_01hqzvabc", "method": "DELETE", "description": "Cancel the subscription." },
    "list": { "href": "https://api.selectwin.io/v1/subscriptions", "method": "GET", "description": "List all subscriptions." }
  }
}

Campos-chave da resposta

Campos do currentCycle:

Erros

Boas práticas

• Não use polling. Para saber quando o status muda (ciclo pago, cobrança recusada, cancelamento), assine os eventos por webhook e leia o objeto só quando notificado.
• Leia após cada evento relevante para reconciliar: o webhook entrega o id; este endpoint entrega o estado completo e atual.
• Confie em status + currentCycle.status, não em campos derivados, para decidir o que mostrar ao cliente (em dia, em atraso, cancelada).
• Trate o id como opaco e armazene a string inteira; não construa nem deduza IDs.
• Use os _links para descobrir as ações disponíveis (cancelar, listar) em vez de montar URLs à mão — assim seu código acompanha mudanças no contrato.
• Não confunda os items da leitura com os da criação: aqui eles vêm completos (com name, unitPrice, currency); para inspecionar/alterar itens isoladamente use Itens.

Veja também

• Visão geral de Assinaturas — modelo do objeto e ciclo de vida completo.
• Criar assinatura — como abrir uma recorrência (e como a resposta difere desta leitura).
• Listar assinaturas — buscar várias por cliente, status ou período.
• Cancelar assinatura — encerrar a recorrência.
• Ciclos e Itens — detalhar e gerenciar ciclos e linhas.
• Splits — repartição de receita.
• Convenções e Proibição de polling.