한눈에 보는 차이
sellerProductId와 productId는 모두 상품과 관련된 숫자지만 기준이 다릅니다.
| 구분 | sellerProductId | productId |
|---|---|---|
| 한국어 이름 | 등록상품ID | 노출상품ID |
| 기준 | 판매자가 등록한 상품 묶음 | 고객에게 노출되는 상품 단위 |
| 생성 시점 | 상품 생성 완료 시 | 쿠팡 노출 구조에서 부여 |
| 변경 가능성 | 공식 문서상 변경되지 않음 | 결합·분리로 바뀔 수 있음 |
| 주요 사용 | 등록 상품 조회·수정·상태 확인 | 현재 고객 노출 상품 확인 |
| 내부 장부 활용 | 등록 묶음 식별값으로 보관 | 보조값으로 함께 보관 |
sellerProductId는 등록상품ID입니다
sellerProductId는 상품 생성이 완료될 때 쿠팡이 부여합니다. 판매자가 등록한 상품 묶음을 찾는 기준입니다.
예를 들어 식기건조매트 하나를 등록하면서 그레이, 블랙, 대형, 소형 옵션을 함께 만들었다면 이 등록 전체를 하나의 sellerProductId로 조회할 수 있습니다. 하위 옵션은 각각 별도의 vendorItemId와 sellerProductItemId를 가질 수 있습니다.
sellerProductId는 다음 상황에 사용합니다.
- 내가 등록한 상품 상세 조회
- 등록 상품 상태와 승인 결과 확인
- 상품 정보 수정의 기준
- 하위 옵션 목록과 vendorItemId 확인
- Open API 상품 목록 검색
쿠팡 공식 자료에 따르면 상품 생성 응답, 상품 목록 페이징 조회, 상품 목록 구간 조회에서 sellerProductId를 확인할 수 있습니다.
productId는 노출상품ID입니다
productId는 고객이 쿠팡에서 보게 되는 상품 구조의 ID입니다. 여러 판매자가 실질적으로 같은 상품을 등록하면 쿠팡의 카탈로그 기준에 따라 하나의 노출 상품으로 결합될 수 있습니다.
반대로 기존에 함께 노출되던 상품이 서로 다른 상품으로 판단되면 분리될 수 있습니다. 공식 문서가 productId는 머지와 분리로 바뀔 수 있다고 안내하는 이유입니다.
따라서 productId는 현재 노출 상태를 확인할 때 유용하지만, 내가 영구적으로 통제하는 식별값은 아닙니다.
예시로 이해하기
판매자 A와 판매자 B가 같은 모델의 텀블러를 판매한다고 가정해보겠습니다.
| 단계 | 판매자 A | 판매자 B | 고객 노출 |
|---|---|---|---|
| 각자 상품 등록 | sellerProductId A | sellerProductId B | 아직 별도일 수 있음 |
| 쿠팡이 같은 상품으로 판단 | 등록 ID는 그대로 | 등록 ID는 그대로 | 같은 productId 아래 노출 가능 |
| 상품 정보 차이로 분리 | 등록 ID는 그대로 | 등록 ID는 그대로 | 서로 다른 productId가 될 수 있음 |
이 예시에서 판매자의 등록 이력과 고객 노출 구조는 서로 다른 층입니다. sellerProductId와 productId를 같은 값처럼 사용하면 상품 결합이나 분리 후 데이터가 끊길 수 있습니다.
어떤 값을 내부 기준으로 써야 하나요?
옵션별 매출과 재고를 관리하려면 자체 SKU와 vendorItemId를 중심으로 두는 편이 좋습니다. 등록 묶음 관리는 sellerProductId로 보완합니다.
추천 저장 구조는 다음과 같습니다.
자체 SKU
├─ sellerProductId : 등록 묶음 확인
├─ vendorItemId : 판매 옵션 확인
└─ productId : 현재 노출 상태 참고productId가 바뀌더라도 자체 SKU와 vendorItemId가 남아 있으면 기존 원가, 주문, 광고 데이터를 계속 연결하기 쉽습니다.
자주 묻는 상황별 판단
상품 조회 API를 호출하려고 합니다
등록상품ID인 sellerProductId를 사용합니다. 조회 응답에서 하위 옵션과 vendorItemId를 확인할 수 있습니다.
고객 화면의 상품이 다른 상품과 묶였습니다
현재 productId와 각 판매 옵션의 vendorItemId를 확인합니다. 등록 이력의 sellerProductId까지 함께 기록하면 문의와 변경 추적이 쉬워집니다.
광고보고서와 판매 데이터를 합치려고 합니다
productId 하나만 보지 말고 vendorItemId, sellerProductItemId, SKU 등 더 안정적인 옵션 식별값을 우선 확인합니다.
상품을 재등록했습니다
새 sellerProductId와 vendorItemId가 생길 수 있습니다. 이전 SKU와 새 ID의 연결 이력을 별도 표로 남기세요.
저장 전 체크리스트
ID 관리 점검
- sellerProductId와 productId 열을 분리했나요?
- 각 옵션의 vendorItemId를 함께 저장했나요?
- 자체 SKU가 옵션별로 고유한가요?
- productId를 영구 기본 키로 단독 사용하지 않았나요?
- 상품 결합·분리 또는 재등록 이력을 남길 칸이 있나요?
전체 ID 구조가 아직 헷갈린다면 쿠팡 SKU와 상품 ID 차이를 먼저 보고, 옵션 단위 활용은 쿠팡 옵션ID 확인과 사용처에서 이어서 확인하세요.