Ciclos de cobrança

Cada assinatura é cobrada em ciclos. Um ciclo representa um período de cobrança (ex.: um mês), com

Cada assinatura é cobrada em ciclos. Um ciclo representa um período de cobrança (ex.: um mês), com sua data de vencimento (dueDate) e status próprio. A Selectwin gera e cobra os ciclos automaticamente. Os IDs de ciclo usam o prefixo scy_ (também aceitamos o legado cycle_).

Operação	Método	Endpoint	Sucesso
Listar ciclos	GET	`/v1/subscriptions/{subscriptionId}/cycles`	200
Consultar ciclo	GET	`/v1/subscriptions/{subscriptionId}/cycles/{cycleId}`	200
Reagendar ciclo	POST	`/v1/subscriptions/{subscriptionId}/cycles`	201

Status de ciclo

scheduled (agendado), processing (em cobrança), paid (pago), failed (falhou), canceled (cancelado).

Listar ciclos

GET /v1/subscriptions/{subscriptionId}/cycles

Aceita paginação (limit 1–100, padrão 20; offset), filtro de período (daterange, daterangegt, daterangegte, daterangelt, daterangelte) e status (um dos status de ciclo acima).

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

Resposta 200 OK (paginada):

{
  "offset": 0, "limit": 20, "total": 3, "hasMore": false,
  "page": { "current": 1, "total": 1, "offset": { "first": 0, "prev": null, "next": null, "last": 0 } },
  "data": [
    {
      "id": "scy_01hqzvabc",
      "cycle": 1,
      "status": "paid",
      "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-01T00:00:00.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 do ciclo: id, cycle (número sequencial), status, startDate, endDate, dueDate, billedAt (data da cobrança ou null), updatedAt, createdAt.

Consultar ciclo

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

{
  "id": "scy_01hqzvabc",
  "cycle": 1,
  "status": "paid",
  "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-01T00:00:00.000Z",
  "merchant": { "name": "Seller Name", "merchantId": "bus_1234567890", "isSubAccount": false },
  "_links": { "self": { "href": "https://api.selectwin.io/v1/subscriptions/subs_01hqzvabc/cycles/scy_01hqzvabc", "method": "GET" } }
}

Reagendar ciclo

POST /v1/subscriptions/{subscriptionId}/cycles

⚠️ Esta operação reagenda — não cobra. Ela cancela o ciclo scheduled atual e cria um novo ciclo com vencimento adiantado em um período. Não executa cobrança nem cria uma transação imediatamente; a cobrança acontece quando o novo ciclo vencer. Use-a para deslocar a data de cobrança. Não exige corpo.

curl -X POST "https://api.selectwin.io/v1/subscriptions/subs_01hqzvabc/cycles" \
  -H "SelectKey: sk_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Resposta 201 Created (o ciclo recém-agendado):

{
  "id": "scy_02hqzvdef",
  "cycle": 2,
  "status": "scheduled",
  "startDate": "2026-05-01T00:00:00.000Z",
  "endDate": "2026-06-01T00:00:00.000Z",
  "dueDate": "2026-05-01T00:00:00.000Z",
  "billedAt": null,
  "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/scy_02hqzvdef", "method": "GET" } }
}

Erros

`error.code`	HTTP
`subscriptionNotFound`	404
`cycleNotFound`	404