Shopify 주문 수정 API: 안전한 시작부터 확정까지의 흐름 구현

API가 세 단계로 작동하는 이유#

주문 수정은 한 번의 업데이트가 아니라 트랜잭션입니다. Shopify는 주문의 계산된 버전을 만들고, 앱이 여기에 변경 사항을 준비하도록 한 다음, 앱이 확정할 때 그 버전을 적용합니다.

Revize를 사용하는 스토어의 주문 1,000만 건 이상을 분석한 결과, 주문 약 19건 중 1건인 5.2%가 결제 후 수정되었습니다(Revize, 2026). 주문 수정은 고객 지원에서 예외적으로 처리할 일이 아니라 일상적인 운영 흐름으로 설계할 만큼 빈번합니다.

CalculatedOrder는 창고 피킹 목록의 검토용 사본과 비슷합니다. 사본에서 품목을 추가하거나 제거하고 결과를 확인한 뒤 최종 버전 하나를 적용할 수 있습니다.

올바른 API 호출만큼 시점도 중요합니다. Revize를 사용하는 스토어에서는 주문 수정까지 걸리는 시간의 중앙값이 결제 후 4.6분입니다(Revize, 2026). 그 사이에 피킹이 시작되면 기술적으로 유효한 코드라도 잘못된 상품을 배송할 수 있습니다.

Shopify 주문 수정 API의 작동 방식#

Shopify Admin API 2026-07의 작업 흐름은 orderEditBegin, 하나 이상의 변경 준비 뮤테이션, orderEditCommit 순서입니다. Shopify의 뮤테이션 문서에 따르면 변경 준비와 확정에는 계산된 주문 ID 또는 주문 수정 세션 ID를 사용할 수 있습니다. 이 가이드에서는 일관되게 calculatedOrder.id를 사용합니다.

1. Shopify 주문 ID로 orderEditBegin을 호출합니다.
2. calculatedOrder.id를 $calculatedOrderId로 저장합니다.
3. 해당 ID로 각 변경 준비 뮤테이션을 실행합니다.
4. 계산된 품목, 합계, 모든 userErrors 배열을 확인합니다.
5. 동일한 ID를 orderEditCommit에 전달합니다.

Shopify는 이 시작, 변경 준비, 확정 방식을 문서화했습니다. 앱에는 write_order_edits 접근 범위가 필요합니다.

최소한의 시작 뮤테이션에서는 진단을 위해 두 객체를 모두 요청하되, 이후 흐름에서 사용할 식별자 하나를 선택할 수 있습니다.

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

userErrors가 비어 있지 않으면 중단합니다. 네트워크 요청이 성공했다는 것은 Shopify가 요청을 받았다는 뜻일 뿐, 작업을 수락했다는 뜻은 아닙니다.

버전별 주문 수정 가이드에는 이형 상품, 수량, 사용자 지정 품목, 품목별 할인, 배송 항목을 위한 변경 준비 작업이 나와 있습니다. 구현 전과 API 버전을 변경하기 전에 관련 2026-07 뮤테이션 참조 문서를 확인합니다.

이형 상품 교환 흐름을 완성하는 방법#

이형 상품을 교환할 때는 하나의 주문 수정 세션에서 대체 상품을 추가하고 원래 계산된 품목의 수량을 0으로 설정합니다. 두 작업이 모두 성공하고 계산 결과가 고객이 확인한 내용과 일치할 때만 확정합니다.

고객이 미디엄 사이즈를 주문했지만 라지 사이즈가 필요하다고 가정해 보겠습니다.

1. 수정을 시작하고 calculatedOrder.id를 저장합니다.
2. 해당 ID로 라지 사이즈 이형 상품을 추가합니다.

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

3. 계산된 주문에서 원래 미디엄 사이즈 품목을 찾습니다. 반환된 계산 상태를 확인하지 않은 채 원래 주문의 품목 ID를 복사하지 말고, 계산된 품목의 ID를 사용합니다.

4. 원래 품목의 수량을 0으로 설정합니다.

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

5. 계산된 주문을 다시 조회합니다. 대체 상품이 있고 원래 품목의 수량이 0이며 합계가 고객에게 확인받은 내용과 일치하는지 확인합니다.
6. 동일한 계산된 주문 ID로 확정합니다.

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

주의: 대체 상품 추가는 성공했지만 원래 품목 제거가 성공하기 전에 확정하지 마세요. 그러면 교환이 아닌 품목 추가가 됩니다.

