AI 쇼핑 에이전트를 위한 Shopify WebMCP 결제 가이드

AI 쇼핑 에이전트가 쓰는 Shopify Checkout WebMCP란?

Checkout WebMCP는 구매자가 열어 둔 체크아웃 탭에 등록되는 툴 모음입니다. 직원이 있는 계산대를 떠올리면 이해하기 쉽습니다. 에이전트는 장바구니를 가져오고 양식을 읽어 지원되는 항목을 채울 수 있지만, 본인 확인이나 결제 인증은 여전히 구매자가 처리해야 하며 최종 진행도 구매자가 승인합니다.

이는 Shopify가 먼저 선보인 스토어프런트 툴을 체크아웃까지 확장한 것입니다. 호환되는 브라우저 에이전트는 카탈로그를 검색하고, 상품을 살펴보고, 장바구니를 수정한 뒤 proceed_to_checkout을 호출할 수 있습니다. 지원 대상 체크아웃에 들어가면 툴 목록이 바뀌며 다음 네 가지 체크아웃 툴을 사용할 수 있습니다.

• get_checkout은 현재 체크아웃을 읽습니다. Thank you 페이지에서는 주문 영수증을 읽습니다.
• update_checkout은 주문을 넣지 않은 채 지원되는 연락처, 주문 처리, 할인, 선언 필드와 결제 상태를 교체합니다.
• complete_checkout은 구매자 확인을 받은 뒤 주문 처리를 시도하거나 검토 단계를 엽니다.
• navigate_to_storefront는 스토어프런트가 있는 상점이라면 같은 탭을 그곳으로 되돌립니다.

체크아웃 구현에는 UCP의 체크아웃 객체, 상태와 메시지가 쓰입니다. UCP는 전체 흐름을 받치는 공통 데이터 계약이고, WebMCP는 브라우저가 그 계약을 에이전트에 노출하는 방식입니다. 서버 측 에이전트라면 Shopify의 Checkout MCP를 사용해야 합니다.

판매자가 새로 켤 설정도, 별도로 설치할 체크아웃 API도 없습니다. 판매자 입장에서는 도입이 쉬워지지만 에이전트 개발자의 일이 사라지는 것은 아닙니다. 브라우저 지원과 Web Bot Auth, 세심한 상태 처리, 실질적인 동의 경계가 여전히 필요합니다.

먼저 Checkout WebMCP 지원 여부를 확인합니다

첫 번째 검사는 툴 탐색입니다. 스토어프런트에서 WebMCP를 제공했다고 해서 Shopify 체크아웃에도 Checkout WebMCP가 노출된다고 가정하면 안 됩니다.

Shopify는 다음 환경에 체크아웃 툴을 등록하지 않습니다.

• 구매자가 Shop Pay를 쓰지 않는 일반 세 페이지 체크아웃
• B2B 체크아웃
• 임베디드 체크아웃 또는 모바일 체크아웃 SDK 흐름
• 다른 상점의 상품이 포함된 체크아웃
• 주문 초안, 주문 수정 또는 결제 대금 수금
• 체크아웃 UI 확장이 제공하는 상호작용

이런 경로에서는 페이지의 제어권을 구매자에게 넘겨야 합니다. 브라우저 측에는 cancel_checkout 툴도 없습니다. 툴이 보이지 않는다는 이유로 에이전트가 페이지 컨트롤을 임의로 조작해도 된다는 뜻은 아닙니다.

Shopify에 따르면 현재 스토어프런트 WebMCP는 Chromium 기반 브라우저의 에이전트 지원에 의존합니다. 테스트에는 지원되는 브라우저와 직접 관리하는 체크아웃을 사용해야 합니다. 체크아웃 툴이 없다면 정상적으로 나올 수 있는 지원 여부 판정으로 받아들이십시오. 깨지기 쉬운 클릭 자동화로 우회해서는 안 됩니다.

