Ciclos de cobrança

Cada assinatura é cobrada em ciclos: períodos de cobrança recorrentes (por exemplo, um mês) com data de início, fim, vencimento e status próprios. A Selectwin gera e cobra os ciclos automaticamente; estes endpoints permitem listar o histórico de ciclos, consultar um ciclo específico e disparar a renovação do ciclo de uma assinatura.

Autenticação por header SelectKey em todas as chamadas; base URL https://api.selectwin.io/v1. Dinheiro em centavos (inteiro) e datas em ISO 8601 UTC. Veja Convenções.

Como funciona

Um ciclo (objeto com prefixo cyc_) é a unidade de faturamento de uma assinatura. Quando você cria uma assinatura, a Selectwin gera o primeiro ciclo; ao final de cada período, gera o próximo, seguindo a frequência do plano (billing.frequency / billing.frequencyCount). Cada ciclo carrega:

• um número sequencial (cycle: 1, 2, 3, …);
• uma janela de vigência (startDate → endDate);
• a data de vencimento da cobrança (dueDate);
• um status que evolui conforme a cobrança é gerada e paga.

O objeto currentCycle, retornado em Consultar assinatura, reflete sempre o ciclo vigente. Cada mudança de status do ciclo dispara um webhook de assinatura — não fique consultando estes endpoints em laço; veja Proibição de polling.

Valores de status do ciclo

O campo status descreve em que ponto da cobrança o ciclo está. No contrato ele é tipado apenas como string (sem enum fixo). Os valores que aparecem nos exemplos do contrato são:

O fluxo típico (inferido a partir dos exemplos) é: a cobrança é emitida (billed), depois confirmada (paid); um ciclo pode terminar como canceled se a assinatura for cancelada.

Trate os IDs (cyc_…, subs_…) como opacos: armazene a string inteira e não faça parsing do prefixo.

Listar ciclos

GET /v1/subscriptions/{subscriptionId}/cycles

Retorna o histórico paginado de ciclos da assinatura — útil para montar uma timeline de faturas/renovações ou conciliar cobranças. A lista traz uma projeção leve de cada ciclo (sem amount); para o detalhe completo, use Consultar ciclo.

Quando usar

• Exibir o histórico de cobranças de uma assinatura ao cliente ou no painel.
• Conciliar quantos ciclos já foram gerados/pagos.
• Não use em laço para "esperar" um pagamento — reaja ao webhook correspondente.

Requisição

Headers

Parâmetros de caminho

Parâmetros de query

Veja Paginação para o padrão offset/limit/hasMore.

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

Resposta

200 OK — envelope paginado com os ciclos em data:

{
  "offset": 0,
  "limit": 20,
  "total": 3,
  "hasMore": false,
  "page": {
    "current": 1,
    "total": 1,
    "offset": { "first": 0, "prev": null, "next": null, "last": 0 }
  },
  "data": [
    {
      "id": "cyc_01hqzvabc",
      "status": "paid",
      "cycle": 1,
      "startDate": "2026-04-01T00:00:00.000Z",
      "endDate": "2026-05-01T00:00:00.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-12T17:56:33.000Z"
    }
  ],
  "merchant": { "name": "Seller Name", "merchantId": "bus_1234567890", "isSubAccount": false },
  "_links": {
    "self": { "href": "https://api.selectwin.io/v1/subscriptions/subs_01hqzvabc/cycles", "method": "GET" }
  }
}

Campos de cada item em data[]:

O item de lista não inclui amount. Para obter o valor do ciclo, consulte o ciclo individualmente.

Consultar ciclo

GET /v1/subscriptions/{subscriptionId}/cycles/{cycleId}

Retorna o detalhe de um único ciclo.

Requisição

Parâmetros de caminho

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

Resposta

200 OK:

{
  "id": "cyc_01hqzvabc",
  "cycle": 1,
  "status": "billed",
  "startDate": "2026-04-01T00:00:00.000Z",
  "endDate": "2026-05-01T00:00:00.000Z",
  "dueDate": "2026-05-01T00:00:00.000Z",
  "billedAt": "2026-04-01T10:15:00.000Z",
  "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/cycles/cyc_01hqzvabc", "method": "GET", "description": "Read a cycle." },
    "list": { "href": "https://api.selectwin.io/v1/subscriptions/subs_01hqzvabc/cycles", "method": "GET", "description": "List cycles of a subscription." },
    "create": { "href": "https://api.selectwin.io/v1/subscriptions/subs_01hqzvabc/cycles", "method": "POST", "description": "Renew cycle of subscription." }
  }
}

Campos da resposta:

Renovar ciclo

POST /v1/subscriptions/{subscriptionId}/cycles

Dispara a renovação do ciclo da assinatura. A operação não recebe corpo: o servidor avança o ciclo de cobrança da assinatura conforme a regra de negócio do plano e retorna o ciclo resultante.

Quando usar (e quando não)

• Use para forçar o avanço/renovação do ciclo de uma assinatura quando seu fluxo de negócio exigir antecipar a próxima cobrança.
• Não use para cobrar um valor pontual fora da assinatura — para isso, crie uma transação avulsa.
• Não use em laço para "garantir" pagamento; reaja aos webhooks de assinatura.

Requisição

Headers

Parâmetros de caminho

Esta operação não tem corpo de requisição nem parâmetros de query.

curl -X POST "https://api.selectwin.io/v1/subscriptions/subs_01hqzvabc/cycles" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  -H "X-Idempotency-Key: 8f1c2e7a-1b9d-4a3e-9c6f-2b7a1d0e5c44"

Resposta

200 OK — o ciclo resultante:

{
  "id": "cyc_01hqzvabc",
  "subscriptionId": "subs_01hqzvabc",
  "status": "paid",
  "amount": 9900,
  "dueDate": "2026-04-01T00:00:00.000Z",
  "paidAt": "2026-04-01T10:15:00.000Z",
  "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/cycles/cyc_01hqzvabc", "method": "GET" }
  }
}

Campos da resposta:

Note a diferença de projeção: a renovação e a consulta individual retornam amount; o item de lista não retorna amount.

Erros

Trate sempre pelo error.code (estável), nunca pela message. Veja Tratamento de Erros e o Catálogo de Códigos de Erro.

O 402 insufficientFundsError aplica-se à renovação (POST), que envolve cobrança; já GET (listar/consultar) não retorna 402.

Boas práticas

• Use X-Idempotency-Key no POST para que retries de rede não disparem renovações duplicadas.
• Reaja a webhooks, não a polling: acompanhe a mudança de status do ciclo (billed → paid) pelos eventos de assinatura em vez de reconsultar em laço.
• Mostre amount da consulta/renovação, não da lista — o item paginado omite amount de propósito.
• Trate paidAt/billedAt como possivelmente ausentes enquanto o ciclo ainda não foi cobrado ou pago.
• Pagine o histórico com limit/offset e ordene com sort=descending para mostrar o ciclo mais recente primeiro.
• Converta dinheiro e datas só na exibição: guarde centavos e ISO 8601 UTC internamente.
• Não confunda renovar ciclo com cobrança avulsa: para um pagamento fora do plano, use uma transação.

Veja também

• Visão geral de Assinaturas — modelo do objeto, status e ciclo de vida.
• Consultar assinatura — onde aparece o currentCycle.
• Listar assinaturas · Criar assinatura · Cancelar assinatura
• Itens da assinatura · Splits da assinatura
• Paginação · Idempotência · Proibição de polling · Convenções