WooCommerce 11.3: as correções que mudam o que a sua API devolve

Uma chamada à API de produtos do WooCommerce que hoje devolve seis produtos vai devolver um só a partir da semana de 9 de novembro. A requisição é a mesma, o status continua 200 e não há aviso de depreciação nem erro em log. O que mudou foi o entendimento do que aquela combinação de parâmetros significa.

O WooCommerce 11.3 está em release candidate com data marcada para 9 de novembro de 2026, com 1.310 commits de 117 pessoas. A lista oficial de novidades destaca controles de estilo em blocos, selo de promoção com o valor economizado e filtro por meio de pagamento no Analytics. Nenhum desses itens é o que exige atenção. O risco está em três correções: cada uma conserta um comportamento errado, e é por isso mesmo que elas mudam o resultado de quem calibrou integração contra o comportamento antigo.

O filtro de promoção devolvia produtos que ninguém pediu

Combinar on_sale com include ou exclude nos endpoints de produto nunca funcionou direito. O código somava os IDs em promoção ao array de IDs pedidos com +=, e soma de arrays em PHP é união por chave: os dois arrays começam em zero, as chaves colidem e parte dos IDs desaparece. Além disso, o WP_Query ignora post__not_in quando post__in já está definido, então o exclude era descartado em silêncio.

O PR #69432 corrige isso. Com produtos 10 a 12 fora de promoção e 13 a 18 em promoção, a diferença fica assim:

• on_sale=true&include=10,13 devolvia 10, 13, 15, 16, 17 e 18. Passa a devolver 13.
• on_sale=false&include=10,13 devolvia 10 e 13. Passa a devolver 10.
• on_sale=true&exclude=13 devolvia 13 a 18. Passa a devolver 14 a 18.
• on_sale=false&exclude=10 devolvia 11, 12 e 13. Passa a devolver 11 e 12.

A mudança alcança /wc/v2/products, /wc/v3/products, /wc/v3/products/<id>/variations, /wc/v4/products (com a feature rest-api-v4 ligada) e o /wc/store/v1/products da Store API. Cada parâmetro usado isoladamente continua igual.

Quem sente primeiro é feed de preço para Google Merchant ou Meta, app mobile que monta vitrine de ofertas e régua de e-mail disparada sobre uma lista de itens em desconto. O comportamento antigo misturava produtos fora de promoção na consulta, e muita integração aprendeu a filtrar de novo do lado de fora. Essas vão receber menos itens do que esperam, sem erro para disparar alerta. Monitoramento de status HTTP não vê nada; monitoramento de contagem vê o número cair e procura a causa em cache ou estoque, não numa correção de API.

Reembolso por API passa a ser recusado em vez de gravado errado

O POST /wp-json/wc/v3/orders/{order_id}/refunds com valores explícitos em line_items não era validado contra o pedido. A partir do 11.3 é, e a recusa vem com código próprio:

• woocommerce_rest_refund_total_exceeds_line, HTTP 422: a linha pede mais do que o total original daquele item.
• woocommerce_rest_refund_total_exceeds_remaining, HTTP 422: a linha pede mais do que o saldo reembolsável restante do item, mesmo que o pedido como um todo ainda tenha saldo.
• woocommerce_rest_invalid_refund_amount, HTTP 400: a soma das linhas passa do amount declarado.

As regras incluem ainda sinal correto por linha (valor negativo só em linha negativa, como taxa de desconto), item pertencente ao pedido reembolsado e comparação na precisão de moeda da loja. Requisição só com quantidade mantém o comportamento anterior, e sucesso continua 201.

Isso é defesa, não regressão: antes dessa validação, um valor errado virava um reembolso errado gravado no pedido. Mas ela aparece como falha em quem já operava fora da regra. ERP que arredonda diferente do WooCommerce, hub de marketplace que rateia frete por conta própria e rotina de assinatura que reembolsa proporcional ao período usado são os candidatos naturais. Vale verificar o que a integração faz diante de um 422: repetir a mesma requisição não muda o resultado, e fila de retry cega transforma um reembolso recusado em laço infinito.