1. 브라우저 에이전트를 인증하고 툴을 탐색합니다

툴 인수에 자격 증명을 넣지 말고 Web Bot Auth, 즉 WBA로 브라우저 요청에 서명합니다. WBA는 네트워크 계층에서 쓰는 에이전트의 여권과 같습니다. Shopify는 등록된 키만 검증하므로 실제 운영 환경에는 Ed25519 키, 호스팅된 공개 키 디렉터리, Shopify 등록, 서명된 요청과 유효 시간이 짧은 서명 타임스탬프가 필요합니다.

페이지 안에서는 현재 툴을 탐색한 뒤 window, origin, name 세 식별자를 모두 대조해야 합니다. 아래 래퍼는 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);
}

여기서 JSON.stringify는 단순한 형식상의 선택이 아닙니다. Chrome 153에서는 객체를 그대로 넘기면 Failed to parse input arguments 오류가 납니다. Shopify는 Chrome 155부터 객체를 받을 수 있고 JSON 문자열 방식은 더 이상 권장되지 않을 것으로 예상합니다. 따라서 인수 직렬화는 에이전트 곳곳에 흩어 놓지 말고 하나의 호환성 함수 안에 두는 편이 안전합니다.

체크아웃 화면이 이동하면 툴 목록도 바뀔 수 있습니다. toolchange를 수신한 뒤 다음 호출 전에 툴과 스키마를 다시 탐색해야 합니다. 이동 결과로 null이 오는 경우도 정상 처리해야 합니다. executeTool()이 반환되기 전에 페이지가 이동했다는 뜻일 수 있습니다.

툴 결과에 들어 있는 판매자 또는 외부 주체의 모든 문자열은 체크아웃 데이터로만 취급해야 합니다. 모델에 내리는 지시로 받아들이면 안 됩니다. Shopify 역시 툴을 우회해 체크아웃 UI를 직접 조작하지 말라고 명시합니다.

2. 변경할 때마다 먼저 최신 상태를 읽습니다

첫 업데이트 전, 구매자가 페이지에서 무언가 바꾼 뒤, 오류나 화면 이동이 발생한 뒤에는 get_checkout을 {} 인수로 호출합니다. 캐시에 남은 기억이 아니라 방금 발급된 영수증을 기준으로 삼아야 합니다.

응답에는 구매자 정보, 품목, 주문 처리 옵션, 할인, 선언 필드, 결제 수단, 메시지, 합계와 상태가 포함될 수 있습니다. 금액은 해당 통화의 보조 단위를 기준으로 한 정수입니다. USD에서 10799는 $107.99를 뜻합니다. messages 필드가 없다면 해당 응답에 체크아웃 메시지가 없다는 의미입니다.

완료 준비와 구매 동의를 혼동하면 안 됩니다. ready_for_complete는 체크아웃이 완료 요청을 받을 수 있다는 뜻입니다. 구매자가 주문이나 선택된 카드, 총액을 승인했다는 뜻은 아닙니다.

3. 필드 하나가 아닌 원하는 전체 상태를 업데이트합니다

update_checkout은 PATCH가 아니라 PUT처럼 동작합니다. PATCH가 “전화번호만 바꿔 주세요”라고 적은 메모라면, PUT은 양식 전체를 새것으로 교체하는 방식입니다. 유지해야 할 값은 원하는 체크아웃 상태 전체에 반드시 포함해야 합니다.

안전한 업데이트 순서는 다음과 같습니다.

1. get_checkout을 호출합니다.
2. 방금 받은 응답과 현재 툴 스키마를 바탕으로 쓰기 가능한 상태를 다시 구성합니다.
3. 구매자가 승인한 값만 바꿉니다.
4. 지원되는 필드의 전체 목표 상태를 update_checkout으로 보냅니다.
5. 반환된 체크아웃을 읽고 상태, 메시지, 적용된 할인과 총액을 확인합니다.

