Otimizações e exemplos de uso API Magento 2 Adobe Commerce

Regras de carrinho (Sales Rules) via REST API

Referência de exemplos prontos para criar, listar, atualizar e excluir regras de carrinho e cupons pela API REST do Magento 2.

S Sidenei Steinbach 08/09/2026 Atualizado 08/09/2026 10 min de leitura

magento-2 api promocoes cupom sales-rules

Esta página reúne exemplos prontos de chamadas à API REST para criar, consultar, atualizar, desativar e excluir regras de carrinho (Sales Rules) e seus cupons.
O leitor é o desenvolvedor ou fornecedor que integra um sistema externo à loja — ERP, hub, painel próprio ou automação de campanhas.
Pré-requisito: uma integração já criada na loja, com token de acesso válido e permissão para o recurso de regras de carrinho.
Não cobre a configuração dessas regras pelo painel administrativo nem regras de preço de catálogo — apenas o uso da API REST no Magento 2.

Antes de começar

Todos os exemplos usam https://example.com como base. Substitua pelo domínio da sua loja.

Substitua também token_aqui pelo Bearer token da sua integração. O token vai sempre no header Authorization, e as chamadas de criação e atualização exigem Content-Type: application/json.

O token da integração dá acesso de escrita às regras e aos cupons da loja. Mantenha-o apenas no servidor que faz a integração — nunca em código de frontend, repositório público ou arquivo compartilhado.

Conceitos e valores dos campos

Antes dos exemplos, os valores que mais geram dúvida no payload.

coupon_type — como a regra é acionada

Valor	Significado
`1`	Sem cupom (regra automática)
`2`	Cupom específico
`3`	Auto-geração de cupons

simple_action — como o desconto é calculado

Valor	Significado
`by_percent`	Percentual de desconto no item
`by_fixed`	Valor fixo por item
`cart_fixed`	Valor fixo no total do carrinho
`buy_x_get_y`	Compre X leve Y

simple_free_shipping — frete grátis

Valor	Significado
`"0"`	Não
`"1"`	Itens correspondentes
`"2"`	Carrinho todo

discount_qty — quantidade máxima de unidades que recebem o desconto. 0 significa sem limite.

Um atributo de produto só fica disponível nas condições da regra se estiver com Use for Promo Rule Conditions = Yes (is_used_for_promo_rules = 1). Sem isso, a condição não pode ser montada.

O GET de uma regra normalmente não retorna condition e action_condition populados. Não use o retorno do GET como base para um PUT: o PUT exige payload completo e as condições seriam zeradas. Guarde o JSON de criação do seu lado.

Em JSON, as barras invertidas dos nomes de classe precisam estar escapadas — \\ em vez de \.

1. Listar regras

Todas, paginado:

curl --location 'https://example.com/rest/V1/salesRules/search?searchCriteria[pageSize]=50&searchCriteria[currentPage]=1' \
--header 'Authorization: Bearer token_aqui'

Somente ativas:

curl --location 'https://example.com/rest/V1/salesRules/search?searchCriteria[filterGroups][0][filters][0][field]=is_active&searchCriteria[filterGroups][0][filters][0][value]=1&searchCriteria[filterGroups][0][filters][0][conditionType]=eq&searchCriteria[pageSize]=50' \
--header 'Authorization: Bearer token_aqui'

Por nome (LIKE), ordenado pelas mais recentes:

curl --location 'https://example.com/rest/V1/salesRules/search?searchCriteria[filterGroups][0][filters][0][field]=name&searchCriteria[filterGroups][0][filters][0][value]=%25API%25&searchCriteria[filterGroups][0][filters][0][conditionType]=like&searchCriteria[sortOrders][0][field]=rule_id&searchCriteria[sortOrders][0][direction]=DESC&searchCriteria[pageSize]=20' \
--header 'Authorization: Bearer token_aqui'

2. Ler uma regra específica

curl --location 'https://example.com/rest/V1/salesRules/5' \
--header 'Authorization: Bearer token_aqui'

3. Criar regra simples — 10% preparada para cupom

coupon_type: 2 apenas marca a regra como "usa cupom específico". O código do cupom não é criado aqui — RuleInterface não expõe o campo coupon_code, então qualquer coupon_code enviado no payload é descartado pelo webapi.

O código sai em uma segunda chamada, em /V1/coupons, usando o rule_id retornado pelo POST abaixo.

