Itens da Assinatura

Os itens são as linhas recorrentes de uma assinatura, cada uma referenciando uma variante (var_...). Você pode adicionar, listar, consultar, atualizar (quantidade) e remover itens. Os IDs de item usam o prefixo sit_ (também aceitamos o legado item_).

#Adicionar item

POST /v1/subscriptions/{subscriptionId}/items

curl -X POST "https://api.selectwin.io/v1/subscriptions/subs_01hqzvabc/items" \
  -H "SelectKey: sk_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  -H "Content-Type: application/json" \
  -d '{
    "variantId": "var_abc123",
    "quantity": 1,
    "description": "Add-on de suporte",
    "externalReference": "line-2",
    "metadata": { "sku": "SKU-1" }
  }'

A resposta 201 Created retorna o item criado (não a assinatura inteira).

#Listar itens

GET /v1/subscriptions/{subscriptionId}/items

{
  "offset": 0, "limit": 20, "total": 1, "hasMore": false,
  "page": { "current": 1, "total": 1, "offset": { "first": 0, "prev": null, "next": null, "last": 0 } },
  "data": [
    {
      "id": "sit_01hqzvabc",
      "name": "Premium Plan",
      "description": "Monthly access",
      "enabled": true,
      "pricingSchema": "recurring",
      "unitPrice": 9900,
      "quantity": 1,
      "currency": "BRL",
      "images": null,
      "metadata": null,
      "externalReference": "var-premium",
      "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/items", "method": "GET" } }
}

#Consultar item

GET /v1/subscriptions/{subscriptionId}/items/{itemId} — retorna o objeto do item:

{
  "id": "sit_01hqzvabc",
  "name": "Premium Plan",
  "description": "Monthly access",
  "enabled": true,
  "pricingSchema": "recurring",
  "unitPrice": 9900,
  "quantity": 1,
  "currency": "BRL",
  "images": null,
  "metadata": null,
  "externalReference": "var-premium",
  "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/items/sit_01hqzvabc", "method": "GET" } }
}

#Atualizar item (quantidade)

PATCH /v1/subscriptions/{subscriptionId}/items/{itemId}

A atualização é apenas de quantidade (preço e agenda são snapshots imutáveis da variante). A próxima cobrança já sai com a quantidade nova — e o ajuste proporcional do resto do período em curso entra nela (ver Ajuste proporcional).

curl -X PATCH "https://api.selectwin.io/v1/subscriptions/subs_01hqzvabc/items/sit_01hqzvabc" \
  -H "SelectKey: sk_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  -H "Content-Type: application/json" \
  -d '{ "quantity": 2 }'

Retorna o objeto do item atualizado (200 OK).

#Remover item

DELETE /v1/subscriptions/{subscriptionId}/items/{itemId}

Remove o item indicado. Retorna uma confirmação de remoção:

{ "id": "sit_01hqzvabc", "resource": "item", "deleted": true }

#Ajuste proporcional

A assinatura é cobrada adiantada: cada cobrança paga o período que começa nela. Quando você muda a quantidade, adiciona ou remove um item no meio do período, o período em curso já foi pago na quantidade antiga — então a diferença do resto dele é calculada na hora da mudança e entra na próxima cobrança, junto com o período seguinte já na quantidade nova:

ajuste = (valor da linha na quantidade nova − na antiga) × (tempo que falta do período ÷ duração do período)

• Aumento (mais unidades, item novo ou troca por um plano mais caro): o ajuste é somado à próxima cobrança. Ex.: plano de R$ 10 por unidade, de 2 para 4 unidades no meio do mês → a próxima cobrança é R$ 40 (4 unidades) + R$ 10 (2 unidades × meio período) = R$ 50.
• Redução (menos unidades, item removido ou troca por um plano mais barato): o ajuste é um crédito abatido da próxima cobrança. Um crédito maior que a cobrança zera a cobrança e o que sobra fica para a seguinte — nunca vira dinheiro devolvido, nunca se perde.
• Uma vez só. O ajuste é consumido quando a cobrança que o levou é aprovada. Uma cobrança recusada não consome: a retentativa leva o mesmo ajuste, e a cobrança seguinte à aprovada já não o traz. Duas mudanças simultâneas na mesma quantidade não geram dois ajustes.
• Trocar de plano é adicionar o item novo e remover o antigo: o resultado é a diferença entre os dois, proporcional.
• O cupom recorrente da assinatura não desconta o ajuste — ele corrige um período que já passou.
• Só há ajuste em assinatura active, dentro do período em curso, e em linhas de preço unitário por quantidade (licensed). Em teste (trialing), em atraso (pastdue), não paga, pausada ou em linhas medidas por uso (metered) e escalonadas (tiered/package), a mudança vale a partir da próxima cobrança, sem ajuste.
• O valor que a próxima cobrança vai levar, com o ajuste, aparece em expectedAmount do ciclo em aberto na lista de ciclos.

#Erros