생략한 값은 대부분 지워집니다. 결제, 선언 필드와 저장된 연락처 정보에는 각각 별도 규칙이 있습니다. 따라서 먼저 현재 스키마가 허용하는 필드로 제한하지 않았다면 범용 객체 스프레드를 쓰는 것은 안전하지 않습니다.

실제로 문제가 자주 생기는 지점은 다음처럼 구체적입니다.

• buyer에는 이메일과 E.164 형식의 전화번호를 넣을 수 있습니다. 저장된 값 중 일부는 잠긴 채로 남을 수 있으므로 반환값을 확인하고, 잠긴 값은 구매자가 페이지에서 직접 수정하게 해야 합니다.
• fulfillment.methods는 최대 한 가지 방식만 받습니다. 현재 목적지, 그룹과 옵션 ID를 다시 사용하십시오. 목적지나 옵션을 선택하는 호출에서 주문 처리 유형 또는 픽업 검색 출발지를 동시에 바꾸면 안 됩니다.
• discounts.codes에는 유지할 구매자 입력 코드가 모두 들어 있어야 합니다. 빈 배열을 보내면 해당 코드는 제거되지만 자동 할인은 남습니다. 코드가 응답에 돌아왔다고 실제 적용된 것은 아니므로 discounts.applied와 메시지를 확인해야 합니다.
• declared_fields에는 세금 번호나 스토어 크레딧 같은 체크아웃 전용 값을 담을 수 있습니다. 알 수 없는 키, 잘못된 유형과 유효하지 않은 값은 거부됩니다.
• payment.instruments는 지원되는 항목을 최대 하나만 받습니다. Checkout WebMCP로 새 카드 번호를 입력받을 수는 없습니다.

Shop Pay는 특히 주의해야 합니다. 로그인한 구매자는 get_checkout이 반환한 저장 카드 중 하나를 선택할 수 있습니다. 게스트 흐름에서는 체크아웃이 허용하는 경우 기존 Shop Pay 승인 ID를 사용할 수 있습니다. 에이전트가 그 승인을 적용했다면 이후 업데이트에서 결제를 생략할 때 자격 증명이 폐기됩니다. 주문이 접수될 때까지 모든 업데이트에 승인 항목을 다시 보내야 합니다.

업데이트 호출이 성공했어도 체크아웃 상태는 incomplete로 남을 수 있습니다. 업데이트가 30초 넘게 걸리면 일부 변경 사항이 적용됐더라도 update_failed가 반환될 수 있습니다. 두 경우 모두 다음 행동을 정하기 전에 최신 상태를 다시 읽어야 합니다.

4. 주문 완료 여부는 구매자가 결정하게 합니다

올바른 완료 절차는 짧고 엄격합니다.

1. 최신 체크아웃을 가져옵니다.
2. 현재 상품, 결제 방식과 총액을 구매자에게 보여 줍니다.
3. 그 총액으로 해당 주문을 넣어도 되는지 명시적으로 허락받습니다.
4. 무엇이든 달라지면 변경된 상태를 보여 주고 다시 묻습니다.
5. 승인 후에만 complete_checkout을 호출합니다.
6. 구매가 이뤄졌다는 증거로는 status: completed만 인정합니다.

WBA는 어떤 에이전트가 요청을 보냈는지 증명합니다. Shop Pay 승인은 결제 수단을 사용할 권한을 부여합니다. ready_for_complete는 체크아웃 상태를 설명합니다. 그 어느 것도 구매자의 구매 허락을 대신하지 못합니다.

완료 과정은 여러 갈래로 나뉠 수 있습니다. 검토 단계가 설정돼 있다면 제어권이 구매자에게 돌아갑니다. 구매자가 내용을 검토하고 제출을 승인한 뒤에만 complete_checkout을 다시 호출해야 합니다. 결제 인증은 다릅니다. 구매자가 같은 탭에서 인증을 끝내며 에이전트는 다시 제출하면 안 됩니다. get_checkout을 폴링해 체크아웃이 completed에 도달하거나 에이전트 입력이 필요해질 때까지 기다립니다.

