[공지] 필수 구매옵션 입력 의무화 및 API 변경 안내 (2026년 2월 2일 시행)

안녕하세요. 쿠팡입니다.

기존 운영되고 있는 상품정보 정책에 따라, 쿠팡이 요청하는 속성값은 판매를 위한 필수 입력사항입니다. 고객에게 더 나은 쇼핑 경험을 제공하기 위해, 신규 및 기존 등록 상품에 대해 해당 카테고리에서 요구하는 필수 구매옵션 입력 여부에 대한 모니터링을 강화할 예정입니다.

필수 구매옵션 입력이 누락된 경우, 아래와 같이 상품 노출 제한 또는 등록 실패가 발생할 수 있으니 아래 기술 변경 사항을 반드시 확인하시기 바랍니다. 본 정책은 신규 상품뿐만 아니라 기존 등록 상품에 대해서도 순차 적용됩니다.

본 문서의 업데이트 내용은 한국 마켓에만 적용되며, 대만(TW) 사용자에게는 영향을 미치지 않습니다.

1. 정책 개요

시행 일자: 2026년 2월 2일부터 순차적 적용
주요 조치 내용:
- 상품 노출 제한: 필수 구매옵션 누락 시 WING 내 '노출 제한'으로 표시되며 검색 노출이 차단될 수 있습니다.
- 상품 등록 실패: 필수 구매옵션 누락 시 API를 통한 상품 등록 요청이 거절되거나 최종 등록에 실패할 수 있습니다.

2. API 주요 변경 사항

1）상품 생성 (Product Creation)

필수 속성 누락 시 오류 원인을 명확히 식별할 수 있도록 응답 메시지가 강화되었습니다.

응답 스펙 업데이트: details 및 errorItems 필드에 "필수 구매 옵션 (미입력 시 등록/노출 제한) 존재하지 않습니다" 메시지 추가.
오류 응답 예시 (ERROR):

{
    "code": "ERROR",
    "message": "[]. 유효하지 않은 구매 옵션 값 혹은 단위가 존재합니다.",
    "details": "... 다음과 같이 필수 구매 옵션 (미입력시 등록/노출 제한)을 입력해주세요. : '총 수량'. 자세한 사항은 아래 errorItems 에서 확인할 수 있습니다.",
    "errorItems": [
        {
            "itemIndex": 0,
            "itemAttributes": [
                {
                    "attributeTypeName": "총 수량",
                    "message": "필수 구매 옵션 (미입력 시 등록/노출 제한) 존재하지 않습니다."
                }
            ]
        }
    ]
}

2）상품 수정 (승인필요) (Modify Product)

오픈 속성(Open Attributes) 관리 방식 업데이트 및 입력값 검증 로직이 강화되었습니다.

오픈 속성(Open Attributes) 관리:
- 삭제 방법: 페이로드의 attributes 리스트에서 해당 속성 요소를 제외하면 삭제됩니다.
- 식별 방법: [카테고리 메타 정보 조회 API] 응답에 해당 attributeTypeName이 없는 경우 오픈 속성으로 간주합니다.
오류 스펙 업데이트 (400 Request Variable Confirmation):
- 유효하지 않은 데이터 형식/단위 입력 시 오류 발생
- 카테고리별로 정의된 유효한 값 이외 입력 시 요청 거절

3）상품 목록 페이징 조회 (Product List Paging Query)

노출 제한된 상품을 식별하기 위한 신규 쿼리 파라미터가 추가되었습니다.

신규 파라미터:
- violationTypes (String List): 위반 유형 필터링 (NO_VA_V2, MOTA_V2, ATTR)
  - NO_VA_V2: 상품정보 검증이 필요한 상품 (노출제한)
  - MOTA_V2: 누락된 필수 구매옵션을 입력해야하는 상품 (노출제한)
  - ATTR: 옵션 수정이 필요한 상품 (노출낮음)
- violationTypeAndOr (String): 필터링 논리 연산 설정 (AND, OR)
요청 예시: GET /api/v1/marketplace/seller-products?vendorId={vendorId}&violationTypes=ATTR&violationTypes=MOTA_V2&violationTypeAndOr=OR

3. 개발자 대응 요청 사항

에러 핸들링: 상품 생성 시 반환되는 상세 errorItems 메시지를 판매자 시스템 UI에 노출하여 즉각적인 수정이 가능하도록 대응해 주십시오.
노출 제한 상품 점검: [상품 목록 페이징 조회 API]의 violationTypes 파라미터 중 하나인 "MOTA_V2"를 활용해 “필수 구매옵션이 누락”된 상품들을 조회하십시오.
수정 및 승인: 노출 제한을 해제하기 위해 [상품 수정 API]를 통해 유효한 필수 구매옵션을 입력하거나 수정해주세요. 입력/수정 시 상태가 '심사중'으로 변경되며, 승인 완료 후 정상 노출됩니다.

정확한 상품 정보 입력은 고객의 구매 전환율을 높이는 핵심 요소입니다. 판매자님의 성공이 쿠팡의 성공인 만큼, 개발자분들의 적극적인 협조 부탁드립니다.

감사합니다.

OPENAPI 관련 안내

이 섹션의 문서

1. 정책 개요

2. API 주요 변경 사항

1）상품 생성 (Product Creation)

2）상품 수정 (승인필요) (Modify Product)

3）상품 목록 페이징 조회 (Product List Paging Query)

3. 개발자 대응 요청 사항

OPENAPI 관련 안내

이 섹션의 문서

1. 정책 개요

2. API 주요 변경 사항

1）상품 생성 (Product Creation)

2）상품 수정 (승인필요) (Modify Product)

3）상품 목록 페이징 조회 (Product List Paging Query)

3. 개발자 대응 요청 사항

관련 문서