Itens da assinatura

Os itens são as linhas recorrentes de uma assinatura, cada uma referenciando uma variante (var...).

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_).

Operação	Método	Endpoint	Retorna
Adicionar	POST	`/v1/subscriptions/{id}/items`	item criado (`201`)
Listar	GET	`/v1/subscriptions/{id}/items`	lista paginada de itens
Consultar	GET	`/v1/subscriptions/{id}/items/{itemId}`	item
Atualizar	PATCH	`/v1/subscriptions/{id}/items/{itemId}`	item
Remover	DELETE	`/v1/subscriptions/{id}/items/{itemId}`	confirmação de remoção

O preço vem da variante (modelo Selectwin-strict). Você controla quantity (e anotações); o unitPrice/currency/pricingSchema são um snapshot da variante e são imutáveis. A variante precisa ser recorrente. Uma assinatura deve manter pelo menos um 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" }
  }'

Campo	Tipo	Obrigatório	Descrição
`variantId`	string	Sim	ID da variante recorrente (`var_...`; aceita `prv_...` legado)
`quantity`	integer	Não	Quantidade (1–999999, default `1`)
`description`	string	Não	Anotação (máx. 2048)
`externalReference`	string	Não	Sua referência
`metadata`	object	Não	Pares chave-valor

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 mudança vale a partir do próximo ciclo.

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 }'

Campo	Tipo	Obrigatório	Descrição
`quantity`	integer	Sim	Nova quantidade (1–999999)

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 }

Uma assinatura deve manter pelo menos um item — remover o último retorna 422 subscriptionRequiresItem.

Erros

`error.code`	HTTP	Quando
`subscriptionNotFound`	404	Assinatura inexistente
`itemNotFound`	404	Item inexistente
`variantNotFound`	404	Variante inexistente (ao adicionar)
`variantNotRecurring`	422	Variante não recorrente (ao adicionar)
`subscriptionRequiresItem`	422	Tentativa de remover o último item
`subscriptionNotModifiable`	422	A assinatura está cancelada