Uma regra criada com coupon_type: 2 nasce sem cupom nenhum e nunca é aplicada até que o código seja criado na segunda chamada. Criar só a regra e parar aí é o erro mais comum desse fluxo.

curl --location 'https://example.com/rest/V1/salesRules' \
--header 'Authorization: Bearer token_aqui' \
--header 'Content-Type: application/json' \
--data '{
  "rule": {
    "name": "10 porcento - cupom especifico",
    "description": "Cupom de teste via API",
    "website_ids": [1],
    "customer_group_ids": [0, 1, 2, 3],
    "is_active": true,
    "coupon_type": 2,
    "uses_per_coupon": 100,
    "uses_per_customer": 1,
    "simple_action": "by_percent",
    "discount_amount": 10,
    "discount_qty": 0,
    "discount_step": 0,
    "apply_to_shipping": false,
    "stop_rules_processing": false,
    "is_rss": false,
    "sort_order": 10,
    "from_date": "2026-09-08",
    "to_date": "2026-12-31"
  }
}'

Com o rule_id da resposta, criar o código:

curl --location 'https://example.com/rest/V1/coupons' \
--header 'Authorization: Bearer token_aqui' \
--header 'Content-Type: application/json' \
--data '{
  "coupon": {
    "rule_id": 5,
    "code": "DESCONTO10",
    "usage_limit": 100,
    "usage_per_customer": 1,
    "expiration_date": null,
    "is_primary": true,
    "type": 0
  }
}'

usage_limit e usage_per_customer com 0 significam ilimitado. Em type, 0 é manual e 1 é gerado. is_primary: true marca o cupom como o principal da regra — é o que aparece no campo Coupon Code do admin.

Se a intenção for um lote de códigos, a regra precisa ser criada com coupon_type: 3 e use_auto_generation: true, e os códigos saem via POST /V1/coupons/generate.

A ordem é sempre a mesma: primeiro POST /V1/salesRules para criar a regra, depois POST /V1/coupons com o rule_id retornado para criar o código. Não existe endpoint nativo que faça as duas coisas em uma operação, e as chamadas não são atômicas — se a segunda falhar (código duplicado, por exemplo), a regra fica criada e sem cupom.

4. Criar regra com condição de carrinho — subtotal + país

Condição: base_subtotal >= 200 E country_id == BR.

curl --location 'https://example.com/rest/V1/salesRules' \
--header 'Authorization: Bearer token_aqui' \
--header 'Content-Type: application/json' \
--data '{
  "rule": {
    "name": "10 porcento acima de R$200 - BR",
    "description": "Criada via API com condicao de carrinho",
    "website_ids": [1],
    "customer_group_ids": [0, 1, 2, 3],
    "is_active": true,
    "coupon_type": 2,
    "uses_per_customer": 1,
    "simple_action": "by_percent",
    "discount_amount": 10,
    "apply_to_shipping": false,
    "stop_rules_processing": false,
    "sort_order": 10,
    "from_date": "2026-09-08",
    "to_date": "2026-12-31",
    "condition": {
      "condition_type": "Magento\\SalesRule\\Model\\Rule\\Condition\\Combine",
      "aggregator_type": "all",
      "value": "1",
      "conditions": [
        {
          "condition_type": "Magento\\SalesRule\\Model\\Rule\\Condition\\Address",
          "attribute_name": "base_subtotal",
          "operator": ">=",
          "value": "200"
        },
        {
          "condition_type": "Magento\\SalesRule\\Model\\Rule\\Condition\\Address",
          "attribute_name": "country_id",
          "operator": "==",
          "value": "BR"
        }
      ]
    }
  }
}'

Atributos úteis em Condition\Address: base_subtotal, base_subtotal_with_discount, total_qty, weight, shipping_method, postcode, region, region_id, country_id.

Em aggregator_type, "all" equivale a E e "any" equivale a OU.

5. Criar regra com condição sobre itens do carrinho

Condição: existe no carrinho um item da categoria 5 com quantidade maior ou igual a 2. O Product\Found fica aninhado dentro do Combine.

