Carrinho

O carrinho guarda o que o comprador pretende levar antes de fechar o pedido: os itens, as quantidades, o cupom digitado e o resumo de valores. Ele existe para o cliente logado e também para o visitante que ainda não tem conta. Quando a compra é finalizada, o carrinho vira um checkout e depois um pedido.

Esta seção cobre tudo o que acontece antes do checkout: montar o carrinho, alterar linhas, calcular totais com promoções e frete, aplicar cupom, importar uma planilha de itens e recuperar um carrinho abandonado.

Como funciona

O carrinho é criado sozinho na primeira chamada: GET /cart para um visitante novo devolve um carrinho vazio e já o grava. Ele expira cerca de 30 dias depois de criado (expires_at).

1. Identifique o comprador

   Gere um identificador de visitante (um UUID v4 aleatório) e guarde no navegador ou no app. Envie em todas as chamadas como X-Session-ID. Se o cliente fizer login, envie também o token: o token passa a valer e o X-Session-ID deixa de identificar o carrinho.

2. Adicione itens

   Adicionar itens devolve o carrinho inteiro já atualizado. Cada chamada aplica as regras do produto: estoque, quantidade mínima, máxima e múltiplo.

3. Mostre os valores

   Chame Calcular o carrinho a cada mudança para obter desconto, frete e total corretos. Chame Aplicar cupom quando o comprador digitar um código.

4. Depois do login, una os carrinhos

   O visitante que entra na conta traz um carrinho de visitante. Unir carrinhos passa as linhas dele para o carrinho da conta.

5. Siga para o checkout

   Com o carrinho pronto, abra a sessão em Iniciar o checkout.

Conceitos-chave

Cliente, visitante e chave de API

A loja pode exigir login para comprar. Se allow_guest_cart estiver desligado (veja Configurações do checkout), o visitante recebe 401 ao tentar adicionar um item.

Totais do carrinho e totais calculados

O objeto do carrinho traz subtotal, discount_total, shipping_total, tax_total e total, mas esses campos refletem só a soma dos itens. Promoções automáticas, cupom, frete e impostos entram apenas na resposta de Calcular o carrinho, que é a fonte para exibir o total ao comprador.

Campos de compatibilidade nas respostas

As respostas do carrinho repetem alguns valores em formatos antigos, para clientes escritos para a plataforma anterior: cart_id (igual a id), subtotal_str e total_str (valores em string decimal, "230.00"), timestamp (Unix) e, em cada item, id, item_id (iguais a product_id), amount (igual a quantity), price_str e subtotal_str. Em integrações novas, ignore esses campos e use os de centavos.

Carrinho de filial (compra B2B)

Quem compra por uma filial de empresa envia X-Organization-Branch-Id com o UUID da filial. O carrinho passa a ser o da filial. Um valor que não é UUID devolve 400 invalid_branch e uma filial que o usuário não pode usar devolve 403 branch_forbidden.

Cache

As rotas de /cart respondem com Cache-Control: no-store. Não coloque um CDN na frente delas.

Rotas

Erros comuns

• Esquecer o X-Session-ID. Sem token e sem o cabeçalho, toda rota do carrinho devolve 400 session_id or authentication required.
• Trocar de X-Session-ID a cada página. Cada valor novo cria um carrinho vazio novo. Gere o identificador uma vez e reaproveite.
• Exibir total do carrinho como valor final. Esse campo ignora promoções, cupom e frete. Use o resultado de Calcular o carrinho.
• Enviar quantity zero ao adicionar. Adicionar exige quantidade maior que zero (400 quantity must be positive). Para tirar uma linha, use Remover uma linha.
• Tratar 500 ao adicionar produto inexistente como falha do servidor. Um product_id que não existe ou está inativo hoje devolve 500 failed to add item, com a causa em detail. Valide o id antes.
• Confiar no preço guardado na linha. O preço é recalculado no checkout; se mudou, o pedido é recusado com price_changed e o comprador precisa revisar o total.

Próximos passos