Variantes de produto

As variantes carregam a precificação de um produto. Você as cria, atualiza, lista, consulta e

As variantes carregam a precificação de um produto. Você as cria, atualiza, lista, consulta e remove individualmente. Cada operação atua sobre uma única variante.

Operação	Método	Endpoint	Retorna
Criar	POST	`/v1/products/{productId}/variants`	variante (`201`)
Listar (de um produto)	GET	`/v1/products/{productId}/variants`	lista paginada
Consultar (sob o produto)	GET	`/v1/products/{productId}/variants/{variantId}`	variante
Atualizar	PATCH / PUT	`/v1/products/{productId}/variants/{variantId}`	variante
Excluir (sob o produto)	DELETE	`/v1/products/{productId}/variants/{variantId}`	confirmação
Listar todas (array)	GET	`/v1/products/variants/listall` · `/v1/variants`	array direto
Consultar (por id)	GET	`/v1/variants/{variantId}`	variante
Excluir (por id)	DELETE	`/v1/variants/{variantId}`	confirmação

O id da variante usa o prefixo var_ (ids legados prv_ também são lidos). O pricing segue o modelo dual-axis: pricing.type e pricing.schema são imutáveis após a criação. Escopos: products:variants:{create,read,list,update,delete}.

Criar variante

POST /v1/products/{productId}/variants

Cria uma variante sob o produto (corpo = um único objeto). Veja os campos da variante. Suporta X-Idempotency-Key.

curl -X POST "https://api.selectwin.io/v1/products/prd_01hqzvabc/variants" \
  -H "SelectKey: sk_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Plano Anual",
    "description": "Acesso por 12 meses",
    "sku": "SKU-001",
    "images": ["https://example.com/v.png"],
    "metadata": { "tier": "pro" },
    "externalReference": "VAR-EXT-1",
    "enabled": true,
    "pricing": {
      "unitPrice": 9900,
      "currency": "BRL",
      "schema": "unit",
      "type": "recurring",
      "oldPrice": 14900,
      "costPerItem": 4500,
      "billingType": "prepaid",
      "billingFrequency": "monthly",
      "billingFrequencyCount": 1,
      "billingExactDay": 10,
      "cycles": 12,
      "trialInterval": "day",
      "trialIntervalCount": 7
    }
  }'

Resposta 201 Created (a variante criada):

{
  "id": "var_01hqzvabc",
  "productId": "prd_01hqzvabc",
  "name": "Plano Anual",
  "slug": "plano-anual",
  "description": "Acesso por 12 meses",
  "sku": "SKU-001",
  "primary": false,
  "enabled": true,
  "pricing": {
    "unitPrice": 9900,
    "oldPrice": 14900,
    "costPerItem": 4500,
    "currency": "BRL",
    "schema": "unit",
    "type": "recurring",
    "daysTrial": null,
    "billingType": "prepaid",
    "billingFrequency": "monthly",
    "billingFrequencyCount": 1,
    "billingExactDay": 10,
    "cycles": 12,
    "trialInterval": "day",
    "trialIntervalCount": 7,
    "tiersMode": null,
    "tiers": null,
    "transformQuantity": null,
    "usageType": "licensed",
    "usageAggregation": null,
    "meterEventName": null
  },
  "images": ["https://example.com/v.png"],
  "metadata": { "tier": "pro" },
  "attributes": null,
  "externalReference": "VAR-EXT-1",
  "checkoutUrl": null,
  "createdAt": "2026-04-12T17:56:33.000Z",
  "updatedAt": "2026-04-12T17:56:33.000Z"
}

Atualizar variante

PATCH / PUT /v1/products/{productId}/variants/{variantId}

Patch parcial de uma variante (envie ao menos um campo). pricing.type e pricing.schema não podem ser alterados — qualquer tentativa retorna 422. PUT é um alias de PATCH.

curl -X PATCH "https://api.selectwin.io/v1/products/prd_01hqzvabc/variants/var_01hqzvabc" \
  -H "SelectKey: sk_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mensal Atualizado",
    "pricing": { "unitPrice": 10900 }
  }'

Resposta 200 OK: a variante atualizada (mesmo objeto do 201 acima).

Listar variantes

De um produto — GET /v1/products/{productId}/variants (paginada)