curl --location 'https://example.com/rest/V1/salesRules' \
--header 'Authorization: Bearer token_aqui' \
--header 'Content-Type: application/json' \
--data '{
  "rule": {
    "name": "15 porcento - categoria 5 com 2+ itens",
    "website_ids": [1],
    "customer_group_ids": [0, 1, 2, 3],
    "is_active": true,
    "coupon_type": 1,
    "simple_action": "by_percent",
    "discount_amount": 15,
    "stop_rules_processing": false,
    "sort_order": 20,
    "condition": {
      "condition_type": "Magento\\SalesRule\\Model\\Rule\\Condition\\Combine",
      "aggregator_type": "all",
      "value": "1",
      "conditions": [
        {
          "condition_type": "Magento\\SalesRule\\Model\\Rule\\Condition\\Product\\Found",
          "aggregator_type": "all",
          "value": "1",
          "conditions": [
            {
              "condition_type": "Magento\\SalesRule\\Model\\Rule\\Condition\\Product",
              "attribute_name": "category_ids",
              "operator": "==",
              "value": "5"
            },
            {
              "condition_type": "Magento\\SalesRule\\Model\\Rule\\Condition\\Product",
              "attribute_name": "quote_item_qty",
              "operator": ">=",
              "value": "2"
            }
          ]
        }
      ]
    }
  }
}'

No Product\Found, "value": "1" significa "se encontrado" e "value": "0" significa "se não encontrado" — útil para excluir marcas ou categorias do carrinho.

Para condicionar por soma de itens (por exemplo, total dos itens da categoria X maior ou igual a 500), troque Product\Found por Product\Subselect, informando attribute_name (base_row_total ou qty) e operator:

{
  "condition_type": "Magento\\SalesRule\\Model\\Rule\\Condition\\Product\\Subselect",
  "attribute_name": "base_row_total",
  "operator": ">=",
  "value": "500",
  "aggregator_type": "all",
  "conditions": [
    {
      "condition_type": "Magento\\SalesRule\\Model\\Rule\\Condition\\Product",
      "attribute_name": "category_ids",
      "operator": "==",
      "value": "5"
    }
  ]
}

6. Criar regra com `action_condition`

condition define quando a regra vale; action_condition define em quais itens o desconto é aplicado (aba Actions do admin). Exemplo: 20% somente nos SKUs listados, com subtotal mínimo de 100.

curl --location 'https://example.com/rest/V1/salesRules' \
--header 'Authorization: Bearer token_aqui' \
--header 'Content-Type: application/json' \
--data '{
  "rule": {
    "name": "20 porcento em SKUs selecionados",
    "website_ids": [1],
    "customer_group_ids": [0, 1, 2, 3],
    "is_active": true,
    "coupon_type": 2,
    "simple_action": "by_percent",
    "discount_amount": 20,
    "discount_qty": 2,
    "stop_rules_processing": false,
    "sort_order": 30,
    "condition": {
      "condition_type": "Magento\\SalesRule\\Model\\Rule\\Condition\\Combine",
      "aggregator_type": "all",
      "value": "1",
      "conditions": [
        {
          "condition_type": "Magento\\SalesRule\\Model\\Rule\\Condition\\Address",
          "attribute_name": "base_subtotal",
          "operator": ">=",
          "value": "100"
        }
      ]
    },
    "action_condition": {
      "condition_type": "Magento\\SalesRule\\Model\\Rule\\Condition\\Product\\Combine",
      "aggregator_type": "all",
      "value": "1",
      "conditions": [
        {
          "condition_type": "Magento\\SalesRule\\Model\\Rule\\Condition\\Product",
          "attribute_name": "sku",
          "operator": "()",
          "value": "SKU-001,SKU-002,SKU-003"
        }
      ]
    }
  }
}'

O discount_qty: 2 deste exemplo limita a quantidade de unidades que recebem o desconto em cada item correspondente. Para não impor limite, use 0.

7. Criar regra — valor fixo no carrinho

Desconto fixo de R$ 50 no total, com subtotal mínimo de 400.

curl --location 'https://example.com/rest/V1/salesRules' \
--header 'Authorization: Bearer token_aqui' \
--header 'Content-Type: application/json' \
--data '{
  "rule": {
    "name": "R$50 off acima de R$400",
    "website_ids": [1],
    "customer_group_ids": [0, 1, 2, 3],
    "is_active": true,
    "coupon_type": 2,
    "simple_action": "cart_fixed",
    "discount_amount": 50,
    "apply_to_shipping": false,
    "stop_rules_processing": false,
    "sort_order": 15,
    "condition": {
      "condition_type": "Magento\\SalesRule\\Model\\Rule\\Condition\\Combine",
      "aggregator_type": "all",
      "value": "1",
      "conditions": [
        {
          "condition_type": "Magento\\SalesRule\\Model\\Rule\\Condition\\Address",
          "attribute_name": "base_subtotal",
          "operator": ">=",
          "value": "400"
        }
      ]
    }
  }
}'

