Atualizar um produto

Atualize os dados de um produto existente — nome, descrição, categoria, status (enabled), garantia, página de vendas e demais campos do "cabeçalho" do produto — enviando uma requisição PUT ou PATCH com o id do produto na URL. Use quando precisar corrigir informações de catálogo ou ativar/desativar a venda de um produto.

PUT /v1/products/{productId} · PATCH /v1/products/{productId}

Como funciona

A Selectwin expõe dois verbos para a mesma operação, ambos atendidos pelo mesmo handler:

• PATCH — atualização parcial: envie só os campos que quer mudar; o resto permanece como está.
• PUT — substituição da representação do produto: você descreve o estado desejado dos campos editáveis.

Na prática, como os dois compartilham o handler, enviar apenas os campos que deseja alterar funciona em ambos. Por clareza semântica, prefira PATCH para ajustes pontuais (ex.: trocar a categoria) e reserve PUT para quando estiver reescrevendo o conjunto dos dados do produto.

O que o servidor faz

1. Valida o productId da URL (formato e existência).
2. Valida os campos enviados no corpo (tipos, enums e faixas — ex.: warrantyDays entre 7 e 3650).
3. Aplica as mudanças e atualiza updatedAt.
4. Retorna 200 OK com a representação atualizada do produto (incluindo a lista de variantes, somente leitura).

A operação é síncrona: ao receber 200, a mudança já está persistida. Não há etapa assíncrona nem evento de webhook obrigatório para concluir a edição.

Quando usar (e quando não usar)

Requisição

Headers

Parâmetros de caminho

Corpo

Todos os campos abaixo são opcionais na atualização — envie apenas os que deseja alterar. Valores monetários não se aplicam aqui (são propriedade das variantes).

Exemplo PATCH (ajuste pontual)

Trocar apenas a categoria e pausar a venda:

curl -X PATCH "https://api.selectwin.io/v1/products/prd_01hqzvabc" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "courses",
    "enabled": false
  }'

Exemplo PUT (vários campos)

curl -X PUT "https://api.selectwin.io/v1/products/prd_01hqzvabc" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Premium Course",
    "slug": "premium-course",
    "description": "Curso completo (2026)",
    "enabled": true,
    "type": "digital",
    "language": "pt",
    "category": "courses",
    "warrantyDays": 30,
    "salesPage": "https://loja.com/premium",
    "externalReference": "SKU-EXT-1"
  }'

Resposta

200 OK com a representação atualizada do produto.

{
  "id": "prd_01hqzvabc",
  "enabled": true,
  "name": "Plano Premium",
  "type": "digital",
  "language": "pt-BR",
  "category": "saas",
  "slug": "plano-premium",
  "images": ["https://cdn.selectwin.io/p/img1.png"],
  "warrantyDays": 30,
  "variants": [
    {
      "id": "var_01hqzvabc",
      "name": "Mensal",
      "enabled": true,
      "description": "Monthly billing",
      "sku": "SKU-M",
      "pricing": {
        "oldPrice": 14900,
        "unitPrice": 9900,
        "currency": "BRL",
        "schema": "unit",
        "type": "recurring",
        "billingType": "prepaid",
        "billingFrequency": "monthly",
        "billingFrequencyCount": 1,
        "cycles": 12
      },
      "updatedAt": "2026-04-12T17:56:33.000Z",
      "createdAt": "2026-04-12T17:56:33.000Z"
    }
  ],
  "updatedAt": "2026-04-12T17:56:33.000Z",
  "createdAt": "2026-04-12T17:56:33.000Z"
}

Campos-chave da resposta:

Erros

Trate sempre pelo error.code (estável), não pela message. Veja o Catálogo de Códigos de Erro e Tratamento de Erros.

Tentar alterar preço/variante por aqui não funciona: os campos variants[] não são editáveis neste endpoint. Use Variantes, onde pricing.type e pricing.schema são imutáveis após a criação (pricingTypeImmutable / pricingSchemaImmutable, 422).

Excluir um produto

Para remover um produto do catálogo, use o endpoint dedicado:

DELETE /v1/products/{productId}

curl -X DELETE "https://api.selectwin.io/v1/products/prd_01hqzvabc" \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Resposta 200 OK:

{
  "id": "prd_01hqzvabc",
  "resource": "product",
  "deleted": true
}

Boas práticas

• Prefira PATCH para ajustes pontuais. Envie só os campos que mudam; isso reduz o risco de sobrescrever algo sem querer.
• Use X-Idempotency-Key em toda atualização. Em retries por timeout, evita aplicar a mesma mudança duas vezes. Veja Idempotência.
• Não use este endpoint para preço. Preço, trial e frequência vivem nas Variantes; alterá-los aqui não tem efeito.
• Desative em vez de excluir quando quiser apenas tirar o produto de venda preservando histórico: PATCH com enabled: false.
• Após editar, recarregue com GET se precisar de description/externalReference, pois a resposta do update os omite.
• Respeite as faixas do contrato. warrantyDays deve ficar entre 7 e 3650; valores fora disso retornam invalidParameters (400).
• Trate erros pelo error.code, com fallback por error.statusCode (429/5xx → backoff).

Veja também

• Visão geral de Produtos — modelo do objeto e ciclo de vida.
• Criar produto — criação com variantes no mesmo payload.
• Consultar produto — objeto completo (inclui description e externalReference).
• Listar produtos — busca e filtros do catálogo.
• Variantes — editar preço, SKU, trial e frequência de cobrança.
• Convenções · Idempotência · Códigos de Erro