오류 코드에 따라 복구 경로도 달라집니다.

가장 위험한 재시도는 첫 응답이 확실하지 않다는 이유로 완료를 다시 요청하는 것입니다. Checkout WebMCP에는 멱등성 키가 없습니다. 먼저 상태를 읽고, completed라면 중단해야 합니다.

실용 가치로 따져본 일곱 가지 활용 사례

다음 사례는 에이전트가 이미 구매자의 브라우저 안에서 작동할 때 가장 큰 효과를 냅니다. 서버에서 보이지 않게 돌아가는 판매자 측 자동화가 아닙니다.

가장 강력한 사례는 첫 번째입니다. 재방문 구매자에게는 이미 저장된 상태가 있고, WebMCP는 편리함을 동의로 둔갑시키지 않으면서 반복 입력을 줄일 수 있습니다.

실제 사업성은 어떻게 계산해야 할까?

Shopify 체크아웃 툴을 쓰기 위해 판매자가 새 설정을 추가할 필요는 없습니다. 그렇다고 이를 둘러싼 쇼핑 에이전트를 공짜로 운영할 수 있는 것은 아닙니다. 모델, 브라우저 배포, WBA 운영, 테스트, 개인정보 보호 장치와 지원이 여전히 필요합니다.

현재 판매자가 설치하는 AI 쇼핑 어시스턴트의 가격대는 매우 넓습니다. Shopify App Store 공식 등록 정보를 보면 Easy AI Shopping Assistant는 월 $9.99 요금제를, Carti는 $49~$249 요금제를 제공합니다. iAdvize는 월 $290~$1,330 요금제를 제공합니다. 이 제품들은 스토어프런트 채팅, 추천, 분석 또는 지원을 함께 제공하므로 구매자 측 WebMCP 에이전트를 직접 대체하지는 않습니다.

예산의 변화는 그보다 좁지만 더 실용적입니다. 브라우저 에이전트 팀은 상점별 체크아웃 셀렉터를 유지하는 데 드는 수고를 줄이고, 상태 무결성과 동의, 예외 처리에 더 집중할 수 있습니다. 플랫폼 전반의 맥락은 판매자 측 제품과 운영상의 장단점을 다룬 Shopify 리뷰에서 확인할 수 있습니다.

제품화할 가치가 있는 두 가지 아이디어

1. Checkout WebMCP QA 및 동의 테스트 도구

가장 유망한 기회입니다. Shopify 에이전시와 쇼핑 에이전트 팀은 에이전트에 주문을 맡기기 전에 해당 체크아웃이 지원 대상인지, 에이전트가 안전하게 동작하는지 확인해야 합니다.

실측 검색어 중 이 업무에 가장 가까운 shopify checkout customization은 미국에서 월 170회 검색되며, 전년 대비 89% 성장했고 CPC는 $10.92입니다. WebMCP 테스트보다 범위가 넓은 검색어지만 체크아웃 동작과 구현을 둘러싼 수요가 활발하다는 점은 보여 줍니다.

판매 가능한 최소 버전은 테스트 체크아웃을 여는 Chromium 러너입니다. origin과 window별로 툴을 기록하고, JSON 문자열 인수를 검증하며, toolchange를 감지하고, 최신 상태 업데이트를 테스트합니다. 화면 이동 시 null 반환과 문서화된 오류 코드를 시뮬레이션하고 익명 처리된 동의 보고서도 생성해야 합니다. 실제 결제 완료는 수동 테스트 모드로 제한합니다.

