WEB / 웹과 전환

네이버 커머스 API, 10월 28일부로 클레임 필드명이 바뀌었다

읽는 데 7분 INSIGHTX
네이버 커머스 API, 10월 28일부로 클레임 필드명이 바뀌었다

네이버 커머스 API의 상품주문 상세내역 조회에서 취소·반품·교환 정보를 담던 cancel·return·exchange 필드가 2026년 10월 28일부로 지원이 끝났다. 같은 정보는 이제 currentClaim 하위 필드로만 내려온다. 네이버 커머스API 기술지원 저장소는 지난 7월 9일 이 일정을 다시 공지했고, 이 변경은 2024년부터 예고돼 온 것이라고 밝혔다.

정확히 어떤 필드가 바뀌었나?

대상은 상품주문 상세내역 조회 API(POST /v1/pay-order/seller/product-orders/query)다. 이 API 응답의 data 배열에서 최상위 cancel·return·exchange 필드가 사라지고, 같은 정보는 currentClaim.cancel·currentClaim.return·currentClaim.exchange로 옮겨간다. 교환은 진행 상태에 따라 beforeClaim.exchange에도 걸쳐 내려올 수 있다.

구분종료된 필드대체 필드
취소cancelcurrentClaim.cancel
반품returncurrentClaim.return
교환exchangecurrentClaim.exchange / beforeClaim.exchange

클레임 필드가 왜 전환 측정과 관련 있나?

상세페이지에서 발생한 주문은 결제 이후에도 취소·반품·교환으로 상태가 계속 바뀐다. 광고 전환값을 매출 기준으로 집계하거나 반품·취소분을 되돌려 반영하는 자동화를 이 API로 짜 두었다면, 클레임 상태를 읽는 지점이 곧 전환값 측정의 정확도를 좌우한다. 응답 구조가 바뀌는 날 연동 코드가 구 필드만 보고 있었다면, 그 시점부터 취소·반품 반영이 멈춘 것처럼 보일 수 있다.

연동 시스템에서 무엇부터 점검해야 하나?

자사 주문 연동이나 전환값 보정 스크립트가 cancel·return·exchange 키를 직접 읽고 있는지 코드로 확인하는 것이 먼저다. 그 다음 currentClaim 기준으로 분기를 바꾸고, 교환 건은 진행 상태에 따라 beforeClaim.exchange까지 함께 봐야 누락이 없다.

  • 대상 API: 상품주문 상세내역 조회(POST /v1/pay-order/seller/product-orders/query)
  • 종료 시점: 2026년 10월 28일 중(한국표준시)
  • 사전 공지: 2024년부터 예고, 2026년 7월 9일 재공지
  • 대체 구조: currentClaim(가장 최근 클레임 1건), beforeClaim.exchange(교환 재배송 중 추가 클레임 발생 시 최초 교환 정보)

점검을 놓치면 어떤 문제가 생기나?

네이버 커머스API 기술지원 저장소 공지는 종료 뒤에는 응답에 구 필드를 아예 돌려주지 않는다고 밝혔다. 연동 코드가 cancel·return·exchange 값이 없는 것을 「클레임 없음」으로 잘못 해석하면, 실제로는 취소·반품이 일어난 주문이 정상 결제로 집계될 수 있다. 전환값을 주문 상태 기준으로 자동 보정하는 구조일수록 이 오류가 광고 성과 리포트까지 그대로 번진다.

정리하면, 네이버 커머스 API는 2026년 10월 28일부로 상품주문 상세내역 조회의 cancel·return·exchange 필드 지원을 끝내고 currentClaim·beforeClaim 구조로 완전히 넘어갔다. 2024년부터 예고된 변경이지만, 상세페이지 주문 자동화나 전환값 보정 스크립트가 구 필드를 그대로 참조하고 있었다면 지금부터는 취소·반품 반영이 조용히 멈춘다. 연동 코드에서 cancel·return·exchange 키를 검색해 currentClaim 기준으로 바꾸는 것이 가장 먼저 할 점검이다.

Q & A

자주 묻는 질문

cancel·return·exchange 필드를 그대로 두면 바로 오류가 나나요?
네이버 커머스API 기술지원 저장소 공지에 따르면 2026년 10월 28일부로 응답에 해당 필드가 아예 내려오지 않습니다. 코드가 이 값을 그대로 읽던 구조라면 오류가 나기보다는 「클레임 없음」으로 조용히 잘못 처리될 가능성이 더 큽니다.
currentClaim과 beforeClaim은 어떻게 다른가요?
currentClaim은 가장 최근에 요청된 클레임 정보 한 건만 담습니다. beforeClaim.exchange는 교환 재배송 상태에서 추가 클레임이 발생했을 때, 맨 처음 요청했던 교환 클레임 정보를 따로 보여주는 필드입니다.
이 변경이 광고 전환값 측정에도 영향을 주나요?
직접적인 광고 플랫폼 변경은 아닙니다. 다만 주문 취소·반품 상태를 이 API로 읽어 전환값을 보정하는 자동화를 쓰고 있다면, 필드 구조가 바뀌는 시점에 그 보정이 끊길 수 있어 결과적으로 전환 데이터 정확도에 영향을 줍니다.
이번이 처음 예고된 변경인가요?
아닙니다. 네이버 커머스API 기술지원 저장소는 이 필드 종료가 2024년부터 예고돼 온 것이라고 밝혔고, 2026년 7월 9일 공지로 적용일을 10월 28일로 다시 확정해 알렸습니다.

← 저널 목록으로