Alterar produto

Atualiza um produto existente enviando só os campos que mudam, como preço, estoque, status, categorias, descrições e dados de envio.

Use esta operação para manter o cadastro em dia: o ERP que atualiza preço e estoque, o PIM que corrige descrições, a regra que desativa um item descontinuado, ou o passo que publica um produto que estava aguardando aprovação. A alteração é parcial: você envia apenas as chaves que quer mudar e todo o resto fica como está. Enviar o produto inteiro também funciona, e é o que o painel faz.

Cada alteração relevante (preço, estoque, nome, status, SKU...) é registrada no histórico de alterações com o usuário e o horário. Mudar o estoque pelo campo de quantidade grava um movimento no extrato de estoque. Para ajustar só preço em muitos produtos, ou só estoque, veja o lote.

PUT/api/v1/admin/products/{id}Admin

Atualiza um produto

Autenticação: Authorization: Bearer <token> de um usuário administrador com o privilégio manage_catalog. A resposta é o produto completo já atualizado.

Path parameters

iduuidobrigatório

UUID do produto. SKU, display_id e UUID cortado são recusados com 400.

Corpo da requisição

namestring

Novo nome, até 255 caracteres. Vazio é recusado.

descriptionstring

Nova descrição completa, em HTML.

short_descriptionstring

Nova descrição curta.

highlight_textstring

Linha curta sob o nome do produto na página.

descriptionsobject

Texto por idioma. A chave é o código do idioma (pt-BR, en) e o valor aceita name, description, short_description, promo_text, highlight_text, seo_title, seo_description e meta_keywords. Cada idioma enviado é regravado por inteiro; os não enviados ficam intactos.

skustring

Novo SKU. Único na loja (409 se repetido). "" apaga o código.

barcodestring

EAN/GTIN.

ncm_codestring

Código NCM, 8 dígitos.

vendor_internal_skustring

Código interno do seller. Sempre editável, mesmo em oferta ligada a um mestre.

slugstring

Novo slug. Se já existir, a plataforma acrescenta -2, -3...

vendor_iduuid

Move o produto para outro seller.

category_iduuid

Nova categoria principal. Atenção: o produto continua vinculado à categoria anterior, que passa a ser adicional. Para tirá-lo dela, troque o conjunto inteiro por Categorias do produto.

additional_category_idsarray

Categorias adicionais. Para trocar todas as categorias de uma vez, veja Categorias do produto.

priceinteger

Novo preço de venda em centavos. Zero é permitido; negativo é recusado.

list_priceinteger

Preço "de" em centavos. Três estados: ausente não mexe, null ou "" apaga, número grava. Se maior que zero, não pode ser menor que o preço.

cost_priceinteger

Custo em centavos. Mesmos três estados de list_price; zero é um custo válido.

shipping_freightinteger

Frete fixo do produto, em centavos.

quantitynumber

Novo estoque absoluto (não é um acréscimo). Registra um movimento no extrato de estoque. Não envie valores negativos.

stock_adjust_reasonstring

Motivo do ajuste, gravado no extrato de estoque. Só vale junto de quantity.

low_stock_alertinteger

Limite de estoque baixo. Não pode ser negativo.

min_quantitynumber

Quantidade mínima por compra.

max_quantitynumber

Quantidade máxima por compra (0 = sem máximo).

quantity_stepnumber

Múltiplo de compra.

sale_unitstring

Unidade de venda: un, kg, cx, l, par ou texto livre.

sale_unit_labelstring

Rótulo da unidade de venda.

allow_fractionalboolean

Aceita compra fracionada.

out_of_stock_actionstring

NBS

Sem estoque: N esconde o botão, B aceita encomenda, S mostra o formulário "avise-me".

zero_price_actionstring

PRA

Preço zero: P vende, R bloqueia a compra online, A pede orçamento.

avail_sincestring

Data de lançamento, RFC 3339.

usergroup_idsarray

Grupos de clientes que enxergam o produto. Ausente não mexe; lista vazia limpa (visível para todos).

statusstring

ADHRXactivedisabledhiddenpendingrejected

Novo status, pela letra ou pelo nome. A, D e H também atualizam o intended_status. R e X pertencem ao fluxo de moderação.

intended_statusstring

ADH

Status para o qual o produto volta quando for aprovado.

