API de edição de pedidos da Shopify: como criar um fluxo seguro do início à confirmação

Por que as três etapas da API são importantes#

A edição de pedidos é uma transação, não uma atualização única. A Shopify cria uma versão calculada do pedido, permite que o app prepare alterações nessa versão e a aplica quando o app confirma a edição.

Em mais de 10 milhões de pedidos de lojas que usam a Revize, cerca de 1 em cada 19 pedidos, ou 5,2%, foi editado após o checkout (Revize, 2026). É um volume suficiente para tratar a edição como parte da operação habitual, e não como uma exceção para a equipe de atendimento.

O CalculatedOrder funciona como uma cópia de prova de uma lista de separação do depósito. Você pode adicionar e remover itens nessa cópia, conferir o resultado e então publicar uma versão final.

O momento da edição importa tanto quanto as chamadas corretas à API. Nas lojas que usam a Revize, a mediana das edições ocorre 4,6 minutos após o checkout (Revize, 2026). Se a separação começar nesse intervalo, até um código tecnicamente correto pode resultar no envio do pacote errado.

Como funciona a API de edição de pedidos da Shopify#

Na Shopify Admin API 2026-07, o fluxo é orderEditBegin, uma ou mais mutações de preparação e, por fim, orderEditCommit. As referências das mutações da Shopify aceitam o ID do pedido calculado ou o ID da sessão de edição para preparar e confirmar alterações. Este guia usa calculatedOrder.id em todo o fluxo.

1. Chame orderEditBegin com o ID do pedido da Shopify.
2. Armazene calculatedOrder.id como $calculatedOrderId.
3. Execute cada mutação de preparação com esse ID.
4. Confira os itens calculados, os totais e todos os arrays userErrors.
5. Passe o mesmo ID para orderEditCommit.

A Shopify documenta esse modelo de início, preparação e confirmação. O app precisa do escopo de acesso write_order_edits.

Uma mutação inicial mínima pode solicitar os dois objetos para diagnóstico e escolher um identificador para o restante do fluxo:

mutation BeginOrderEdit($orderId: ID!) {
  orderEditBegin(id: $orderId) {
    calculatedOrder {
      id
      lineItems(first: 50) {
        nodes {
          id
          quantity
        }
      }
    }
    orderEditSession {
      id
    }
    userErrors {
      field
      message
    }
  }
}

Pare se userErrors não estiver vazio. Uma solicitação de rede bem-sucedida prova apenas que a Shopify a recebeu, não que aceitou a operação.

O guia de edição da versão da API documenta operações de preparação para variantes, quantidades, itens personalizados, descontos em itens e linhas de frete. Consulte a referência da mutação na versão 2026-07 antes de implementar e novamente antes de mudar a versão da API.

Como implementar uma troca completa de variante#

Uma troca de variante adiciona a substituta e define como zero a quantidade do item calculado original na mesma sessão de edição. Confirme a edição somente depois que as duas operações tiverem sucesso e o resultado calculado corresponder ao que o cliente confirmou.

Imagine que um cliente comprou o tamanho M e precisa do G.

1. Inicie a edição e armazene calculatedOrder.id.
2. Adicione a variante de tamanho G usando esse ID:

mutation AddReplacement(
  $calculatedOrderId: ID!
  $variantId: ID!
  $quantity: Int!
) {
  orderEditAddVariant(
    id: $calculatedOrderId
    variantId: $variantId
    quantity: $quantity
  ) {
    calculatedLineItem {
      id
      quantity
    }
    userErrors {
      field
      message
    }
  }
}

3. Encontre o tamanho M original no pedido calculado. Use o ID do item calculado; não copie o ID de um item do pedido original sem conferir o estado calculado retornado.

4. Defina a quantidade do item original como zero:

mutation RemoveOriginal(
  $calculatedOrderId: ID!
  $lineItemId: ID!
) {
  orderEditSetQuantity(
    id: $calculatedOrderId
    lineItemId: $lineItemId
    quantity: 0
  ) {
    calculatedLineItem {
      id
      quantity
    }
    userErrors {
      field
      message
    }
  }
}

