Conceitos

Status

O status é calculado a cada consulta, nesta ordem:

Vigência

• Data de início e data de término são obrigatórias.
• A data de término deve ser maior que a data de início e maior que o momento atual — inclusive ao editar. Para editar uma promoção expirada, informe uma nova data de término futura.

Prioridade

order define a ordem de avaliação: quanto menor o número, mais cedo a promoção é avaliada. Promoções sem prioridade ficam por último; empates são resolvidos pela data de início e depois pelo ID. Aceita null, zero ou valores positivos; valores negativos são recusados.

Acúmulo

• canAccumulate = false: a promoção só é aplicada se nenhuma outra já tiver sido aplicada ao carrinho, e nenhuma outra é aplicada depois dela.
• canAccumulate = true: a promoção pode ser combinada com outras que também acumulam, conforme o escopo accumulationScope.
• O acúmulo só tem efeito se a loja estiver configurada para permitir promoções cumulativas.

Qualquer outro valor de accumulationScope é recusado com 400 (ACCUMULATION_LINK_INVALID). Regras:

• Com canAccumulate = false, envie accumulationScope = 0 (ou omita) e nenhum vínculo.
• Com escopo 1 ou 2, a lista vazia [] é recusada (“Selecione ao menos uma promoção…”). Em uma atualização, accumulationLinks omitido ou null mantém os vínculos já cadastrados; enviar a lista substitui os vínculos.
• Não envie accumulationLinks: [] para limpar os vínculos: troque o escopo para 0.
• Uma promoção não pode ser vinculada a ela mesma nem duas vezes à mesma promoção.

Os escopos 1 e 2 só têm efeito no carrinho quando o acúmulo seletivo está habilitado para a loja. Com ele habilitado, valem também estas regras:

• Só é possível vincular promoções existentes na loja e que acumulam.
• Há um limite de vínculos por promoção (padrão: 5).
• Uma promoção citada no acúmulo de outras não pode passar a “não acumular” enquanto existirem essas referências (veja accumulationInboundLinks em Obter promoção).
• Ao criar com escopo 1 ou 2, informe os vínculos.

Cupons

O tipo da promoção é deduzido da quantidade de códigos em couponInformation.couponCodes:

• Códigos repetidos na lista são gravados uma única vez. Não envie códigos vazios.
• Um código não pode estar em uso por outra promoção da loja (salvo se a loja permitir cupons duplicados).
• allowCustomerToReuseSameCoupon só pode ser true com mais de um cupom.
• Apenas uma promoção com cupom é aplicada por carrinho, e ela é avaliada antes das demais.

Limites de uso

totalUsageLimit (usos totais) e usageLimitPerCustomer (usos por cliente), em generalInformation. 0, null ou omitido = ilimitado. Em promoções com cupom, um limite por cliente maior que o limite total é reduzido ao limite total. Se ficarem null, os campos equivalentes de couponInformation (couponTotalUsageLimit e couponUsageLimitPerCustomer) são usados.

Condições e grupos (E / OU)

• As condições ficam dentro de grupos (conditionGroups).
• Dentro de um grupo, todas as condições precisam ser atendidas (E).
• Entre grupos, basta um grupo ser atendido (OU).
• Com 2 ou mais grupos, cada grupo precisa de um name e de ao menos uma condição.
• Uma promoção sem condições vale para qualquer carrinho.

Cada condição é descrita por quatro coordenadas, todas obtidas em Estrutura de condições:

{
  "conditionGroup": 5,        // grupo (ex.: 5 = Carrinho)
  "conditionSubGroup": 16,    // subgrupo (ex.: 16 = Subtotal)
  "logicOperator": {
    "id": 3,                 // operador (ex.: 3 = maior ou igual)
    "arguments": [
      { "id": 4, "values": ["199.90"] }   // argumento 4 = valor
    ]
  }
}

Operadores

Cada condição aceita apenas alguns operadores; a lista exata por loja está em logicOperators da estrutura de condições.

Descontos

Cada desconto é descrito por um grupo (discountGroup), um tipo (discountSubGroup: 1 = valor nominal em R$, 2 = percentual, 3 = brinde selecionável) e seus argumentos. Uma promoção pode ter mais de um desconto. Veja todas as combinações em Receitas de descontos.

Selos, divulgação e parceiros

• Selos (stamps): imagens exibidas nos produtos participantes. Informe o stampId e a ordem de exibição.
• Divulgação (disclosure): textos ou HTML exibidos ao consumidor. type: 1 = spot (vitrines), 2 = página de produto. title tem no máximo 50 caracteres.
• Parceiros (partners): restringe a promoção a parceiros (B2B) específicos. Lista vazia = sem restrição.

Algumas condições não permitem divulgação; use Permissão de divulgação para saber se as condições escolhidas permitem selos e textos.