whatsapp_hiddenboolean

Esconde o produto só do catálogo do WhatsApp.

free_shippingboolean

Frete grátis.

requires_shippingboolean

false para produto digital, sem entrega.

weightnumber

Peso em kg. Não pode ser negativo.

lengthnumber

Comprimento em cm.

widthnumber

Largura em cm.

heightnumber

Altura em cm.

seo_titlestring

Título SEO.

seo_descriptionstring

Descrição SEO.

meta_keywordsstring

Palavras-chave SEO.

search_wordsstring

Termos extras para a busca da loja.

promo_textstring

Texto promocional acima do botão de compra.

buy_now_urlstring

Link externo de "Comprar agora" (lojas em modo catálogo). Vazio ou http(s)://...; outro formato é recusado.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/products/0497b6a8-c868-43be-ac21-2abddd24cd3c" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "price": 5290,
    "list_price": null,
    "quantity": 20,
    "stock_adjust_reason": "Inventário de outubro"
  }'

Resposta

200Produto alterado

json

{
  "id": "0497b6a8-c868-43be-ac21-2abddd24cd3c",
  "display_id": 10643,
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "category_id": "7ebc648d-6091-4511-8ea2-f86f7b3b4dd9",
  "name": "Caneca Esmaltada 350 ml",
  "slug": "caneca-esmaltada-350-ml",
  "sku": "CAN-350-AZ",
  "price": 5290,
  "cost_price": 2000,
  "track_inventory": true,
  "quantity": 20,
  "status": "A",
  "intended_status": "A",
  "approval_status": "approved",
  "created_at": "2026-10-11T20:51:07.858767Z",
  "updated_at": "2026-10-11T21:02:41.120331Z",
  "product_id": "0497b6a8-c868-43be-ac21-2abddd24cd3c",
  "price_str": "52.90",
  "amount": 20,
  "images": [],
  "price_tiers": []
}

Resposta resumida: o corpo real traz todos os campos do produto, descritos em Consultar produto.

Campos da resposta

*any

O produto completo, depois da alteração, com os mesmos campos de Consultar produto (sem descriptions e linked_orders_count).

Erros

Status	Quando	Corpo
400	JSON inválido, ou número em formato inválido	`{"error":"invalid request body","detail":"..."}`
400	Nenhum campo conhecido no corpo	`{"error":"no known fields to update","detail":"nenhum campo do corpo é aceito por este endpoint... Aceitos: ..."}` (a lista de campos aceitos vem no `detail`)
400	`{id}` que não é UUID	`{"error":"invalid product id","detail":"\"SKU1\" não é o id do produto (parece SKU ou código)..."}`
400	Nome vazio, preço ou custo negativos, categoria vazia	`{"error":"validation_failed","fields":{"price":"invalid_price"}}`. Códigos: `name_required`, `invalid_price`, `invalid_cost_price`, `category_required`
400	`list_price` menor que o preço	`{"error":"list_price_below_price","detail":"list_price (100) must be >= price (5490)"}`
400	Status inexistente	`{"error":"invalid product status","detail":"status \"cancelled\" não existe para produto: use \"active\" (A), \"disabled\" (D), \"hidden\" (H), \"pending\" (R) ou \"rejected\" (X)"}`
400	Nome longo demais, peso negativo, quantidades inválidas, `physical_shipping_data_required`, `barcode_required`	Mesmos códigos de Criar produto
401	Sem credenciais, chave inválida ou token expirado	`{"error":"invalid or expired token"}`
403	Usuário sem permissão de escrita	`{"error":"insufficient privileges","required":"manage_catalog"}`
404	O produto não existe ou está na lixeira	`{"error":"product not found","detail":"..."}`
409	SKU ou código de barras repetido	`{"error":"a product with this SKU already exists"}`
409	Oferta ligada a um mestre e a configuração da loja trava os campos do mestre	`{"error":"master-locked fields cannot be edited","locked_fields":["name"]}`
429	Limite de requisições	`{"error":"rate limit exceeded","detail":"too many requests, please try again later"}`
500	Falha interna; ou, por limitação conhecida, `vendor_id`/`category_id` inexistentes e `buy_now_url` inválido	`{"error":"failed to update product","detail":"o registro referenciado não existe (campo relacionado a \"vendor_id\")..."}`

Veja também