Checkout Shopify com WebMCP: guia para agentes de IA

O que é o checkout Shopify com WebMCP

O Checkout WebMCP reúne ferramentas registradas na aba em que o cliente está finalizando a compra. Pense nele como um caixa com atendimento: o agente leva a cesta, lê o formulário e preenche os campos compatíveis, mas o cliente continua responsável por desafios de identidade ou pagamento e dá a autorização final.

Ele amplia as ferramentas que a Shopify já oferecia na vitrine. Um agente de navegador compatível pode pesquisar o catálogo, consultar produtos, atualizar o carrinho e chamar proceed_to_checkout. Quando o checkout é elegível, a lista muda e quatro ferramentas de checkout ficam disponíveis:

• get_checkout lê o checkout atual ou o comprovante do pedido na página de agradecimento.
• update_checkout substitui dados compatíveis de contato, entrega, desconto, campos declarados e pagamento sem concluir o pedido.
• complete_checkout tenta concluir o pedido — ou abre uma etapa de revisão — depois da confirmação do cliente.
• navigate_to_storefront leva a mesma aba de volta à vitrine, quando a loja tem uma.

A implementação do checkout usa o objeto, os status e as mensagens de checkout do UCP. O UCP é o contrato comum de dados por trás do fluxo; o WebMCP é o meio pelo qual o navegador expõe esse contrato a um agente. Para um agente executado no servidor, a opção adequada é o Checkout MCP da Shopify.

Não existe uma nova configuração para o lojista nem uma API de checkout separada para instalar. Isso facilita a adoção pelas lojas, mas não elimina o trabalho de quem desenvolve o agente. Ainda são necessários compatibilidade com o navegador, Web Bot Auth, tratamento cuidadoso de estado e uma fronteira real de consentimento.

Comece por um checkout elegível

A descoberta das ferramentas é o primeiro teste. Não presuma que o checkout da Shopify oferece o Checkout WebMCP só porque a vitrine disponibilizou WebMCP.

A Shopify não registra as ferramentas de checkout nos seguintes casos:

• Checkout padrão de três páginas, exceto quando o cliente finaliza com Shop Pay
• Checkout B2B
• Checkout incorporado ou fluxos de SDK de checkout móvel
• Checkout com mercadorias de outra loja
• Rascunhos de pedido, edições de pedido ou cobrança de pagamento
• Interações fornecidas por extensões da interface de checkout

Nesses fluxos, devolva ao cliente o controle da página. Também não há uma ferramenta cancel_checkout disponível no navegador. A ausência de uma ferramenta não dá ao agente permissão para manipular os controles da página.

Segundo a Shopify, o WebMCP da vitrine atualmente depende do suporte do agente em navegadores baseados em Chromium. Faça os testes em um navegador compatível e em um checkout sob seu controle. Se as ferramentas não aparecerem, trate o resultado como uma condição esperada de elegibilidade, e não como motivo para recorrer a cliques frágeis.

1. Autentique o agente de navegador e descubra as ferramentas

Assine as solicitações do navegador com Web Bot Auth, ou WBA, em vez de inserir credenciais nos argumentos das ferramentas. O WBA funciona como o passaporte do agente na camada de rede. A Shopify só verifica chaves registradas; por isso, a configuração de produção exige uma chave Ed25519, um diretório público de chaves hospedado, registro na Shopify, solicitações assinadas e timestamps de assinatura de curta duração.

Na página, descubra as ferramentas atuais e confira os três identificadores: window, origin e name. O wrapper abaixo segue o padrão de chamada documentado pela Shopify:

async function callCheckoutTool(name, args = {}) {
  const tools = await document.modelContext.getTools();
  const tool = tools.find((candidate) =>
    candidate.name === name &&
    candidate.window === window &&
    candidate.origin === location.origin
  );

  if (!tool) throw new Error(`${name} is not registered here.`);

  const result = await document.modelContext.executeTool(
    tool,
    JSON.stringify(args),
  );

  if (result === null) return null;
  return JSON.parse(result);
}

O JSON.stringify não é um detalhe cosmético. No Chrome 153, passar um objeto causa o erro Failed to parse input arguments. A Shopify informa que o Chrome 155 deve aceitar objetos e descontinuar as strings JSON. Portanto, concentre a serialização de argumentos em uma única função de compatibilidade, em vez de espalhá-la pelo agente.

A lista de ferramentas pode mudar conforme o checkout navega. Escute o evento toolchange e, antes da próxima chamada, descubra novamente as ferramentas e seus schemas. Aceite também null como resultado de navegação: a página pode ter mudado antes de executeTool() retornar.

Trate qualquer texto do lojista ou de terceiros presente no resultado de uma ferramenta como dado do checkout, nunca como instrução para o modelo. A Shopify alerta explicitamente para não contornar uma ferramenta operando diretamente a interface do checkout.

2. Leia o estado antes de qualquer alteração

Chame get_checkout com {} antes da primeira atualização, sempre que o cliente mudar algo na página e depois de um erro ou de uma navegação. Essa resposta é o comprovante atualizado do agente, não uma memória em cache.

