Visão geral

O recurso de Assinaturas (Subscriptions) orquestra cobranças recorrentes de ponta a ponta: ele agrupa um cliente, um ou mais itens recorrentes e um método de pagamento, e a Selectwin gera e cobra automaticamente cada ciclo de faturamento, emitindo webhooks a cada mudança de estado. Use-o para planos mensais/anuais, períodos de teste (trial), assinaturas com vários itens (add-ons, upsells) e divisão de receita (splits).

O que é uma assinatura

Pense em uma assinatura como um contrato de cobrança que se repete. Você a cria uma vez; a partir daí a Selectwin:

• gera um ciclo (cyc_...) a cada período de faturamento (mensal, anual, etc.);
• cobra cada ciclo gerando uma transação (tra_...) — visível em currentCharge na criação;
• avança o status da assinatura conforme o pagamento é aprovado, falha ou esgota retentativas;
• dispara webhooks a cada transição, para você reagir sem fazer polling.

Você controla o catálogo (variantes), as quantidades, os splits e os metadados; a Selectwin controla o relógio de cobrança.

Modelo do objeto

O exemplo abaixo é a forma completa retornada por Consultar (GET /v1/subscriptions/{id}). A criação (Create) devolve um corpo parecido, acrescido de currentCharge (a transação da 1ª cobrança); a Listagem devolve uma projeção mais leve de cada assinatura (sem customer/billing.address completos).

{
  "id": "subs_01hqzvabc",                       // ID opaco da assinatura (prefixo subs_)
  "status": "active",                           // estado atual (ver Ciclo de vida)
  "currency": "BRL",                            // ISO 4217 — atualmente apenas BRL
  "method": "credit",                           // método de cobrança: credit | billet | pix
  "type": "prepaid",                            // modelo de faturamento da assinatura
  "currentCycle": {                             // ciclo de cobrança vigente
    "id": "cyc_01hqzvabc",
    "cycle": 3,                                 // número sequencial do ciclo (1, 2, 3, …)
    "status": "billed",                         // estado do ciclo
    "startDate": "2026-04-01T00:00:00.000Z",
    "endDate": "2026-04-30T23:59:59.000Z",
    "dueDate": "2026-04-01T00:00:00.000Z",      // vencimento da cobrança do ciclo
    "billedAt": "2026-04-01T10:15:00.000Z",     // quando o ciclo foi cobrado (null se ainda não)
    "updatedAt": "2026-04-12T17:56:33.000Z",
    "createdAt": "2026-04-01T00:00:00.000Z"
  },
  "customer": {                                 // cliente associado
    "id": "cus_01hqzvabc",
    "firstName": "João",
    "lastName": "Silva",
    "email": "[email protected]",
    "document": { "type": "cpf", "number": "12345678901" },
    "delinquent": false,                        // true se o cliente tem cobrança em aberto
    "externalReference": "CRM-USER-001"
  },
  "billing": {                                  // agenda + endereço de cobrança
    "frequency": "monthly",                     // periodicidade (deriva da variante)
    "frequencyCount": 1,                        // a cada N períodos
    "endDate": null,                            // data de término (null = sem fim)
    "exactDay": null,                           // dia fixo de cobrança, se configurado
    "freeTrialDays": 0,                         // dias de trial antes da 1ª cobrança
    "address": { "street": "Av. Paulista", "number": "1000", "city": "São Paulo", "state": "SP", "country": "BR", "postcode": "01310-100" }
  },
  "discount": {                                 // desconto aplicado (cupom ou avulso)
    "value": 500,                               // 500 = R$ 5,00 quando type=flat
    "type": "flat",                             // "flat" (centavos) ou "percentage"
    "percentageOfAmount": null
  },
  "shippable": false,
  "shipping": null,
  "spplited": true,                             // true se há divisão de receita (splits)
  "splits": [                                   // regras de repasse (ver Splits)
    { "id": "split_01hqzvabc", "recipient": "bus_9876543210", "type": "percentage", "value": 10, "chargeProcessingFee": false, "liable": true }
  ],
  "items": [                                    // itens recorrentes da assinatura
    {
      "id": "item_01hqzvabc",                   // ID da linha (item_), não da variante
      "quantity": 1,
      "unitPrice": 9900,                        // preço unitário em centavos (R$ 99,00)
      "pricingSchema": "unit",
      "name": "Premium Plan",
      "enabled": true,
      "currency": "BRL"
    }
  ],
  "callback": { "webhookUrl": "https://example.com/webhook", "active": true },
  "externalReference": "SUB-1001",              // sua referência externa
  "metadata": { "campaign": "launch" },         // pares chave/valor (até 40 chaves)
  "updatedAt": "2026-04-12T17:56:33.000Z",
  "createdAt": "2026-04-12T17:56:33.000Z",
  "merchant": { "name": "Seller Name", "merchantId": "bus_1234567890", "isSubAccount": false },
  "_links": { }                                 // links HATEOAS para próximas ações
}

