---
title: "Atualizar promoção"
method: PUT
path: "/api/promotions/{promotionId}"
tags: ["Admin API · Promoções"]
---

# Atualizar promoção

`PUT /api/promotions/{promotionId}`

## Request

- Base URL: `https://sualoja.commerce-wake.tech`
- URL: `https://sualoja.commerce-wake.tech/api/promotions/{promotionId}`
- Auth: HTTP bearer

Substitui **todos** os dados da promoção pelo conteúdo enviado. Condições, descontos, regras adicionais, selos,
textos de divulgação e parceiros que não estiverem no corpo são removidos (uma lista omitida vale como `[]`).
A única exceção é `accumulationLinks` com escopo 1 ou 2: omitido ou `null`, os vínculos atuais são mantidos.
            
Para alterar um único campo, leia a promoção, altere o campo e reenvie tudo. Grupos de condições, condições e
descontos são recriados a cada atualização, então seus IDs mudam.
            
Permissão: **Cadastro de promoções — visualização e edição**.

## Path parameters

- `promotionId` integer, required

## Headers

- `x-api-version` '2.0', required

## Request body

- PutPromotionCommand
  - `generalInformation` PromotionGeneralInformationDTO, required
    - `name` string, nullable: Obrigatório. Nome da promoção, até 250 caracteres.
    - `description` string, nullable: Descrição interna, até 1000 caracteres.
    - `startDate` string, date-time, nullable: Obrigatório. Início da vigência (ISO 8601; sem fuso, horário de Brasília).
    - `endDate` string, date-time, nullable: Obrigatório. Fim da vigência, maior que `startDate` e que o momento atual.
    - `canAccumulate` boolean: Se acumula com outras promoções. Padrão: `false`.
    - `accumulationScope` 0 | 1 | 2: Escopo de acúmulo de uma promoção que permite acumular. O lojista escolhe UM escopo por promoção — nunca mistura inclusão com exclusão.
    - `isActive` boolean: Se a promoção nasce ativa. Padrão: `false`.
    - `order` integer, nullable: Prioridade (menor = avaliada antes). `null`, zero ou positivo. Padrão: `null`.
    - `totalUsageLimit` integer, nullable: Limite total de usos. 0, `null` ou omitido = ilimitado.
    - `usageLimitPerCustomer` integer, nullable: Limite de usos por cliente. 0, `null` ou omitido = ilimitado.
    - `type` PromotionTypeInformationDTO
      - `typeId` 1 | 2 | 3
      - `label` string, nullable: Obsoleto e ignorado.
  - `couponInformation` PromotionCouponInformationDTO, required
    - `multipleCouponConfig` MultipleCouponConfigDTO
      - `hasMultipleCoupons` boolean: Somente leitura: deduzido da quantidade de códigos e ignorado na escrita.
      - `allowCustomerToReuseSameCoupon` boolean: Permite que o mesmo cliente reutilize um código. Só com mais de um cupom.
    - `couponCodes` string[], nullable: Obrigatório. Códigos de cupom; `[]` para promoções sem cupom. A quantidade define o tipo da promoção (sem cupom, cupom único ou múltiplos cupons).
    - `couponTotalUsageLimit` integer, nullable: Alternativa a `generalInformation.totalUsageLimit`, usada quando aquele é `null`.
    - `couponUsageLimitPerCustomer` integer, nullable: Alternativa a `generalInformation.usageLimitPerCustomer`, usada quando aquele é `null`.
  - `conditionGroups` PromotionConditionGroupDTO[], nullable: Grupos de condições. Substitui os atuais: omitido ou `[]` remove todas as condições.
    - `id` integer, nullable: ID do grupo, retornado em Obter promoção. Ignorado na escrita: os grupos são recriados a cada gravação.
    - `name` string, nullable: Nome do grupo. Obrigatório quando há 2 ou mais grupos.
    - `conditions` PromotionConditionDTO[], nullable: Condições do grupo; todas precisam ser atendidas (E). Nunca `null`: use `[]`.
      - `conditionGroup` 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8
      - `conditionSubGroup` 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27: Subgrupo de condição de promoção.
      - `logicOperator` PromotionConditionLogicOperatorDTO
        - `id` 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
        - `arguments` PromotionConditionArgumentDTO[], nullable: Argumentos do operador. Nunca `null`: use `[]`. Uma condição sem argumentos é descartada sem erro.
          - `values` string[], nullable: Valores do argumento, sempre como strings (ex.: `["10.5"]`, `["true"]`). Numéricos e booleanos recebem um único valor, decimais com ponto. Argumento com lista vazia é descartado.
          - `id` 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 25
      - `productsFilter` ProductsFilterDTO
        - `productIds_Neq` integer[], nullable: Produtos excluídos do resultado do filtro.
        - `search` string, nullable: Busca textual no catálogo de produtos.
        - `categoryIds` integer[], nullable: Somente produtos destas categorias.
        - `brandIds` integer[], nullable: Somente produtos destas marcas.
        - `stock_Gte` integer, nullable: Estoque mínimo.
        - `stock_Lte` integer, nullable: Estoque máximo.
        - `price_Gte` number, double, nullable: Preço mínimo.
        - `price_Lte` number, double, nullable: Preço máximo.
  - `discounts` PromotionDiscountDTO[], nullable: Descontos. Substitui os atuais: omitido ou `[]` remove todos.
    - `discountGroup` 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10
    - `discountSubGroup` 0 | 1 | 2 | 3
    - `arguments` PromotionDiscountArgumentDTO[], nullable: Argumentos do desconto. Nunca `null`: use `[]`. Um desconto sem argumentos é descartado sem erro.
      - `values` string[], nullable: Valores do argumento, sempre como strings (ex.: `["10.5"]`, `["true"]`). Numéricos e booleanos recebem um único valor, decimais com ponto. Argumento com lista vazia é descartado.
      - `id` 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 998 | 999: Argumento de desconto de promoção.
    - `productsFilter` ProductsFilterDTO
      - `productIds_Neq` integer[], nullable: Produtos excluídos do resultado do filtro.
      - `search` string, nullable: Busca textual no catálogo de produtos.
      - `categoryIds` integer[], nullable: Somente produtos destas categorias.
      - `brandIds` integer[], nullable: Somente produtos destas marcas.
      - `stock_Gte` integer, nullable: Estoque mínimo.
      - `stock_Lte` integer, nullable: Estoque máximo.
      - `price_Gte` number, double, nullable: Preço mínimo.
      - `price_Lte` number, double, nullable: Preço máximo.
  - `stamps` PromotionStampDTO[], nullable: Selos. Substitui os atuais: omitido ou `[]` remove todos.
    - `stampId` integer: ID do selo (de GET /api/stamps).
    - `order` integer, nullable: Ordem de exibição do selo.
  - `disclosure` PromotionDisclosureDTO[], nullable: Textos de divulgação. Substitui os atuais: omitido ou `[]` remove todos.
    - `content` string, nullable: Texto da divulgação (aceita HTML).
    - `title` string, nullable: Título da divulgação, até 50 caracteres.
    - `type` 1 | 2
  - `partners` integer[], nullable: IDs de parceiros. Substitui os atuais: omitido ou `[]` remove a restrição.
  - `entityRules` PromotionRule[], nullable: Regras adicionais. Substitui as atuais: omitido ou `[]` remove todas.
    - `entityId` integer: Entidade da regra (de GET /api/promotions/structure/rules).
    - `validationId` integer: Tipo de validação aceito pela entidade.
    - `restrictionId` integer: Onde a regra vale: 1 = no desconto e nas condições, 2 = apenas no desconto (o item não recebe benefício), 3 = apenas nas condições (o item não conta para atingi-las). Enviar uma regra com 2 e outra igual com 3 equivale a 1.
    - `arguments` string[], nullable: Valores da regra, como strings.
  - `accumulationLinks` integer[], nullable: Ids das promos citadas na lista de acúmulo, conforme `GeneralInformation.AccumulationScope`. O vínculo é direcional.