8. Criar regra — frete grátis acima de X

curl --location 'https://example.com/rest/V1/salesRules' \
--header 'Authorization: Bearer token_aqui' \
--header 'Content-Type: application/json' \
--data '{
  "rule": {
    "name": "Frete gratis acima de R$300",
    "website_ids": [1],
    "customer_group_ids": [0, 1, 2, 3],
    "is_active": true,
    "coupon_type": 1,
    "simple_action": "cart_fixed",
    "discount_amount": 0,
    "apply_to_shipping": false,
    "simple_free_shipping": "2",
    "stop_rules_processing": false,
    "sort_order": 5,
    "condition": {
      "condition_type": "Magento\\SalesRule\\Model\\Rule\\Condition\\Combine",
      "aggregator_type": "all",
      "value": "1",
      "conditions": [
        {
          "condition_type": "Magento\\SalesRule\\Model\\Rule\\Condition\\Address",
          "attribute_name": "base_subtotal",
          "operator": ">=",
          "value": "300"
        }
      ]
    }
  }
}'

9. Atualizar regra

Enviar o payload completo, incluindo condition e action_condition.

Campos omitidos no PUT são sobrescritos ou zerados. Como o GET não devolve as condições populadas, monte o PUT a partir do JSON de criação guardado do seu lado — não a partir da resposta do GET.

curl --location --request PUT 'https://example.com/rest/V1/salesRules/5' \
--header 'Authorization: Bearer token_aqui' \
--header 'Content-Type: application/json' \
--data '{
  "rule": {
    "rule_id": 5,
    "name": "10 porcento acima de R$250 - BR",
    "website_ids": [1],
    "customer_group_ids": [0, 1, 2, 3],
    "is_active": true,
    "coupon_type": 2,
    "simple_action": "by_percent",
    "discount_amount": 10,
    "stop_rules_processing": false,
    "sort_order": 10,
    "condition": {
      "condition_type": "Magento\\SalesRule\\Model\\Rule\\Condition\\Combine",
      "aggregator_type": "all",
      "value": "1",
      "conditions": [
        {
          "condition_type": "Magento\\SalesRule\\Model\\Rule\\Condition\\Address",
          "attribute_name": "base_subtotal",
          "operator": ">=",
          "value": "250"
        }
      ]
    }
  }
}'

10. Desativar regra

Mesmo endpoint do update, só com is_active: false — mas ainda com o payload completo.

curl --location --request PUT 'https://example.com/rest/V1/salesRules/5' \
--header 'Authorization: Bearer token_aqui' \
--header 'Content-Type: application/json' \
--data '{
  "rule": {
    "rule_id": 5,
    "name": "10 porcento acima de R$250 - BR",
    "website_ids": [1],
    "customer_group_ids": [0, 1, 2, 3],
    "is_active": false,
    "coupon_type": 2,
    "simple_action": "by_percent",
    "discount_amount": 10,
    "stop_rules_processing": false,
    "sort_order": 10
  }
}'

11. Deletar regra

curl --location --request DELETE 'https://example.com/rest/V1/salesRules/5' \
--header 'Authorization: Bearer token_aqui'

A exclusão é irreversível e remove também os cupons vinculados à regra. Para suspender uma promoção temporariamente, use o PUT com is_active: false do item 10.

Referência — operadores

Operador	Significado
`==`	igual a
`!=`	diferente de
`>=`	maior ou igual
`<=`	menor ou igual
`>`	maior que
`<`	menor que
`{}`	contém
`!{}`	não contém
`()`	é um de (lista separada por vírgula)
`!()`	não é um de

Referência — classes de condição

Nível carrinho / endereço

Magento\SalesRule\Model\Rule\Condition\Combine
Magento\SalesRule\Model\Rule\Condition\Address

Nível item, dentro de condition

Magento\SalesRule\Model\Rule\Condition\Product\Found
Magento\SalesRule\Model\Rule\Condition\Product\Subselect
Magento\SalesRule\Model\Rule\Condition\Product

Nível item, dentro de action_condition

Magento\SalesRule\Model\Rule\Condition\Product\Combine
Magento\SalesRule\Model\Rule\Condition\Product

Referência — atributos de item mais usados

sku, category_ids, attribute_set_id, quote_item_qty, quote_item_price, quote_item_row_total, parent_category_ids — mais qualquer atributo de produto habilitado para promo rules.