Campos principais

Campos de currentCycle

Ciclo de vida

O status da assinatura é o que você acompanha para saber se a receita está fluindo. Os valores possíveis (também aceitos como filtro status em Listar) são:

Operações disponíveis

Base URL: https://api.selectwin.io/v1. Todas as chamadas autenticam pelo header SelectKey (nunca Authorization: Bearer/Basic) — veja Autenticação.

Remover item e remover split usam query string (?itemId=... / ?splitId=...), não o ID no caminho. Veja as páginas respectivas.

Exemplo: consultar uma assinatura

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

Em sandbox, a chave começa com sl_test_. Em requisições com corpo (criar, adicionar item, etc.), envie também Content-Type: application/json.

Conceitos e relações

• Variantes recorrentes (var_...) — definem preço, moeda e agenda de cobrança. Os itens da assinatura referenciam variantes; é o catálogo de Produtos & Variantes que governa o valor cobrado.
• Ciclos (cyc_...) — cada período de faturamento. A assinatura sempre expõe o currentCycle; o histórico está em Ciclos.
• Transações (tra_...) — cada ciclo cobrado gera uma transação. Na criação, ela aparece em currentCharge.
• Clientes (cus_...) — toda assinatura pertence a um cliente. Você pode informar customer.id (existente) ou os dados completos para criação implícita.
• Cupons / descontos (dis_...) — aplicáveis via discount (por id de cupom existente ou desconto avulso flat/percentage).
• Splits (split_...) — dividem a receita de cada cobrança entre destinatários, por percentage (0–100) ou flat (centavos). Veja Splits.
• Webhooks — a forma recomendada de acompanhar mudanças. Configure callback.webhookUrl na assinatura ou endpoints globais; o catálogo de eventos e a verificação de assinatura estão em Webhook Events.

Tratamento de erros

Trate sempre pelo error.code (estável), nunca pela message. Além dos transversais — 401 (unauthorized), 403 (forbidden), 422 (unprocessableEntity), 429 (tooManyRequests), 500 (serverError) —, a criação de assinaturas tem códigos próprios do modelo orientado a catálogo:

O catálogo completo (incluindo os transversais e o envelope de erro) está em Códigos de Erro.

Boas práticas

1. Modele o preço no catálogo, não na assinatura. Crie variantes recorrentes e referencie-as nos items; assim você reaproveita preço/agenda e evita os erros *NotAllowedInSubscription.
2. Garanta agendas consistentes. Todos os itens de uma mesma assinatura devem ter a mesma periodicidade — variantes divergentes geram variantScheduleDivergent.
3. Use idempotência ao criar. Envie X-Idempotency-Key no POST para não duplicar assinaturas em caso de retry de rede. Veja Idempotência.
4. Reaja a webhooks, não faça polling das transições de status e renovações de ciclo. Veja Proibição de Polling.
5. Trate pastdue/unpaid ativamente. Notifique o cliente para atualizar o método de pagamento antes que as retentativas se esgotem e a assinatura caia para unpaid/canceled.
6. Correlacione com seu sistema via externalReference e metadata (até 40 chaves) — facilita reconciliação e suporte sem depender do subs_id.
7. Some os splits com cuidado. Acompanhe remainingPercentage/remainingAmount retornados ao adicionar splits para não ultrapassar 100% da receita. Veja Splits.

Veja também

• Criar Assinatura — corpo completo, regras do catálogo e exemplos.
• Listar · Consultar · Cancelar
• Ciclos · Itens · Splits
• Convenções · Autenticação · Códigos de Erro
• Idempotência · Paginação · Proibição de Polling
• Webhook Events — catálogo de eventos e verificação de assinatura.