## Response `200`

Promoção atualizada.

- PutPromotionResponseDTO
  - `message` string, nullable: Mensagem de confirmação.
  - `success` boolean: Legado: `true` quando a promoção foi atualizada.
  - `errors` PromotionError[], nullable: Legado: erros de gravação. Em falhas, use `details` do envelope de erro.
    - `errorCode` 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25
    - `message` string, nullable: Mensagem do erro.
  - `data` PromotionIdDataDTO: ID da promoção criada ou atualizada.
    - `promotionId` integer: ID da promoção.

## Other responses

- `400`: Corpo inválido ou regra de negócio recusada, no mesmo formato de Criar promoção.
- `401`: Token ausente, inválido ou expirado (SESSION_INVALID), ou sem a permissão exigida (UNAUTHORIZED).
- `404`: Promoção inexistente ou excluída (`NOT_FOUND`).
- `409`: Conflito com o estado atual.
- `500`: Erro inesperado ao gravar. Leia a promoção para conferir o estado e tente de novo.

---

[API](https://skmtc.dev/fbits/apis/admin-api.md) - [All operations](https://skmtc.dev/fbits/apis/admin-api/llms.txt) - [OpenAPI document](https://skmtc.dev/fbits/apis/admin-api/revisions/a37bfd1b0bf3?raw)