'변경 상품 주문 내역 조회' API 정보의 조회/갱신 기준

[commerce-api-naver]

Q. '변경 상품 주문 내역 조회' API 정보의 조회/갱신 기준

A. 주문건의 조회 기준 시간은 '최종 변경 일시(lastChangedDate 필드)'를 기준으로 하며 '최종 변경 구분(lastChangedType 필드)' 범례에 속한 주문 처리 시 일시가 갱신됩니다.

대상 API 호출 시 사용자가 설정한 각 파라미터 값은 대상 주문건의 아래 정보를 기준으로 합니다.

항목	요청 파라미터	주문건 내 기준 필드
조회 일시	조회 기준 시작 일시(lastChangedFrom 파라미터) 조회 기준 종료 일시(lastChangedTo 파라미터)	최종 변경 일시(lastChangedDate 필드)
주문 상태	최종 변경 구분(lastChangedType 파라미터)	최종 변경 구분(lastChangedType 필드)

주문 정보 갱신 기준

'최종 변경 일시'를 포함하여 대상 API가 반환하는 모든 주문 데이터 레코드는 '최종 변경 구분(lastChangedType 필드)' 변경 시 갱신됩니다.

'최종 변경 구분'과 '상품 주문 상태'의 차이

이는 주문건의 현재 상태에 대한 관점 차이로 일부 값은 주문건의 동일 상태를 표현합니다.
따라서 이 2가지 상태 구분 값은 필요에 따라 적절한 값을 참조하는 것을 권장합니다.

• 최종 변경 구분: 판매자 주문 처리 관점에서의 상태 값 표현
• 상품 주문 상태: 주문 라이프 사이클 관점에서의 상태 값 표현

주문 상태	최종 변경 구분 (lastChangedType 필드)	상품 주문 상태 (productOrderStatus 필드)
결제 대기	"PAY_WAITING"	"PAYMENT_WAITING"
결제 완료	"PAYED"	"PAYED"
배송지 변경	"DELIVERY_ADDRESS_CHANGED"	(N/A)
배송 희망일 변경	"HOPE_DELIVERY_INFO_CHANGED"	(N/A)
선물 수락	"GIFT_RECEIVED"	(N/A)
발송 처리	"DISPATCHED"	(N/A)
배송중	(N/A)	"DELIVERING"
배송 완료	(N/A)	"DELIVERED"
클레임 철회	"CLAIM_REJECTED"	(N/A)
클레임 요청	"CLAIM_REQUESTED"	(N/A)
클레임 완료	"CLAIM_COMPLETED"	(N/A)
교환 수거 완료	"COLLECT_DONE"	(N/A)
교환 재배송 처리	"CLAIM_REDELIVERING"	(N/A)
구매 확정	"PURCHASE_DECIDED"	"PURCHASE_DECIDED"
취소 완료	(N/A)	"CANCELED"
교환 완료	(N/A)	"EXCHANGED"
반품 완료	(N/A)	"RETURNED"
미결제 취소	(N/A)	"CANCELED_BY_NOPAYMENT"

주문 정보 갱신 매커니즘

'변경 상품 주문 내역 조회' API에서 반환하는 개별 주문 데이터 레코드(data.lastChangeStatuses 필드 배열 값)는 대상 주문건에 특정 이벤트가 발생하였을 때 일괄 갱신됩니다.
일괄 갱신은 대상 주문건에 '최종 변경 구분(lastChangedType 필드)' 범례에 해당하는 주문 처리가 발생한 경우만 해당합니다. 발생한 주문 처리 이벤트가 '최종 변경 구분' 범례에 해당하지 않는 이벤트인 경우에는 갱신되지 않습니다.

예시

주문 처리 이벤트	이벤트 발생 시각	주문의 최종 변경 구분	주문의 최종 변경 일시	주문 정보 갱신 여부
신규 주문 생성 (결제 수단: 신용 카드)	12:00:00	결제 완료 ("PAYED")	12:00:00	예
(판매자) 발주 확인	12:15:00	결제 완료 ("PAYED")	12:00:00	아니오
(판매자) 발송 처리	12:25:00	발송 처리 ("DISPATCHED")	12:25:00	예
(시스템) 배송 완료 처리	16:00:00	발송 처리 ("DISPATCHED")	12:25:00	아니오
(구매자) 구매 확정	17:45:00	구매 확정 ("PURCHASE_DECIDED")	17:45:00	예

동일 주문건의 주문 상태 값이 상이한 현상

앞서 설명한 매커니즘에 따라 일부 상황에서 동일 주문건에 대해 '변경 상품 주문 내역 조회' API와 '상품 주문 상세 내역 조회' API의 상태 값이 다르게 조회될 수 있습니다.
이러한 경우 '상품 주문 상세 내역 조회' API의 상태 값을 우선하는 것을 권장합니다.

예시

판매자의 발송 처리 시 '상품 주문 상태(productOrderStatus 필드)'는 곧바로 '배송중("DELIVERING")' 상태가 됩니다. 통상적인 주문 흐름이라면 이후 시스템에 의한 배송 완료 처리가 진행됩니다. (조건에 부합하는 경우 한정)
이때 '변경 상품 주문 내역 조회' API의 반환 결과 중 배송 완료 처리된 주문건의 '상품 주문 상태'가 일정 시간동안 '배송중' 상태로 표시될 수 있습니다.
이 경우 대상 주문건에 '최종 변경 구분' 범례에 속한 주문 이벤트가 발생하면 '상품 주문 상태' 역시 알맞은 최신의 상태 값으로 갱신됩니다.
('배송 완료("DELIVERED")' 혹은 그 이외의 값)

---

(마지막 변경일: 2025년 4월 7일)