Filtros: id, sku, currency, enabled, daterange*. Paginação: limit default 20, máx. 100; offset default 0.

{
  "offset": 0,
  "limit": 20,
  "total": 1,
  "page": { "offset": { "first": 0, "prev": 0, "next": 0, "last": 0 }, "current": 1, "total": 1 },
  "hasMore": false,
  "data": [
    {
      "id": "var_01hqzvabc",
      "productId": "prd_01hqzvabc",
      "name": "Mensal",
      "slug": "mensal",
      "description": "Monthly billing",
      "sku": "SKU-M",
      "primary": true,
      "enabled": true,
      "pricing": { "unitPrice": 9900, "oldPrice": null, "costPerItem": null, "currency": "BRL", "schema": "unit", "type": "recurring", "billingType": "prepaid", "billingFrequency": "monthly", "billingFrequencyCount": 1 },
      "images": null,
      "metadata": null,
      "attributes": null,
      "externalReference": null,
      "checkoutUrl": null,
      "createdAt": "2026-04-12T17:56:33.000Z",
      "updatedAt": "2026-04-12T17:56:33.000Z"
    }
  ]
}

Todas (array direto) — GET /v1/products/variants/listall ou GET /v1/variants

Ambos retornam um array no nível raiz (sem envelope de paginação) com o objeto completo de cada variante (mesmo shape do item acima, com pricing completo e productId). Filtros aceitos: id, sku, currency, enabled, daterange*; productId (apenas em /v1/products/variants/listall); sort (ascending | descending, default ascending).

[
  {
    "id": "var_01hqzvabc",
    "productId": "prd_01hqzvabc",
    "name": "Mensal",
    "slug": "mensal",
    "description": "Monthly billing",
    "sku": "SKU-M",
    "primary": true,
    "enabled": true,
    "pricing": { "unitPrice": 9900, "oldPrice": null, "costPerItem": null, "currency": "BRL", "schema": "unit", "type": "recurring", "billingType": "prepaid", "billingFrequency": "monthly", "billingFrequencyCount": 1 },
    "images": null,
    "metadata": null,
    "attributes": null,
    "externalReference": null,
    "checkoutUrl": null,
    "createdAt": "2026-04-12T17:56:33.000Z",
    "updatedAt": "2026-04-12T17:56:33.000Z"
  }
]

Consultar variante

GET /v1/products/{productId}/variants/{variantId} ou GET /v1/variants/{variantId}

Ambos retornam o objeto completo da variante (incluindo pricing.costPerItem):

{
  "id": "var_01hqzvabc",
  "productId": "prd_01hqzvabc",
  "name": "Mensal",
  "slug": "mensal",
  "description": "Monthly billing",
  "sku": "SKU-M",
  "primary": true,
  "enabled": true,
  "pricing": {
    "unitPrice": 9900,
    "oldPrice": null,
    "costPerItem": 5000,
    "currency": "BRL",
    "schema": "unit",
    "type": "recurring",
    "billingType": "prepaid",
    "billingFrequency": "monthly",
    "billingFrequencyCount": 1
  },
  "images": null,
  "metadata": null,
  "attributes": null,
  "externalReference": null,
  "checkoutUrl": null,
  "createdAt": "2026-04-12T17:56:33.000Z",
  "updatedAt": "2026-04-12T17:56:33.000Z"
}

Excluir variante

DELETE /v1/products/{productId}/variants/{variantId} ou DELETE /v1/variants/{variantId}

{ "id": "var_01hqzvabc", "resource": "variant", "deleted": true }

Erros

`error.code`	HTTP	Quando
`variantNotFound`	404	Variante não encontrada para esta conta
`productNotFound`	404	Produto-pai inexistente (rotas aninhadas / criação)
`invalidParameters`	400	`productId`/`variantId` inválido ou corpo de atualização vazio
`invalidPricing`	422	Configuração de `pricing` inconsistente com o `schema`/recorrência
`pricingTypeImmutable`	422	Tentou alterar `pricing.type`
`pricingSchemaImmutable`	422	Tentou alterar `pricing.schema`
`variantNotRecurring`	422	Variante `oneTime` usada em uma assinatura

Catálogo completo: Códigos de Erro.

Variantes de produto

On this page