이 글의 목차
Shopify는 버전 2026-10에 이 API들을 추가했습니다. 주문 관리 또는 주문 처리 연동에서 판매자가 처리하기 전에 고객의 대기 중인 취소 요청을 확인해야 한다면 도입하세요.
주문 처리되지 않은 상품의 삭제만 요청하도록 제한하세요
지원되는 변경은 삭제입니다. 2026-10에서 orderRequestEdit의 lineItems 입력에는 removals만 포함되며, 각 항목에는 lineItemId와 요청한 quantity가 들어갑니다. 수량의 일부만 요청할 수도 있습니다. 상품 추가와 옵션 교체를 위한 요청 유형은 없으며, 주소, 배송, 할인 변경을 위한 요청 유형도 없습니다.
기본 고객 계정 절차에서 구매자는 조건을 충족하는 주문의 Cancel items를 선택합니다. 기존 고객 계정은 지원되지 않습니다. Shopify의 설정 요건에서는 Settings > Customer accounts에서 활성화하는 방법을 안내합니다. 스토어가 아직 기존 계정을 사용한다면 고객 계정 이전 가이드를 참고하세요.
구매자 인터페이스를 만들 때 Order.requestedEditInformation을 조회하세요. 이 필드의 요청 가능 여부 객체는 hasEditableLineItems, editableLineItems, ineligibleLineItems를 제공합니다. 이 응답을 바탕으로 요청 가능한 수량을 표시하세요. 아직 주문 처리되지 않은 모든 상품 수량에 대해 새 요청을 제출할 수 있다고 가정하지 마세요.
기본 셀프서비스 요청은 B2B 주문에도 적용됩니다. 구독 주문의 요청을 처리해도 구독 계약은 활성 상태로 유지됩니다. 마켓별로 활성화하려면 Advanced 또는 Plus가 필요하며, 결제 및 계정 편집기의 얼리 액세스 주문 작업 설정에 접근할 수 있어야 합니다. 이 옵션이 없는 스토어는 모든 마켓에서 요청 기능을 활성화합니다.
API와 권한을 연결하세요
2026-10 참조 문서를 사용하세요. 요청 리소스는 RequestedOrderEdit입니다. 이 리소스의 상태 열거형에는 REQUESTED, RESOLVED, DECLINED가 있습니다. REQUESTED는 판매자의 조치를 기다리는 상태를 뜻합니다. APPROVED 상태는 없습니다.
| 호출 주체 | 작업 | 목적 |
|---|---|---|
| Admin API | requestedOrderEditCreate |
구매자를 대신해 요청 생성 |
| Admin API | requestedOrderEditResolve |
요청을 완료로 표시 |
| Admin API | requestedOrderEditDecline |
요청 거절 |
| Customer Account API | orderRequestEdit |
구매자의 요청 제출 |
| 두 API 모두 | requestedOrderEditCalculate |
재정적 결과 미리보기 |
Admin 쿼리에는 read_orders를 요청하세요. 생성 참조 문서에 명시된 대로, Admin 뮤테이션 3개에는 write_orders와 직원의 edit_orders 권한이 필요합니다. 계산된 주문을 사용하는 판매자 수정 워크플로에는 별도로 write_order_edits가 필요합니다.
구매자 뮤테이션에는 customer_write_pre_authenticated를 요청하세요. 사용자에게도 customer_write_orders 접근 권한 또는 해당 주문에 대한 사전 인증된 접근 권한이 필요합니다. 구매자 미리보기 쿼리를 사용하려면 앱에 customer_read_pre_authenticated가 필요하며, 미리보기를 제공하기 전에 사용자에게 customer_read_orders 접근 권한 또는 해당 주문에 대한 사전 인증된 접근 권한이 있어야 합니다. OrderRequestedEditInformation을 조회하려면 customer_read_orders가 필요합니다.
orderRequestEdit에 @idempotent를 사용하고, 같은 요청 제출을 재시도할 때는 키를 재사용하세요. Shopify는 새 요청을 만드는 대신 원래 요청을 반환합니다.
판매자가 검토하는 동안 주문 처리를 보류하세요
대기 중인 요청에 자동 보류가 적용된다는 문서는 없습니다. Shopify의 변경 로그에서는 REQUESTED 상태인 주문의 주문 처리를 보류하는 것을 앱이 수행할 수 있는 작업으로 설명합니다.
요청 웹훅 토픽 3개인 requested_order_edit/created, requested_order_edit/resolved, requested_order_edit/declined를 구독하세요. 각 토픽에는 read_orders, read_marketplace_orders, read_buyer_membership_orders 중 하나 이상이 필요합니다. 페이로드는 주문과 요청된 삭제 항목을 식별하며, quantity와 resolved_quantity를 포함합니다. 웹훅 예제의 상태 값은 소문자입니다. GraphQL 열거형 값은 대문자입니다.
판매자가 검토 중에 피킹을 일시 중지하려면 연동에 다음 순서를 구현하세요.
/created를 받으면 현재 주문과 요청을 조회합니다. 창고 주문에 요청 ID를 연결해 기록합니다.- 연동에서 관리하는 주문 처리 보류 또는 창고 작업 중단 기능을 적용합니다. 창고가 이미 주문을 가져왔다면 요청된 상품 수량의 피킹이 중단되었다는 확인을 받아야 합니다.
/resolved또는/declined를 받으면 주문에 남아 있는 요청과 현재 수량을 조회합니다. 대기 중인 요청과 필요한 모든 환불 작업이 완료된 뒤에만 연동의 보류를 해제합니다.
모든 요청을 확인하세요. 주문 하나에 여러 요청이 있을 수 있으며, displayRequestedEditStatus = REQUESTED는 하나 이상의 요청에 여전히 판매자의 조치가 필요하다는 뜻입니다. /resolved 이벤트 하나만으로 보류를 해제하지 마세요.
자동 해제를 활성화하기 전에 작업 중단 확인 방식을 합의하세요. 주문 처리 보류 연동 가이드에서 후속 시스템의 통제 방법을 설명합니다.
요청을 닫기 전에 삭제를 처리하세요
Shopify 관리자에서 Orders를 Customer request로 필터링하세요. 요청은 주문의 배너에 표시됩니다. 검토 담당자에게는 Orders 권한이 필요합니다.
결제된 주문에서 Remove items를 선택하면 요청된 상품이 표시된 환불 페이지가 열립니다. 환불할 상품을 선택하고 금액과 재입고 옵션을 검토한 다음 Refund를 클릭하세요. Shopify가 요청을 완료로 표시합니다. 미결제 주문에서는 Remove items를 선택하면 재입고 페이지가 열립니다.
완료 처리는 요청 기록을 닫습니다. requestedOrderEditResolve 참조 문서는 이를 요청을 완료로 표시하는 작업으로 설명하며, 유일한 입력은 요청 id입니다. 수량, 환불, 재입고 필드는 없습니다. 상품 삭제와 환불은 별도로 실행하고, 두 작업 모두 구현의 실행 기록에 남기세요.
제출 전에 requestedOrderEditCalculate를 사용해 요청된 삭제의 재정적 결과를 미리 확인하세요. 이 쿼리는 financialSummary와 계산된 항목을 반환합니다. 미리보기는 금전 정산을 실행하지 않습니다. 주문 수정 API 가이드에서 기존의 시작, 변경 준비, 커밋 워크플로와 별도의 정산 작업을 설명합니다.
요청을 거절하려면 requestedOrderEditDecline을 호출하세요. 선택 입력인 declineNote는 구매자에게 보내는 알림 메시지이며, 최대 500자입니다. 반면 Shopify 관리자의 Manage request > Mark as resolved는 주문을 변경하거나 고객에게 이메일을 보내지 않고 요청을 닫습니다. 판매자가 삭제를 거부하면 요청을 거절하세요. 상품을 삭제하고 환불한 뒤에만, 또는 요청을 다른 방법으로 처리했을 때만 완료 처리하세요.
출시 전에 문서에 없는 상태 전환을 검증하세요
Shopify 관리자에서는 요청된 상품을 환불하거나 주문을 취소하면 요청이 완료 처리되지만, 상품을 삭제하고 나중에 환불하면 요청이 열린 상태로 남습니다. Shopify 문서에는 refundCreate 또는 요청된 상품을 삭제하는 orderEditCommit이 API를 통해 요청을 완료 처리하는지 안내되어 있지 않습니다. 해당 동작에 의존하기 전에 개발 스토어에서 API 경로가 관리자와 동일하게 작동하는지 테스트하세요.
아직 주문 처리되지 않은 항목 수량의 일부에 대해 요청을 만든 다음, requestedOrderEditResolve를 호출하지 않고 사용하려는 환불 또는 수정 경로로 해당 수량을 처리하세요. 결과로 나온 요청 상태와 resolvedQuantity를 주문의 남은 상품 수량 및 환불 거래와 함께 확인하세요. 어떤 요청 웹훅이 도착하는지 기록하세요.
같은 주문에서 요청 가능한 다른 상품 수량에 대해 요청을 하나 더 만들고, 요청 하나가 대기 중인 상태에서 보류 해제 핸들러를 실행해 보세요. 판매자에게 검토할 요청이 남아 있는 동안에는 창고 작업을 계속 차단하세요. 삭제 또는 환불이 실패하면 판매자가 확인할 수 있도록 예외를 표시하고 주문을 계속 차단하세요.
복구를 위해 필터 requested_order_edit_status:requested를 사용해 페이지 단위로 나누어 조회하는 orders 쿼리를 실행하세요. 일치하는 각 주문의 requestedOrderEdits 연결을 조회하고 보유한 요청 기록과 대조해 일치시키세요. 연동에서 보류 중인 주문도 ID로 조회해 대조하세요. 웹훅을 놓친 사이 마지막 요청이 닫힌 주문은 해당 검색 결과에서 빠지기 때문입니다. 창고의 해제 규칙에 따라 전체 점검 주기를 설정하세요.
변경을 실행할 주체를 정하세요
상품 추가는 구매자 요청 API 이외의 경로로 처리하세요. Shopify의 판매자 수정 절차는 주문 처리 전에 상품을 추가할 수 있도록 지원합니다.
판매자가 설정한 수정 가능 시간 안에 옵션 교체, 주소 수정, 상품 추가가 필요한 고객을 위해 스토어는 Revize 같은 셀프서비스 수정 앱을 사용합니다. Fulfillment while editing 아래의 Hold orders 설정은 시간 기반 수정 마감 전까지 주문 처리를 보류한 뒤, 설정된 해제 시점과 결제 조건에 따라 해제합니다. Until fulfillment 마감을 사용하면 Revize는 보류를 적용하지 않습니다.
| 구매자 요청 수정 | 판매자 수정 | Revize (셀프서비스 앱) | |
|---|---|---|---|
| 시작 주체 | 고객 계정 또는 orderRequestEdit를 사용하는 구매자. 앱이 구매자를 대신해 요청을 만들 수도 있음 |
판매자 직원 또는 주문 수정 API를 사용하는 앱 | Shopify 주문 상태 페이지의 구매자 |
| 승인 주체 | 판매자 또는 앱이 요청을 검토한 뒤 처리하거나 거절함 | 직원 또는 앱이 수정을 실행함 | 판매자가 허용할 작업을 미리 설정함. 조건을 충족하는 취소는 자동으로 처리됨 |
| 변경 가능한 항목 | 아직 주문 처리되지 않은 상품의 삭제. 수량의 일부도 가능함. 제출만으로는 아무것도 변경되지 않음 | 기본 수정 제한 내에서 상품, 수량, 배송비, 수동 할인 | 옵션 및 수량 변경, 배송 주소, 상품 추가. 상품 추가에는 Pro가 필요함 |
| 결제 | 요청 생성과 완료 처리는 환불을 실행하지 않음. 삭제를 처리하려면 환불 여부를 결정해야 함 | 총액이 늘어나면 업데이트된 인보이스를 보낼 수 있음. 총액이 줄어들면 환불할 수 있음 | 총액이 늘어나거나 줄어들거나 그대로인지에 따라 Pay now, Refund 또는 Confirm. Shopify가 결제 또는 환불을 실행하며, Pay now는 차액만 청구함 |
| 주문 처리 | 아직 주문 처리되지 않은 상품만 가능함. 자동 보류는 문서에 안내되어 있지 않음 | 수량 변경 및 삭제는 아직 주문 처리되지 않은 항목만 가능함. 수동 할인은 주문 처리된 항목에서도 변경할 수 있음 | 주문 처리 전, 판매자가 설정한 수정 가능 시간 내. Hold orders 모드는 주문 처리를 보류함 |
고객 수정 절차를 열기 전에 창고와 협의해 Fulfillment while editing을 설정하세요. 구매자용 취소 안내가 필요하면 고객에게 취소 가이드 링크를 제공하세요.
자주 묻는 질문
요청이 RESOLVED 상태인데 상품이 남아 있습니다. API가 실패한 건가요?
상태만으로는 삭제 여부를 확인할 수 없습니다. requestedOrderEditResolve는 요청을 완료로 표시하며, 요청 id만 받습니다. 수량, 환불, 재입고 필드는 없습니다. 지원팀은 구매자에게 처리가 끝났다고 안내하기 전에 실제 주문과 환불 기록을 확인해야 합니다.
구매자가 이 API로 사이즈 교체를 요청할 수 있나요?
아니요. 2026-10 요청 입력은 아직 주문 처리되지 않은 상품의 삭제만 지원합니다. 사이즈 변경은 스토어의 판매자 수정 또는 고객 셀프서비스 수정 워크플로로 처리하세요.
resolved 웹훅을 받으면 해당 주문의 모든 요청이 닫혔다는 뜻인가요?
아니요. 창고 주문의 보류를 해제하기 전에 requestedOrderEdits를 조회하거나 displayRequestedEditStatus를 확인하세요. 주문 수준의 REQUESTED 값은 하나 이상의 요청이 여전히 판매자의 조치를 기다리고 있다는 뜻입니다.
주문 처리 주문 취소 구독을 유지해야 하나요?
주문 처리 서비스 연동에 필요하다면 유지하세요. fulfillment_orders/cancellation_request_* 토픽은 판매자 또는 앱이 주문 처리 서비스에 보내는 요청에 관한 것입니다. 구매자 요청 수정은 requested_order_edit/*를 사용하며 별도의 처리가 필요합니다.