5. Consulte o pedido calculado novamente. Confirme que a variante substituta está presente, a quantidade da original é zero e os totais correspondem à confirmação do cliente.
6. Confirme a edição usando o mesmo ID do pedido calculado:

mutation CommitOrderEdit(
  $calculatedOrderId: ID!
  $notifyCustomer: Boolean!
  $staffNote: String
) {
  orderEditCommit(
    id: $calculatedOrderId
    notifyCustomer: $notifyCustomer
    staffNote: $staffNote
  ) {
    order {
      id
      updatedAt
    }
    userErrors {
      field
      message
    }
  }
}

Atenção: Não confirme a edição se a adição tiver dado certo, mas a remoção ainda não. Isso transforma uma troca em um item extra.

Rejeite cliques duplicados no botão de confirmação, registre qual etapa foi concluída e busque o pedido novamente antes de confirmar se outro processo puder tê-lo alterado.

Qual mutação usar para cada edição#

Use o fluxo de pedido calculado para alterar itens, quantidades, descontos e linhas de frete. Use orderUpdate e as mutações de cancelamento e reembolso somente para as tarefas documentadas nas respectivas referências da versão da API.

A referência de orderUpdate da versão 2026-07 cobre atributos como e-mail do cliente, endereço de entrega, tags e metafields, além de documentar a atualização de observações nos exemplos. Para alterações significativas, como adicionar ou remover itens, mudar quantidades ou modificar descontos, ela orienta o uso de orderEditBegin.

As considerações da Shopify sobre edição de pedidos informam que códigos de desconto, descontos automáticos e descontos de scripts não podem ser editados. Descontos aplicados ao pedido inteiro também não podem ser adicionados, removidos ou alterados. As mutações de desconto em itens não eliminam essas limitações.

Onde termina o alcance da API de edição de pedidos da Shopify#

A confirmação da edição e a liquidação financeira são etapas separadas. A Shopify informa que uma edição que altera o total pode deixar um saldo a pagar pelo cliente ou um valor a reembolsar.

Quando o total aumenta, busque o pedido confirmado novamente e verifique como o saldo será cobrado antes de liberá-lo para o processamento de pedidos (fulfillment). Uma resposta bem-sucedida de orderEditCommit não comprova que o pagamento foi concluído.

Quando o total diminui, a confirmação da edição não substitui um fluxo de reembolso deliberado. Calcule o valor pretendido, chame a operação de reembolso apropriada e confira a resposta. Uma edição sem diferença de valor não exige cobrança nem reembolso, mas ainda exige uma verificação final do estado do pedido.

Inscreva-se no webhook orders/edited da Shopify e busque o pedido novamente antes que um sistema posterior tome alguma medida. Webhooks sinalizam que é preciso ler o registro atual; não são motivo para confiar em uma cópia local anterior.

Não permita que um operador logístico terceirizado, ou 3PL, separe um pedido enquanto a edição ou a situação financeira estiver pendente. Teste a retenção, a regra de status do pagamento ou o sinal de liberação no sistema do depósito que efetivamente baixa os pedidos.

Como diagnosticar falhas na edição#

Comece verificando a elegibilidade, os identificadores, a validação e as alterações simultâneas. Registre o nome da mutação, o ID do pedido da Shopify, o ID de edição escolhido e o array userErrors completo, sem registrar dados sigilosos do cliente ou do pagamento.

Os requisitos de edição de pedidos da Shopify dizem que os apps precisam de write_order_edits, só podem editar itens ainda não processados e não podem editar pedidos arquivados nem pedidos feitos antes de 1º de janeiro de 2019. Por padrão, os apps têm acesso aos pedidos dos últimos 60 dias; consultar pedidos mais antigos exige read_all_orders.

Essas regras são independentes. read_all_orders amplia o acesso a registros antigos, mas não torna editável um pedido arquivado ou anterior a 2019.

Não baseie o comportamento do app em uma mensagem de erro presumida. Leia o campo e a mensagem retornados para a solicitação específica e reproduza a falha com um pedido de teste controlado.