확인 버튼의 중복 클릭을 거부하고, 완료된 단계를 기록하며, 다른 프로세스가 주문을 변경했을 가능성이 있으면 확정 전에 다시 조회합니다.

수정 유형별로 사용할 뮤테이션#

품목, 수량, 할인, 배송 항목 변경에는 계산된 주문 흐름을 사용합니다. orderUpdate, 취소, 환불 뮤테이션은 각 버전의 참조 문서에 명시된 작업에만 사용합니다.

2026-07 orderUpdate 참조 문서는 고객 이메일, 배송 주소, 태그, 메타필드 등의 속성을 다루며, 예시에서 메모 업데이트도 설명합니다. 품목 추가·제거, 수량 변경, 할인 수정과 같은 중요한 변경에는 orderEditBegin을 사용하도록 안내합니다.

Shopify의 주문 수정 고려 사항에 따르면 할인 코드, 자동 할인, 스크립트 할인은 수정할 수 없습니다. 주문 전체에 적용되는 할인도 추가, 제거, 변경할 수 없습니다. 품목별 할인 뮤테이션을 사용해도 이러한 제한은 그대로 적용됩니다.

Shopify 주문 수정 API가 처리하지 않는 범위#

수정 확정과 금전 정산은 별도로 확인해야 합니다. Shopify에 따르면 주문 총액이 바뀌면 고객에게 추가 결제가 필요하거나 환불해야 할 수 있습니다.

총액이 늘어난 경우, 주문 처리(풀필먼트)로 넘기기 전에 확정된 주문을 다시 조회하고 차액을 어떻게 받을지 확인합니다. orderEditCommit 응답이 성공했다고 해서 결제가 완료된 것으로 간주하지 마세요.

총액이 줄어든 경우, 확정만으로 환불 절차가 완료되지는 않습니다. 환불할 금액을 계산하고 적절한 환불 작업을 호출한 뒤 응답을 확인합니다. 차액이 0인 수정에는 추가 결제나 환불이 필요하지 않지만, 최종 주문 상태는 확인해야 합니다.

Shopify의 orders/edited 웹훅을 구독하고, 후속 시스템이 작업하기 전에 주문을 다시 조회합니다. 웹훅은 현재 기록을 읽으라는 신호이지, 앞서 저장한 로컬 사본을 신뢰해도 된다는 뜻이 아닙니다.

수정 상태나 결제·환불 상태가 해결되지 않은 주문은 제3자 물류업체(3PL)가 피킹하지 못하게 해야 합니다. 실제로 주문을 다운로드하는 창고 시스템에서 보류, 결제 상태 규칙 또는 처리 재개 신호를 테스트합니다.

주문 수정 실패를 진단하는 방법#

수정 가능 여부, 식별자, 유효성 검사, 동시 변경부터 확인합니다. 고객 정보나 결제 관련 비밀정보를 기록하지 않으면서 뮤테이션 이름, Shopify 주문 ID, 선택한 수정 ID, 전체 userErrors 배열을 로그에 남깁니다.

Shopify의 주문 수정 요구 사항에 따르면 앱에는 write_order_edits가 필요하고, 주문 처리되지 않은 품목만 수정할 수 있으며, 보관된 주문이나 2019년 1월 1일 이전에 접수된 주문은 수정할 수 없습니다. 기본적으로 앱은 최근 60일간의 주문에 접근할 수 있습니다. 그보다 오래된 주문을 조회하려면 read_all_orders가 필요합니다.

이는 서로 다른 규칙입니다. read_all_orders는 오래된 기록에 대한 접근 범위를 넓히지만, 보관된 주문이나 2019년 이전 주문을 수정할 수 있게 하지는 않습니다.

추측한 오류 문자열에 맞춰 앱의 동작을 구현하지 마세요. 해당 요청에서 반환된 필드와 메시지를 읽고, 통제된 테스트 주문으로 실패를 재현합니다.

Revize를 사용할지 API로 직접 구축할지 결정하기#

주문 처리 전에 고객이 직접 수정하게 하는 것이 목표라면 Revize가 기본 선택지로 적합하고, 내부 시스템에 특화된 조정이 필요하다면 맞춤 코드가 적합합니다. 고객용 흐름을 갖춘 솔루션을 사용할지, 모든 화면과 상태 전환 및 창고 보호 장치를 직접 구현할지 결정해야 합니다.

