Alterar ou remover uma linha

Muda a quantidade de uma linha do carrinho ou remove a linha, identificando-a pelo line_id ou pelo id do produto.

Use estas rotas quando o comprador aperta "+" ou "−" na tela do carrinho, digita uma quantidade nova ou clica na lixeira de uma linha. As duas devolvem o carrinho completo já atualizado.

O parâmetro {productId} do caminho aceita duas coisas: o line_id da linha (recomendado, é único) ou o product_id do produto. Com o product_id, uma loja que vende o mesmo produto em duas variações ou com opções diferentes tem várias linhas candidatas; nesse caso informe também variation_id, unified_variation_id ou options para a API achar a linha certa.

Alterar a quantidade

PUT e PATCH fazem exatamente a mesma coisa; PATCH existe porque muitos clientes HTTP usam esse verbo para atualização parcial. Envie a nova quantidade total da linha, não a diferença.

PUT/api/v1/storefront/cart/items/{productId}Autenticada

Define a quantidade de uma linha do carrinho

Uma quantity igual ou menor que zero remove a linha. Uma quantidade positiva revalida as regras do produto (estoque, mínimo, máximo, múltiplo, visibilidade por grupo de clientes), porque elas podem ter mudado desde que o item entrou no carrinho.

Parâmetros de caminho

productIdstringobrigatório

line_id da linha ou product_id do produto.

Cabeçalhos

Authorizationstring

Bearer <token> do cliente logado.

X-Session-IDstring

Identificador do visitante. Obrigatório sem token.

Corpo da requisição

quantitynumberobrigatório

Nova quantidade total. Zero ou negativa remove a linha. O nome amount também é aceito; se os dois vierem, vale quantity. Atenção: um corpo sem nenhum dos dois remove a linha.

variation_iduuid

Ajuda a achar a linha quando productId é um id de produto com várias variações.

unified_variation_idinteger

Idem, para variação unificada.

optionsarray

Idem, para achar a linha com exatamente essa combinação de opções.

PATCH/api/v1/storefront/cart/items/{productId}Autenticada

Define a quantidade de uma linha do carrinho (alias PATCH)

Alias de PUT, com os mesmos parâmetros, corpo, respostas e erros.

Exemplo de requisição

bash

curl -X PATCH "$BASE_URL/api/v1/storefront/cart/items/64ddde83-28ce-4bba-86e5-ba9ebf1ba500" \
  -H "X-Session-ID: $SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "quantity": 3
}'

Resposta

200Carrinho atualizado

json

{
  "id": "01ff5b45-566b-4b98-94a1-23a648c9ea23",
  "items": [
    {
      "line_id": "64ddde83-28ce-4bba-86e5-ba9ebf1ba500",
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "name": "Notebook Slim Rosa 02373",
      "unit_price": 11500,
      "quantity": 3,
      "total": 34500
    }
  ],
  "subtotal": 34500,
  "total": 34500,
  "currency": "BRL"
}

A resposta tem os mesmos campos de Ler o carrinho. Mudar a quantidade pode mudar o preço unitário: se a quantidade cruza uma faixa de preço (ou uma regra B2B), o unit_price da linha é recalculado.

Remover uma linha

DELETE/api/v1/storefront/cart/items/{productId}Autenticada

Remove uma linha do carrinho

Remove a linha inteira, qualquer que seja a quantidade.

Parâmetros de caminho

productIdstringobrigatório

line_id da linha ou product_id do produto.

Parâmetros de consulta

variation_iduuid

Remove só a linha dessa variação. Necessário quando productId é um id de produto que tem várias variações no carrinho.

unified_variation_idinteger

Idem, para variação unificada. Sem ele, remover o tamanho M do produto poderia remover o tamanho L.

Cabeçalhos

Authorizationstring

Bearer <token> do cliente logado.

X-Session-IDstring

Identificador do visitante. Obrigatório sem token.

bash

curl -X DELETE "$BASE_URL/api/v1/storefront/cart/items/64ddde83-28ce-4bba-86e5-ba9ebf1ba500" \
  -H "X-Session-ID: $SESSION_ID"

A resposta 200 é o carrinho completo, sem a linha removida.

Erros