A resposta pode trazer dados do cliente, itens, opções de entrega, descontos, campos declarados, instrumentos de pagamento, mensagens, totais e um status. Valores monetários são inteiros na unidade mínima da moeda. Em USD, 10799 significa $107.99. Se o campo messages não estiver presente, não há mensagens de checkout naquela resposta.

Não confunda prontidão com consentimento. ready_for_complete indica que o checkout pode receber uma tentativa de conclusão; não significa que o cliente aprovou o pedido, o cartão selecionado ou o total.

3. Atualize todo o estado desejado, não um campo isolado

O comportamento de update_checkout se parece com PUT, não com PATCH. PATCH seria um bilhete dizendo “troque o número de telefone”. PUT equivale a substituir o formulário inteiro. Se um valor precisa permanecer, inclua-o no estado completo que o checkout deve assumir.

O ciclo seguro de atualização é este:

1. Chame get_checkout.
2. Reconstrua o estado gravável com base nessa resposta atualizada e no schema vigente da ferramenta.
3. Altere apenas o valor aprovado pelo cliente.
4. Envie a update_checkout o conjunto completo de campos compatíveis desejados.
5. Leia o checkout retornado e verifique status, mensagens, descontos aplicados e total.

A maioria dos valores omitidos é apagada. Pagamento, campos declarados e dados de contato armazenados têm regras próprias. Por isso, fazer um spread genérico do objeto é arriscado, a menos que antes ele seja limitado aos campos aceitos pelo schema atual.

Os detalhes que mais costumam causar problemas são bem concretos:

• buyer aceita e-mail e telefone no padrão E.164. Alguns valores armazenados podem continuar bloqueados; confira o que retorna e deixe o cliente editar na página os dados que não podem ser alterados pela ferramenta.
• fulfillment.methods aceita no máximo um método. Reutilize os IDs atuais de destino, grupo e opção. Não mude o tipo de entrega nem a origem da busca por retirada na mesma chamada que seleciona um destino ou uma opção.
• discounts.codes precisa conter todos os códigos inseridos pelo cliente que devem ser mantidos. Um array vazio os remove, enquanto descontos automáticos permanecem. O simples retorno de um código não prova que ele foi aplicado; verifique discounts.applied e as mensagens.
• declared_fields pode transportar valores específicos do checkout, como um número fiscal ou crédito da loja. Chaves desconhecidas, tipos incorretos e valores inválidos são rejeitados.
• payment.instruments aceita no máximo uma entrada compatível. O Checkout WebMCP não consegue coletar um novo número de cartão.

O Shop Pay exige atenção adicional. Um cliente autenticado pode escolher um cartão salvo retornado por get_checkout. No fluxo de visitante, é possível usar um ID de aprovação existente do Shop Pay quando o checkout o aceita. Se o agente aplicou essa aprovação, omitir o pagamento em uma atualização posterior descarta a credencial. Reenvie a entrada de aprovação em todas as atualizações até que o pedido seja concluído.

Uma atualização pode terminar com sucesso enquanto o checkout continua com o status incomplete. Se levar mais de 30 segundos, também pode retornar update_failed mesmo que algumas mudanças tenham sido aplicadas. Nos dois casos, leia novamente o estado antes de decidir o próximo passo.

4. Faça da aprovação do cliente a trava de conclusão

A sequência correta para concluir a compra é curta e rigorosa:

1. Busque um checkout atualizado.
2. Mostre ao cliente os itens atuais, a forma de pagamento e o total.
3. Peça autorização explícita para concluir aquele pedido por aquele total.
4. Se algo mudar, apresente o novo estado e peça autorização outra vez.
5. Só depois da aprovação chame complete_checkout.
6. Aceite apenas status: completed como prova da compra.

O WBA comprova qual agente enviou uma solicitação. Uma aprovação do Shop Pay autoriza um mecanismo de pagamento. ready_for_complete descreve o estado do checkout. Nenhum deles representa a permissão do cliente para comprar.

A conclusão pode seguir caminhos diferentes. Uma etapa de revisão configurada devolve o controle ao cliente; só chame complete_checkout novamente depois que a pessoa revisar e autorizar o envio. Um desafio de pagamento é diferente: o cliente o conclui na mesma aba, e o agente não deve enviar outra vez. Consulte get_checkout periodicamente até o checkout chegar a completed ou exigir uma ação do agente.

O código de erro indica qual caminho de recuperação seguir:

A repetição perigosa é tentar concluir a compra de novo porque a primeira resposta foi incerta. O Checkout WebMCP não oferece uma chave de idempotência. Leia o estado antes. Se ele indicar completed, pare.

Sete casos de uso, do maior para o menor valor prático

Esses casos funcionam melhor quando o agente já está no navegador do cliente. Não são automações do lojista executadas de forma invisível em um servidor.

O primeiro caso é o mais promissor. Clientes recorrentes já têm dados salvos, e o WebMCP reduz o trabalho repetitivo sem fingir que conveniência é sinônimo de consentimento.

O que a conta do negócio realmente mostra