Usar a Revize ou começar pelas APIs#

A Revize é a opção padrão mais adequada quando o objetivo é permitir que o cliente edite o próprio pedido antes do processamento; código personalizado atende à coordenação interna específica da empresa. A escolha é entre uma jornada do cliente pronta para uso e a responsabilidade por cada interface, transição e proteção do fluxo no depósito.

O código personalizado tem uma função clara quando o lojista precisa de um painel exclusivo para a equipe ou de um processo de aprovação que abrange sistemas internos. A Revize não oferece uma API geral de edição de pedidos nem uma fila de aprovação para lojistas.

As agências podem conectar acionadores documentados do Shopify Flow aos eventos de edição da Revize, usar as tags de edição e liberação da Revize na lógica de processamento de pedidos ou usar a Public Cancellation API para oferecer cancelamento em uma interface externa. A Public Cancellation API é exclusiva do Pro, exige ativação pelo suporte e aplica a janela de edição, as restrições e a política de reembolso do portal.

Entre as edições feitas após a compra em lojas que usam a Revize, 92,2% foram concluídas pelos clientes sem a ajuda de um atendente (Revize, 2026). O guia de edição de pedidos após a compra para agências aborda o levantamento necessário antes da implementação.

A disponibilidade dos recursos varia conforme o plano. Adição e troca de produtos, reembolsos em crédito na loja, recálculo de descontos, frete e tributos, mecanismo de regras, Reverse Unpaid Edits e Public Cancellation API são exclusivos do Pro, conforme detalhado na documentação de cobrança da Revize.

Instale Revize: Order Editing & Upsell quando o objetivo for oferecer uma solução funcional de autoatendimento, em vez de mais uma interface interna de edição.

Como a Revize completa o fluxo#

A Revize oferece aos clientes um fluxo de edição controlado na página de status do pedido da Shopify. O lojista define a janela, as ações disponíveis, a política de reembolso e o modo de processamento de pedidos.

Quando uma edição aumenta o total, a Revize apresenta Pagar agora e redireciona o cliente ao checkout da Shopify apenas para pagar a diferença. Se o total diminui, apresenta Reembolsar; se não muda, apresenta Confirmar. A Shopify executa o pagamento ou o reembolso, conforme descrito no fluxo do cliente da Revize.

O lojista define o prazo em Order Editing > Order edit window. O guia de configuração da janela de edição documenta durações predefinidas, durações personalizadas, horários de encerramento programados e o modo que permite editar até o processamento do pedido. Esse modo, por si só, não coloca o pedido em retenção.

No modo de processamento recomendado, a Revize aplica uma retenção ao processamento do pedido na Shopify durante a janela de edição e a libera quando a janela se encerra. Sistemas que ignoram retenções podem precisar da alternativa documentada de captura manual de pagamento. Uma tag de liberação pode, em vez disso, sinalizar a um sistema de processamento de pedidos configurado para aguardar essa tag.

A Revize verifica o estoque em tempo real, considerando a zona de entrega, antes de permitir que o cliente troque uma variante. O guia de retenção do processamento de pedidos aborda a parte do fluxo que ocorre no depósito.

O que testar nesta semana#

Teste um pedido desde o checkout até o processamento corrigido, incluindo as falhas. Uma mutação bem-sucedida em um cliente GraphQL é apenas a primeira verificação.

1. Crie um pedido representativo de desenvolvimento ou um pedido preliminar.
2. Teste uma troca sem diferença de valor, um aumento e uma redução de valor.
3. Confira userErrors após o início, cada mutação de preparação e a confirmação.
4. Confira o pedido calculado antes de confirmar a edição.
5. Verifique separadamente o tratamento da cobrança e do reembolso.
6. Envie o pedido editado pelo sistema real de processamento de pedidos.
7. Teste um pedido arquivado, um pedido antigo, tentativas simultâneas e abandono.
8. Consulte as limitações da edição nativa de pedidos da Shopify antes de habilitar o acesso em produção.