관건은 지원 범위입니다. 툴 제공 여부는 체크아웃 유형과 브라우저 지원에 따라 달라지고, Chrome의 인수 형식은 바뀌고 있으며, 픽스처만으로는 실제 결제 인계가 작동한다고 증명할 수 없습니다. 이런 한계를 분명히 드러낼 때 제품 경쟁력이 생깁니다. 모든 환경을 자동화한다고 주장해서는 안 됩니다.

2. 구매자용 Shopify 쇼핑 어시스턴트

브라우저 확장은 쇼핑객이 여러 Shopify 스토어에서 상품을 검색해 지원 대상 체크아웃에 이르기까지 안내할 수 있습니다. 재사용 가능한 확인 화면과 저장된 결제 상태를 다루는 엄격한 규칙도 제공할 수 있습니다.

shopify ai shopping assistant는 미국에서 상업적 의도로 월 30회 검색되며 CPC는 $19.43입니다. 판매자용 경쟁 제품은 월 $9.99~$1,330 요금제를 제시합니다. 이 제품은 구매자 측에 놓이겠지만, 안내형 쇼핑 소프트웨어에 이미 비용을 지불하는 시장이 있다는 점은 확인할 수 있습니다.

MVP에는 스토어프런트 검색과 장바구니 툴, 체크아웃 탐색, WBA, 읽기-업데이트-재조회 루프, 구매자가 제어하는 주문 요약과 결제 인증 인계가 필요합니다. 단일 상점 주문과 저장된 Shop Pay 경로부터 시작하는 편이 좋습니다.

관건은 배포입니다. 판매자가 Checkout WebMCP를 켤 필요는 없지만 구매자에게는 여전히 호환되는 브라우저 에이전트가 필요합니다. B2B, 임베디드, 모바일 SDK, 여러 상점이 섞인 주문과 Shop Pay를 쓰지 않는 일반 세 페이지 체크아웃은 지원 경로 밖에 있습니다.

제약이 곧 제품의 경계입니다

Checkout WebMCP는 지원 대상 브라우저 체크아웃을 위한 더 안전한 인터페이스이지, 어디에나 쓸 수 있는 구매 API가 아닙니다.

체크아웃 중 품목을 추가하거나 제거할 수 없고, 새 카드 번호를 받을 수도, 체크아웃을 취소할 수도 없습니다. 앱이 정의한 확장 UI를 조작하거나 제외 대상 체크아웃에 툴 등록을 강제할 수도 없습니다. Shop Pay 로그인, 3D Secure, 검토 단계나 그 밖의 구매자 행동도 없애 주지 않습니다. 또한 판매자가 작성한 텍스트를 모델이 믿을 수 있는 지시로 바꿔 주지도 않습니다.

정직한 설계 원칙은 간단합니다. 등록돼 있는 동안에만 툴을 사용하고, 최신 상태를 유일한 기준으로 삼으며, 계약상 구매자가 행동해야 할 때마다 페이지를 구매자에게 돌려줘야 합니다.

월요일에 바로 할 일

월요일에는 코드베이스 곳곳에 호출을 연결하지 말고 에이전트에 체크아웃 래퍼 하나를 추가하십시오. 직렬화, 툴 대조, toolchange, null 이동, 오류 분류와 최신 상태 조회를 그 안에 모읍니다. 로컬 픽스처의 여덟 가지 사례를 실행한 다음 직접 관리하는 지원 대상 테스트 체크아웃에서 document.modelContext.getTools()를 열거합니다. 최신 상태로 구성한 업데이트 하나를 실행해 보십시오. 명시적 확인을 받은 뒤 지원되는 테스트 주문만 완료해야 합니다. 안전한 테스트 주문을 직접 소유하지 않았다면 ready_for_complete에서 멈추고, 완료 기능은 출처로만 확인됐을 뿐 직접 시험하지 않았다고 다루십시오.

비즈니스에 맞는 동의 중심 커머스 에이전트가 필요하다면 AI 에이전트 개발 서비스를 확인해 보십시오.