판매자가 자체 직원용 콘솔이나 내부 시스템 전반에 걸친 승인 절차가 필요하다면 맞춤 코드가 적합합니다. Revize는 범용 주문 수정 API나 판매자 승인 대기열을 제공하지 않습니다.

에이전시는 문서화된 Shopify Flow 트리거를 Revize 수정 이벤트에 연결하고, 주문 처리 로직에서 Revize 수정 및 처리 재개 태그를 사용하거나, 외부 취소 화면에 Public Cancellation API를 사용할 수 있습니다. Public Cancellation API는 Pro 전용이며, 고객 지원팀의 활성화가 필요하고, 포털의 수정 가능 기간, 제한 사항, 환불 정책을 적용합니다.

Revize를 사용하는 스토어에서 결제 후 이뤄진 주문 수정 중 92.2%는 고객이 지원 담당자 없이 완료했습니다(Revize, 2026). 에이전시를 위한 결제 후 주문 수정 운영 가이드는 구현 전에 필요한 요구 사항 조사 작업을 다룹니다.

기능 제공 여부는 요금제에 따라 다릅니다. 상품 추가 및 교환, 스토어 크레딧 환불, 할인·배송·세금 재계산, 규칙 엔진, Reverse Unpaid Edits, Public Cancellation API는 Pro 전용입니다. 자세한 내용은 Revize 요금 문서를 참고하세요.

내부 주문 수정 화면을 하나 더 만드는 대신 실제로 작동하는 고객 셀프서비스 기능이 필요하다면 Revize: Order Editing & Upsell을 설치하세요.

Revize가 작업 흐름을 완성하는 방법#

Revize는 Shopify 주문 상태 페이지에서 고객이 정해진 범위 안에서 주문을 수정할 수 있게 합니다. 판매자는 수정 가능 기간, 허용할 작업, 환불 정책, 주문 처리 방식을 설정합니다.

수정으로 총액이 늘어나면 Revize가 지금 결제를 표시하고, 고객이 차액만 결제하도록 Shopify 결제(체크아웃) 페이지로 이동시킵니다. 총액이 줄어들면 환불을, 변하지 않으면 확인을 표시합니다. Revize 고객 작업 흐름에 설명된 대로 결제 또는 환불은 Shopify가 실행합니다.

판매자는 Order Editing > Order edit window에서 기간을 설정합니다. 수정 가능 기간 설정 가이드에는 고정된 기간 선택지, 사용자 지정 기간, 예약된 마감 시점, 주문 처리 전까지 허용하는 모드가 설명되어 있습니다. 주문 처리 전까지 허용하는 모드를 선택하는 것만으로 주문이 보류되지는 않습니다.

권장 주문 처리 방식을 사용하면 Revize는 수정 가능 기간 동안 Shopify 주문 처리 보류를 적용하고, 수정이 마감되면 보류를 해제합니다. 보류를 무시하는 시스템에는 문서화된 결제 수동 승인 대체 방식이 필요할 수 있습니다. 처리 재개 태그를 기다리도록 설정된 주문 처리 시스템에는 해당 태그로 신호를 보낼 수도 있습니다.

Revize는 고객이 이형 상품을 교환하도록 허용하기 전에 배송 지역을 고려한 실시간 재고를 확인합니다. 주문 처리 보류 가이드에서 이 작업 흐름의 창고 측면을 다룹니다.

이번 주에 테스트할 항목#

실패 상황까지 포함해 결제(체크아웃)부터 수정된 주문의 처리까지 한 건을 끝까지 테스트합니다. GraphQL 클라이언트에서 뮤테이션이 성공한 것은 첫 확인 단계에 불과합니다.

1. 실제 주문을 대표하는 개발용 주문 또는 초안 주문을 생성합니다.
2. 동일 금액 교환, 금액 증가, 금액 감소를 테스트합니다.
3. 시작, 모든 변경 준비 뮤테이션, 확정 후 userErrors를 확인합니다.
4. 확정 전에 계산된 주문을 확인합니다.
5. 추가 결제와 환불 처리를 각각 확인합니다.
6. 수정된 주문을 실제 주문 처리 시스템에 전달합니다.
7. 보관된 주문, 오래된 주문, 겹치는 수정 시도, 중도 이탈을 테스트합니다.
8. 운영 환경 접근을 허용하기 전에 Shopify의 기본 주문 수정 기능 제한 사항을 검토합니다.