Ciclos da Assinatura
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",
"amount": 19700,
"transactionId": "tra_01hqzvxyz",
"method": "credit",
"expectedAmount": null,
"attempts": 1,
"nextAttemptAt": null,
"failure": null
}
],
"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, e:
| Campo | Tipo | O que é |
|---|---|---|
amount | inteiro (centavos) | null |
transactionId | string | null |
method | credit | pix |
expectedAmount | inteiro (centavos) | null |
attempts | inteiro | Tentativas de cobrança já feitas neste ciclo (no máximo o teto da régua de inadimplência da loja — 5 por padrão) |
nextAttemptAt | datetime | null |
failure | objeto | null |
failure:
{ "stage": "charge", "code": "insufficientFundsError", "message": "Saldo ou limite insuficiente para realizar esta compra. Verifique o limite disponível ou use outro cartão.", "at": "2026-08-17T10:00:00.000Z" }stage: "beforeCharge"— a cobrança nem chegou a ser feita.code:noCard(sem cartão),noBillingAddress(boleto sem endereço),unpriceableItems(item sem preço),internalError, ou o código da recusa da cobrança (o mesmo vocabulário de erros da criação de transação).messageénull.stage: "charge"— a cobrança foi recusada.codeemessagesão ocodee odisplayMessage(pt-BR) depayment.refusedda transação ligada — ver Recusas de Pagamento.
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
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 |
Atualizado em 17 de outubro de 2026