A Shopify não exige uma nova configuração do lojista para essas ferramentas de checkout. Isso não torna gratuito o agente de compras que as cerca. Ainda há custos de modelo, distribuição do agente no navegador, operação de WBA, testes, controles de privacidade e suporte.

Assistentes de compras com IA instalados por lojistas hoje cobrem uma ampla faixa de preço. Na Shopify App Store oficial, há um plano mensal de $9.99 do Easy AI Shopping Assistant, planos de $49 a $249 da Carti e planos da iAdvize que vão de $290 a $1,330 por mês. Esses produtos combinam chat na vitrine, recomendações, analytics ou suporte e, portanto, não substituem diretamente um agente WebMCP que atua para o cliente.

O impacto no orçamento é mais específico — e mais útil: uma equipe responsável por agentes de navegador pode gastar menos esforço mantendo seletores específicos para o checkout de cada loja e concentrar mais recursos em integridade de estado, consentimento e tratamento de exceções. Para uma visão mais ampla da plataforma, a análise da Shopify aborda o produto voltado ao lojista e seus trade-offs operacionais.

Dois produtos que vale a pena criar

1. Plataforma de testes de QA e consentimento para Checkout WebMCP

Esta é a oportunidade mais forte. Agências Shopify e equipes que criam agentes de compras precisam saber se um checkout é elegível e se o agente se comporta com segurança antes de permitir que ele lide com um pedido.

A busca com dados mensurados mais próxima desse trabalho, shopify checkout customization, recebe 170 buscas mensais nos EUA, cresceu 89% em relação ao ano anterior e tem CPC de $10.92. A consulta é mais ampla do que testes de WebMCP, mas revela demanda ativa por comportamento e implementação de checkout.

A menor versão comercializável seria um runner em Chromium que abre um checkout de teste, registra ferramentas por origem e janela, valida argumentos em string JSON, detecta toolchange, testa uma atualização a partir de estado recente, simula retornos null na navegação e os códigos de erro documentados e gera um relatório de consentimento com dados sensíveis removidos. Mantenha a conclusão com pagamento real atrás de um modo de teste manual.

O desafio é a cobertura. A disponibilidade das ferramentas depende do tipo de checkout e do suporte do navegador, o formato de argumentos do Chrome está mudando e um fixture não comprova um handoff de pagamento real. O produto se diferencia ao deixar esses limites visíveis, e não ao prometer uma automação universal.

2. Assistente de compras Shopify para o cliente

Uma extensão de navegador poderia levar o consumidor da busca de produtos até um checkout elegível em diferentes lojas Shopify, usando uma tela de confirmação reutilizável e regras rigorosas para dados de pagamento salvos.

shopify ai shopping assistant recebe 30 buscas mensais nos EUA, tem intenção comercial e CPC de $19.43. Concorrentes voltados ao lojista oferecem planos de $9.99 a $1,330 por mês. Isso mostra que já existe disposição para pagar por software de compra assistida, embora este produto fique do lado do cliente.

O MVP precisa reunir busca e carrinho na vitrine, descoberta das ferramentas de checkout, WBA, o ciclo de ler-atualizar-ler, um resumo do pedido controlado pelo cliente e a transferência de controle para desafios de pagamento. Comece com pedidos de uma única loja e fluxos do Shop Pay que usem dados salvos.

O obstáculo é a distribuição. Os lojistas não precisam ativar o Checkout WebMCP, mas o cliente ainda precisa de um agente de navegador compatível. B2B, checkout incorporado, SDK móvel, pedidos entre lojas e o checkout comum de três páginas sem Shop Pay continuam fora do fluxo.

Os limites definem o produto

O Checkout WebMCP é uma interface mais segura para checkouts elegíveis no navegador, não uma API universal de compras.

Ele não consegue adicionar ou remover itens durante o checkout, coletar um novo número de cartão, cancelar o checkout, operar interfaces definidas por extensões de apps nem forçar um checkout excluído a registrar ferramentas. Também não elimina o login do Shop Pay, 3D Secure, etapas de revisão ou outras ações do cliente. E não transforma textos do lojista em instruções confiáveis para o modelo.

A regra de design mais honesta é simples: use as ferramentas enquanto elas estiverem registradas, trate o estado atual como fonte da verdade e devolva a página ao cliente sempre que o contrato exigir que ele aja.

O passo para segunda-feira

Na segunda-feira, adicione um único wrapper de checkout ao seu agente, em vez de espalhar chamadas por toda a base de código. Centralize nele a serialização, a correspondência de ferramentas, toolchange, retornos null de navegação, a classificação de erros e as leituras de estado atualizado. Execute os oito casos do fixture local e depois enumere document.modelContext.getTools() em um checkout de teste elegível sob seu controle. Faça uma atualização construída a partir do estado atual. Só conclua um pedido de teste compatível após receber confirmação explícita; se você não tiver um pedido seguro sob seu controle, pare em ready_for_complete e trate a conclusão como verificada nas fontes, não testada pessoalmente.

Se sua empresa precisa de um agente de comércio com consentimento incorporado, conheça o serviço de desenvolvimento de agentes de IA.