Status	Quando	Corpo
400	Sem token e sem `X-Session-ID`	`{"error":"session_id or authentication required"}`
400	Corpo que não é JSON (`PUT`, `PATCH`)	`{"error":"invalid request body"}`
400	Quantidade nova sem estoque, abaixo do mínimo, acima do máximo ou fora do múltiplo	`{"error":"insufficient stock for '...': requested 5, available 3"}`, `qty_below_minimum`, `qty_above_maximum`, `qty_not_multiple_of_step`
400	O produto deixou de estar disponível para esta conta	`product_not_available_for_user`
404	A linha não está no carrinho	`{"error":"item not found in cart: product zzz"}`
500	Falha interna ao gravar o carrinho	`{"error":"failed to update item","detail":"..."}`

Veja também

Alterar ou remover uma linha

Muda a quantidade de uma linha do carrinho ou remove a linha, identificando-a pelo line_id ou pelo id do produto.

Use estas rotas quando o comprador aperta "+" ou "−" na tela do carrinho, digita uma quantidade nova ou clica na lixeira de uma linha. As duas devolvem o carrinho completo já atualizado.

Alterar a quantidade

PUT e PATCH fazem exatamente a mesma coisa; PATCH existe porque muitos clientes HTTP usam esse verbo para atualização parcial. Envie a nova quantidade total da linha, não a diferença.

PUT/api/v1/storefront/cart/items/{productId}Autenticada

Define a quantidade de uma linha do carrinho

Parâmetros de caminho

productIdstringobrigatório

line_id da linha ou product_id do produto.

Cabeçalhos

Authorizationstring

Bearer <token> do cliente logado.

X-Session-IDstring

Identificador do visitante. Obrigatório sem token.

Corpo da requisição

quantitynumberobrigatório

Nova quantidade total. Zero ou negativa remove a linha. O nome amount também é aceito; se os dois vierem, vale quantity. Atenção: um corpo sem nenhum dos dois remove a linha.

variation_iduuid

Ajuda a achar a linha quando productId é um id de produto com várias variações.

unified_variation_idinteger

Idem, para variação unificada.

optionsarray

Idem, para achar a linha com exatamente essa combinação de opções.

PATCH/api/v1/storefront/cart/items/{productId}Autenticada

Define a quantidade de uma linha do carrinho (alias PATCH)

Alias de PUT, com os mesmos parâmetros, corpo, respostas e erros.

Exemplo de requisição

bash

curl -X PATCH "$BASE_URL/api/v1/storefront/cart/items/64ddde83-28ce-4bba-86e5-ba9ebf1ba500" \
  -H "X-Session-ID: $SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "quantity": 3
}'

Resposta

200Carrinho atualizado

json

{
  "id": "01ff5b45-566b-4b98-94a1-23a648c9ea23",
  "items": [
    {
      "line_id": "64ddde83-28ce-4bba-86e5-ba9ebf1ba500",
      "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "name": "Notebook Slim Rosa 02373",
      "unit_price": 11500,
      "quantity": 3,
      "total": 34500
    }
  ],
  "subtotal": 34500,
  "total": 34500,
  "currency": "BRL"
}

Remover uma linha

DELETE/api/v1/storefront/cart/items/{productId}Autenticada

Remove uma linha do carrinho

Remove a linha inteira, qualquer que seja a quantidade.

Parâmetros de caminho

productIdstringobrigatório

line_id da linha ou product_id do produto.

Parâmetros de consulta

variation_iduuid

Remove só a linha dessa variação. Necessário quando productId é um id de produto que tem várias variações no carrinho.

unified_variation_idinteger

Idem, para variação unificada. Sem ele, remover o tamanho M do produto poderia remover o tamanho L.

Cabeçalhos

Authorizationstring

Bearer <token> do cliente logado.

X-Session-IDstring

Identificador do visitante. Obrigatório sem token.

bash

curl -X DELETE "$BASE_URL/api/v1/storefront/cart/items/64ddde83-28ce-4bba-86e5-ba9ebf1ba500" \
  -H "X-Session-ID: $SESSION_ID"

A resposta 200 é o carrinho completo, sem a linha removida.

Erros

Status	Quando	Corpo
400	Sem token e sem `X-Session-ID`	`{"error":"session_id or authentication required"}`
400	Corpo que não é JSON (`PUT`, `PATCH`)	`{"error":"invalid request body"}`
400	Quantidade nova sem estoque, abaixo do mínimo, acima do máximo ou fora do múltiplo	`{"error":"insufficient stock for '...': requested 5, available 3"}`, `qty_below_minimum`, `qty_above_maximum`, `qty_not_multiple_of_step`
400	O produto deixou de estar disponível para esta conta	`product_not_available_for_user`
404	A linha não está no carrinho	`{"error":"item not found in cart: product zzz"}`
500	Falha interna ao gravar o carrinho	`{"error":"failed to update item","detail":"..."}`