Observações Importantes

Regra e cupom são duas chamadas: POST /V1/salesRules cria a regra, POST /V1/coupons cria o código. Não há endpoint nativo que faça as duas coisas em uma operação.
As duas chamadas não são atômicas: se a criação do cupom falhar (código duplicado, por exemplo), a regra permanece criada e sem cupom. Trate esse caso na sua integração, seja repetindo a chamada do cupom, seja removendo a regra órfã.
Guarde o JSON de criação: é a única forma prática de montar um PUT completo depois, já que o GET não devolve condition e action_condition populados.
Atributos de produto em condições: precisam estar habilitados para condições de regra de promoção antes de serem usados no payload.
Lote de cupons é outro fluxo: exige coupon_type: 3 com use_auto_generation: true na criação da regra e a geração via POST /V1/coupons/generate.

Referências e Relacionados

Credenciais API — criação da integração e do token: os exemplos desta página pressupõem um token válido com permissão para regras de carrinho; esta doc cobre como obtê-lo.
Regras de Preço do Carrinho Avançadas: o equivalente pelo painel administrativo, útil para conferir visualmente o resultado de uma regra criada pela API.
Cupom automático por link (Auto Coupon): alternativa para aplicar cupom sem o cliente digitar o código, depois que a regra já existe.
Limitador de Requisições de API: entenda os limites de chamada da loja antes de criar regras e cupons em volume.

Caso tenha ficado alguma dúvida entre em contato com nosso time de suporte através do chat online dentro da sua loja virtual ou através do e-mail web@tryideas.com.br

Copiar para usar com IA

Este artigo foi útil?

Que bom! O que ajudou mais? O que faltou nesta página?

Opcional — seu voto já foi registrado.

Obrigado pelo seu feedback!

Regras de carrinho (Sales Rules) via REST API

Antes de começar

Conceitos e valores dos campos

1. Listar regras

2. Ler uma regra específica

3. Criar regra simples — 10% preparada para cupom

4. Criar regra com condição de carrinho — subtotal + país

5. Criar regra com condição sobre itens do carrinho

6. Criar regra com `action_condition`

7. Criar regra — valor fixo no carrinho

8. Criar regra — frete grátis acima de X

9. Atualizar regra

10. Desativar regra

11. Deletar regra

Referência — operadores

Referência — classes de condição

Referência — atributos de item mais usados

Observações Importantes

Referências e Relacionados

Artigos relacionados

Endpoints de API para integrações que tenham mais volume de alteração de preços e estoques (sem MSI)

Endpoints de API para integrações que tenham mais volume de alteração de preços e estoques (com MSI)

Endpoint SOAP para leitura em lote de preço e estoque

Guia de referência para criar um produto configurável e suas variações pela API REST, no fluxo recomendado

Limitador de Requisições de API: o que é e como protege sua loja

#Antes de começar

#Conceitos e valores dos campos

#1. Listar regras

#2. Ler uma regra específica

#3. Criar regra simples — 10% preparada para cupom

#4. Criar regra com condição de carrinho — subtotal + país

#5. Criar regra com condição sobre itens do carrinho

#6. Criar regra com action_condition

#7. Criar regra — valor fixo no carrinho

#8. Criar regra — frete grátis acima de X

#9. Atualizar regra

#10. Desativar regra

#11. Deletar regra

#Referência — operadores

#Referência — classes de condição

#Referência — atributos de item mais usados

#Observações Importantes

#Referências e Relacionados

Artigos relacionados

Endpoints de API para integrações que tenham mais volume de alteração de preços e estoques (sem MSI)

Endpoints de API para integrações que tenham mais volume de alteração de preços e estoques (com MSI)

Endpoint SOAP para leitura em lote de preço e estoque

Guia de referência para criar um produto configurável e suas variações pela API REST, no fluxo recomendado

Limitador de Requisições de API: o que é e como protege sua loja

Antes de começar

Conceitos e valores dos campos

1. Listar regras

2. Ler uma regra específica

3. Criar regra simples — 10% preparada para cupom

4. Criar regra com condição de carrinho — subtotal + país

5. Criar regra com condição sobre itens do carrinho

6. Criar regra com `action_condition`

7. Criar regra — valor fixo no carrinho

8. Criar regra — frete grátis acima de X

9. Atualizar regra

10. Desativar regra

11. Deletar regra

Referência — operadores

Referência — classes de condição

Referência — atributos de item mais usados

Observações Importantes

Referências e Relacionados