Nesta página
A Shopify adicionou essas APIs na versão 2026-10. Adote-as quando sua integração de gerenciamento ou processamento de pedidos precisar identificar uma solicitação de cancelamento pendente do cliente antes que o lojista a processe.
Limite o envio de solicitações à remoção de unidades não processadas
A alteração permitida é a remoção. Na versão 2026-10, a entrada lineItems de orderRequestEdit contém apenas removals, cada uma com um lineItemId e a quantity solicitada. Quantidades parciais são permitidas. Não há um tipo de solicitação para adições e trocas de variantes, nem para alterações de endereço, frete ou descontos.
No fluxo nativo de contas de cliente, os compradores selecionam Cancel items em um pedido elegível. Contas de cliente legadas não são compatíveis. Os requisitos de configuração da Shopify descrevem a ativação em Settings > Customer accounts. Use o guia de migração de contas de cliente se a loja ainda usar contas legadas.
Leia Order.requestedEditInformation ao criar a interface do comprador. Seu objeto de elegibilidade disponibiliza hasEditableLineItems, editableLineItems e ineligibleLineItems. Exiba as quantidades elegíveis com base nessa resposta. Não presuma que toda unidade não processada está disponível para uma nova solicitação.
As solicitações nativas por autoatendimento também se aplicam a pedidos B2B. Processar uma solicitação para um pedido de assinatura mantém o contrato de assinatura ativo. A ativação por mercado exige Advanced ou Plus e acesso às configurações de ações de pedido em acesso antecipado no editor de checkout e contas. Lojas sem essa opção ativam as solicitações em todos os mercados.
Configure a API e as permissões
Use as referências da versão 2026-10. O recurso de solicitação é RequestedOrderEdit. Seu enum de status contém REQUESTED, RESOLVED e DECLINED. REQUESTED significa que uma ação do lojista está pendente. Não existe um estado APPROVED.
| API utilizada | Operação | Finalidade |
|---|---|---|
| Admin API | requestedOrderEditCreate |
Criar uma solicitação em nome de um comprador |
| Admin API | requestedOrderEditResolve |
Marcar uma solicitação como resolvida |
| Admin API | requestedOrderEditDecline |
Recusar uma solicitação |
| Customer Account API | orderRequestEdit |
Enviar a solicitação do comprador |
| Ambas as APIs | requestedOrderEditCalculate |
Pré-visualizar o resultado financeiro |
Para consultas na Admin API, solicite read_orders. As três mutações da Admin API exigem write_orders e a permissão de equipe edit_orders, conforme especifica a referência de criação. O fluxo de edição pelo lojista com cálculo prévio exige, separadamente, write_order_edits.
Para a mutação do comprador, solicite customer_write_pre_authenticated. O usuário também precisa de acesso customer_write_orders ou acesso pré-autenticado ao pedido. Para a consulta de pré-visualização do comprador, o aplicativo precisa de customer_read_pre_authenticated, e o usuário deve ter acesso customer_read_orders ou acesso pré-autenticado àquele pedido específico antes que você ofereça a pré-visualização. A leitura de OrderRequestedEditInformation exige customer_read_orders.
Use @idempotent em orderRequestEdit e reutilize a chave ao tentar enviar a mesma solicitação novamente. A Shopify retorna a solicitação original em vez de criar outra.
Mantenha o processamento em espera enquanto o lojista analisa
Não há uma pausa automática documentada para solicitações pendentes. O registro de alterações da Shopify descreve a pausa no processamento como uma ação que um aplicativo pode executar em pedidos com status REQUESTED.
Assine os três tópicos de webhook de solicitações: requested_order_edit/created, requested_order_edit/resolved e requested_order_edit/declined. Cada um exige pelo menos um dos escopos read_orders, read_marketplace_orders ou read_buyer_membership_orders. Os payloads identificam o pedido e as remoções solicitadas, incluindo quantity e resolved_quantity. Os status nos exemplos de webhook estão em letras minúsculas. Os valores do enum GraphQL estão em letras maiúsculas.
Se o lojista quiser pausar a separação durante a análise, implemente esta sequência na sua integração:
- Ao receber
/created, busque o pedido e a solicitação atuais. Registre o ID da solicitação junto ao pedido no depósito. - Aplique a pausa no processamento ou o mecanismo de interrupção do depósito controlado pela sua integração. Se o depósito já tiver importado o pedido, exija a confirmação de que a separação das unidades solicitadas foi interrompida.
- Ao receber
/resolvedou/declined, busque as solicitações restantes do pedido e as quantidades atuais. Libere a pausa da sua integração somente depois que as solicitações pendentes e qualquer trabalho de reembolso necessário estiverem concluídos.
Verifique todas as solicitações. Um pedido pode ter várias solicitações, e displayRequestedEditStatus = REQUESTED significa que pelo menos uma ainda precisa de uma ação do lojista. Não libere a pausa com base em um único evento /resolved.
Combine como a interrupção será confirmada antes de ativar a liberação automática. O guia de integração de pausas no processamento aborda os controles nas etapas seguintes.
Processe a remoção antes de encerrar a solicitação
No admin da Shopify, filtre Orders por Customer request. A solicitação aparece em um banner no pedido. Os responsáveis pela análise precisam da permissão Orders.
Para um pedido pago, Remove items abre a página de reembolso com os itens solicitados marcados. Selecione os itens a reembolsar, confira o valor e as opções de reposição de estoque e clique em Refund. A Shopify marca a solicitação como resolvida. Para pedidos não pagos, Remove items abre a página de reposição de estoque.
A resolução encerra o registro da solicitação. A referência de requestedOrderEditResolve descreve a operação como marcar a solicitação como concluída, e sua única entrada é o id da solicitação, sem campos de quantidade, reembolso ou reposição de estoque. Remova e reembolse as unidades separadamente e mantenha as duas operações no registro de execução da sua implementação.
Use requestedOrderEditCalculate para pré-visualizar o resultado financeiro da remoção solicitada antes do envio. A consulta retorna financialSummary e os itens calculados. Uma pré-visualização não liquida valores. Nosso guia da API de edição de pedidos aborda o fluxo existente de início, preparação e confirmação da edição e o trabalho separado de liquidação financeira.
Para recusar a solicitação, chame requestedOrderEditDecline. Seu campo opcional declineNote é uma mensagem de notificação ao comprador com limite de 500 caracteres. No admin da Shopify, Manage request > Mark as resolved encerra a solicitação sem alterar o pedido nem enviar um e-mail ao cliente. Recuse quando o lojista não aceitar a remoção. Marque como resolvida somente depois que as unidades forem removidas e reembolsadas, ou quando a solicitação tiver sido atendida de outra forma.
Comprove as transições não documentadas antes do lançamento
No admin da Shopify, reembolsar os itens solicitados resolve a solicitação, assim como cancelar o pedido, enquanto remover os itens e reembolsá-los depois mantém a solicitação aberta. A Shopify não documenta se refundCreate ou um orderEditCommit que remove as unidades solicitadas resolve a solicitação pela API. Teste se o fluxo da sua API se comporta como o admin em uma loja de desenvolvimento antes de depender desse comportamento.
Crie uma solicitação para parte da quantidade de um item não processado e processe essa quantidade pelo fluxo de reembolso ou edição pretendido, sem chamar requestedOrderEditResolve. Inspecione o status resultante da solicitação e resolvedQuantity, junto às unidades restantes do pedido e à transação de reembolso. Registre quais webhooks de solicitação chegam.
Crie outra solicitação para unidades elegíveis diferentes no mesmo pedido e teste sua rotina de liberação enquanto uma solicitação permanece pendente. Mantenha o depósito bloqueado enquanto o lojista ainda tiver uma solicitação para analisar. Se a remoção ou o reembolso falhar, mostre uma exceção visível ao lojista e mantenha o pedido bloqueado.
Para recuperação, execute uma consulta paginada de orders usando o filtro requested_order_edit_status:requested. Busque a conexão requestedOrderEdits de cada pedido encontrado e concilie-a com seus registros de solicitações. Concilie também, por ID, os pedidos que sua integração mantém em espera, pois um pedido cuja última solicitação foi encerrada sem que um webhook fosse recebido deixa de aparecer nessa busca. Defina o intervalo de verificação com base nas regras de liberação do depósito.
Escolha quem executa a alteração
Encaminhe as adições por um fluxo fora da API de solicitações do comprador. O fluxo de edição pelo lojista da Shopify permite adicionar produtos antes do processamento.
Para clientes que precisam trocar variantes, corrigir endereços ou adicionar itens dentro de uma janela de edição definida pelo lojista, as lojas usam um aplicativo de edição por autoatendimento, como a Revize. Sua configuração Hold orders, em Fulfillment while editing, mantém o processamento em espera enquanto um prazo de edição com duração definida estiver aberto e, depois, o libera conforme o momento de liberação e as condições de pagamento configurados. Com o prazo Until fulfillment, a Revize não aplica nenhuma pausa.
| Edição solicitada pelo comprador | Edição pelo lojista | Revize (aplicativo de autoatendimento) | |
|---|---|---|---|
| Quem inicia | Comprador nas contas de cliente ou por orderRequestEdit. Um aplicativo pode criar uma solicitação para o comprador |
Equipe do lojista ou um aplicativo usando a API de edição de pedidos | Comprador na página de status do pedido da Shopify |
| Quem aprova | Lojista ou aplicativo analisa e processa ou recusa a solicitação | Equipe ou aplicativo executa a edição | Lojista define previamente as ações permitidas. O cancelamento é automático quando elegível |
| O que pode mudar | Remoção de unidades não processadas, incluindo quantidades parciais. O envio da solicitação não altera nada | Produtos, quantidades, taxas de frete e descontos manuais dentro dos limites de edição nativa | Alterações de variante e quantidade, endereço de entrega e adição de produtos. A adição de produtos exige Pro |
| Pagamento | A criação e a resolução não emitem reembolso. Processar a remoção exige uma decisão sobre reembolso | O aumento do total permite uma fatura atualizada. A redução do total permite um reembolso | Pay now, Refund ou Confirm, dependendo de o total aumentar, diminuir ou permanecer igual. A Shopify executa o pagamento ou o reembolso; Pay now cobra apenas a diferença |
| Processamento | Somente unidades não processadas. Nenhuma pausa automática documentada | Alterações de quantidade e remoções: somente em itens não processados. Descontos manuais também podem ser alterados em itens já processados | Antes do processamento, dentro da janela definida pelo lojista. O modo Hold orders mantém o processamento em espera |
Configure Fulfillment while editing com o depósito antes de abrir o fluxo de edição pelo cliente. Para instruções de cancelamento voltadas ao comprador, encaminhe os clientes ao guia de cancelamento.
Perguntas frequentes
Nossa solicitação está RESOLVED, mas as unidades permanecem. A API falhou?
O status por si só não comprova a remoção. requestedOrderEditResolve marca a solicitação como concluída e aceita apenas o id da solicitação, sem campos de quantidade, reembolso ou reposição de estoque. O suporte deve inspecionar o pedido real e o registro de reembolso antes de informar ao comprador que o processamento foi concluído.
O comprador pode solicitar uma troca de tamanho por essas APIs?
Não. As entradas de solicitação da versão 2026-10 permitem apenas remoções de unidades não processadas. Encaminhe a troca de tamanho ao fluxo de edição pelo lojista ou de edição por autoatendimento do cliente da loja.
Um webhook de resolução significa que todas as solicitações daquele pedido estão encerradas?
Não. Busque requestedOrderEdits ou inspecione displayRequestedEditStatus antes de liberar o pedido no depósito. Um valor REQUESTED no nível do pedido significa que uma ação do lojista permanece pendente em pelo menos uma solicitação.
Devemos manter nossas assinaturas de cancelamento de ordens de processamento?
Mantenha-as se sua integração com o serviço de processamento precisar delas. Os tópicos fulfillment_orders/cancellation_request_* tratam de solicitações do lojista ou de um aplicativo a um serviço de processamento. As edições solicitadas pelo comprador usam requested_order_edit/* e exigem tratamento próprio.