A coluna nova no Analytics tem custo de janela de manutenção

Para o relatório filtrar por meio de pagamento, a tabela wc_order_stats ganha uma coluna payment_method anulável e o índice idx_payment_method_date_paid_status. A documentação de release estima cerca de 47 MB de índice por 1 milhão de pedidos e avisa que, em MySQL 5.7, adicionar a coluna reconstrói a tabela.

Os pedidos antigos são preenchidos depois, em segundo plano, pela função wc_update_1130_backfill_order_stats_payment_method(), em lotes de 500 pedidos via Action Scheduler. Numa loja com 3 milhões de pedidos, são 6 mil execuções competindo com a fila que já existe (e-mail, sincronização, webhook) e cerca de 140 MB de índice a mais. Até o backfill terminar, o relatório por meio de pagamento está incompleto por construção, o que é bom saber antes de alguém levar o número para uma reunião.

Há um detalhe que quebra código existente: callbacks de woocommerce_analytics_clauses_* que fazem join com wc_orders e citam payment_method sem prefixo de tabela passam a receber erro de coluna ambígua, porque agora o nome existe nas duas tabelas. Quem mantém cláusula customizada precisa qualificar a coluna. Os novos argumentos de consulta são payment_method_is e payment_method_is_not, em reports/orders e reports/orders/stats.

O resto da lista, incluindo o endpoint de MCP que sai

O endpoint /wp-json/woocommerce/mcp, já depreciado, é removido no 11.3, junto com o caminho de conexão por chave da REST API. O MCP Adapter e a Abilities API deixam de vir empacotados com o WooCommerce: o cliente passa a usar o plugin MCP Adapter do WordPress com application password, e as abilities de produto e pedido ficam ligadas por padrão. O post sobre o MCP Adapter dá o contexto de por que essa separação importa para credencial de agente.

Outros dois pontos merecem atenção antes de subir:

• is_vat_exempt e calculated_shipping agora persistem quando a conta do cliente é salva. Antes voltavam para false: código que contava com esse reset precisa definir o valor nos dois sentidos.
• A tela de relatórios legados começa a ser escondida, mas só em lojas instaladas já no 11.3.0, e o filtro woocommerce_show_legacy_reports_menu controla isso.

O 11.3 também passa a exibir aviso no admin para lojas em PHP antigo, preparando a exigência de PHP 8.1 que entra no 11.6. Vale cruzar isso com o fim do suporte ao PHP 8.2 em 31 de dezembro: são duas pressões no mesmo trimestre.

O que testar nesta semana

• Levantar toda chamada a /products e /variations que combine on_sale com include ou exclude, e comparar contagem de itens em staging com 11.3 contra a produção atual.
• Reproduzir em staging os reembolsos parciais reais do último mês, com os mesmos payloads, olhando o código de erro e não só o status.
• Medir o tempo do ALTER numa cópia do banco de produção, com atenção redobrada se o servidor ainda roda MySQL 5.7.
• Procurar payment_method sem prefixo de tabela nos callbacks de woocommerce_analytics_clauses_* do tema e dos plugins próprios.

A página de novidades classifica quase tudo isso como correção, e tecnicamente está certa: o comportamento antigo era o defeito. Só que, numa operação que fatura por API, uma correção que muda a resposta é indistinguível de uma regressão até alguém comparar o antes e o depois. Essa comparação custa algumas horas de staging nesta semana. Na semana de 9, custa o tempo de descobrir por que o feed encolheu.

---

Fontes: WooCommerce 11.3: What’s coming for developers (developer.woocommerce.com, 26/10/2026), PR #69432 (correção de on_sale com include e exclude), PR #69302 (validação de reembolso na REST), PR #68970 (meio de pagamento no Analytics), issue #67952 (release 11.3.0-rc.1, data de 09/11/2026) e a página de advisories do WooCommerce.