Tipos de preço
Um registro de preço é sempre gravado como a combinação SKU + política comercial, e cada combinação aceita três valores, com papéis distintos:
| Tipo | Campo | Papel |
|---|---|---|
| Preço de lista | listPrice | valor “de” — o preço cheio, exibido riscado |
| Preço base | basePrice | valor “por” — o que o cliente paga |
| Preço fixo | fixedPrice | trava o valor, ignorando promoções |
Como a vitrine escolhe
A escolha é feita por SKU, não por política comercial. Entre os preços vigentes de
um SKU, ganha o de maior prioridade de tipo — fixedPrice, depois basePrice, depois
listPrice. A commercialPolicyId do registro não entra nesse critério.
Isso não atrapalha a operação normal, em que cada SKU tem um preço vigente por vez. Só importa se você publicar o mesmo SKU em duas políticas ao mesmo tempo — veja Multi-política, abaixo nesta página.
O diagrama responde: dado um SKU com vários preços cadastrados, qual valor a loja cobra e qual ela risca?
O valor riscado não é necessariamente o listPrice: é o segundo preço disponível
nessa ordem. Com fixedPrice e basePrice cadastrados, é o basePrice que aparece
riscado, e o listPrice não é usado.
Multi-política
Você pode operar mais de uma tabela de preço no mesmo tenant. O modelo é: todo produto
declara a política a que pertence (commercialPolicyId em POST /v1/batch/Products), e
todo preço é gravado como SKU + política.
Para varejo e atacado no mesmo CNPJ, o desenho que funciona é modelar um produto por
política: cada um com o seu externalReference, apontando para a sua
commercialPolicyId, e o preço de cada SKU publicado na política do produto ao qual ele
pertence.
Não publique preços do mesmo SKU em duas políticas ao mesmo tempo. A resolução do preço vigente agrupa por SKU, não por SKU + política: se houver dois preços válidos para o mesmo SKU no mesmo instante, quem ganha é decidido por tipo e valor, e a política não entra no critério. O resultado deixa de ser previsível.
Mantenha a regra simples: um SKU, uma política, um preço vigente por vez. Se o mesmo item precisa de dois valores, ele precisa de dois SKUs.
Se a sua operação usa uma tabela só, ignore este bloco: publique tudo na
commercialPolicyId que a Grocers entregou na abertura da conta.
Quando usar cada um
Só basePrice — o caso simples. O item tem um preço e pronto.
listPrice + basePrice — o desconto permanente. A vitrine mostra o “de/por” e o
percentual de economia. Só faz sentido se listPrice for realmente maior; valores
iguais fazem a loja exibir um desconto de 0%, o que confunde.
fixedPrice — o preço protegido. Use para itens sob acordo comercial ou tabelados,
onde nenhuma promoção da loja pode incidir. É a exceção, não a regra.
fixedPrice bloqueia campanhas promocionais para aquele SKU. Aplicá-lo em massa
“para garantir o preço” desliga sem aviso todo o mecanismo de promoção da loja.
Vigência
Cada um dos três aceita janela de validade:
{
"value": 8.99,
"startDateTime": "2026-08-01T00:00:00",
"endDateTime": "2026-08-07T23:59:59"
}Sem startDateTime e endDateTime, o preço vale imediatamente e por tempo
indeterminado. Com janela, ele entra e sai sozinho — veja
Preços programados.
As datas de vigência são interpretadas em horário de Brasília (UTC−3), não em UTC.
Escreva a hora do relógio de Brasília: para uma virada à meia-noite de 1º de agosto,
envie "2026-08-01T00:00:00". A plataforma compara o valor gravado contra o horário de
Brasília na hora de resolver o preço vigente.
Escrever T03:00:00Z achando que “converte” a meia-noite de Brasília coloca a promoção
no ar às 3 h da manhã — três horas depois do pretendido, com o preço antigo valendo
a madrugada inteira.
Não envie designador de fuso. O sufixo Z é aceito, mas mente sobre o significado:
o valor não é convertido, é comparado como se fosse hora de Brasília. Pior, um offset
explícito (2026-08-01T00:00:00-03:00) passa por uma conversão antes de ser gravado e
desloca a janela. Envie sempre a data local sem sufixo.
Vitrine e checkout resolvem a vigência com relógios diferentes, e divergem em 3 horas. A listagem de produtos compara contra o relógio do servidor de banco (UTC); o checkout converte para Brasília antes de comparar. A listagem entra e sai da janela 3 horas antes do carrinho. Os detalhes e a orientação de planejamento estão em Preços programados.
Preço e disponibilidade
Um SKU sem nenhum preço vigente não é vendável, mesmo com estoque publicado. A vitrine simplesmente não o exibe como comprável.
Por isso a ordem da carga inicial termina em preço: é o último passo que torna o item efetivamente vendável.