상품

쇼핑몰 상품을 조회·등록·수정·삭제하고, 상품의 리뷰와 리뷰 통계를 읽습니다. 모든 요청은 인증된 프로젝트(쇼핑몰)의 상품만 다룹니다. 다른 프로젝트의 상품 ID 는 없는 상품과 똑같이 404 PRODUCT_NOT_FOUND 로 응답합니다.

인증·scope 는 인증, 오류 형식은 오류, page·limit 규칙은 페이지네이션을 봅니다.

공개 상품

조회 API 는 공개 상품​​만 돌려줍니다.

API 조건
목록 (GET /v1/products) 발행 상태(임시저장 아님), 노출(status_visible), 전시 중(status_display), 전시 기간을 쓰면 기간 안
상세·리뷰·리뷰 통계 발행 상태, 판매금지(status_frozen) 아님, 심사 통과(status_review 가 auto_confirm 또는 confirm). 전시 중단(status_display=false) 상품도 상세는 열립니다

쇼핑몰이 비활성 상태이면 조회 API 는 모두 442 MALL_INACTIVE 입니다.

응답의 enum 값

응답의 일부 숫자 코드는 영문 문자열로 나갑니다.

필드 값
type general_products(0), delivery_products(1), content_products(2), mobile_coupons(3), reservation_products(4), online_courses(5), crowdfunding_donation_products(7), seminars_workshops(8)
tax_type taxable(1), compound_taxation(2), tax_free(3), zero_taxation(4)
status_review auto_confirm(0), waiting(1), pending(2), confirm(3), reject(4)
discount_price_type, setup_fee_type percentage(1), fixed_price(2), count(3)
content_type, information_form_type input(1), image(2), html(3), block(4)

요청에는 괄호 안의 숫자를 보냅니다. status_review 만 숫자와 문자열을 모두 받습니다.

GET /v1/products

공개 상품 목록을 한 페이지씩 조회합니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:product_list
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

위치 이름 타입 필수 기본값 설명
query page integer 1 페이지네이션 규칙
query limit integer 20 1~100
query category_id string 이 카테고리와 그 하위 카테고리의 상품만. 형식이 잘못된 ID 는 무시합니다
query ex_uid string 외부 연동 ID 가 정확히 같은 상품만
query keyword string 상품명·SKU·바코드·검색 태그로 전문 검색
query sort string 쇼핑몰 기본 정렬 -created_at(최신순), created_at(오래된순), price(낮은 가격순), -price(높은 가격순), -sold(판매량순), position(최신순과 같음). 그 밖의 값은 쇼핑몰 기본 정렬

정렬 순서와 상관없이 판매 가능 → 판매 중단 → 품절 상품 순으로 묶여 나옵니다. 판매 이력이 없는 쇼핑몰의 -sold 는 최신순과 같습니다.

응답

200 OK

{
  "list": [
    {
      "product_id": "66f1c2a9e1b2c3d4e5f60789",
      "name": "드립백 커피 10개입",
      "desc": "매일 아침 한 잔",
      "images": ["https://.../1.jpg"],
      "type": "delivery_products",
      "display_price": 15000,
      "use_discount": true,
      "discount_price": 10,
      "discount_price_type": "percentage",
      "use_stock": true,
      "stock": 120,
      "status_display": true,
      "status_sale": true,
      "category_id": "66f1c1...",
      "ex_uid": "SKU-1001",
      "options": [],
      "option_count": 2,
      "category": {
        "_id": "66f1c1...",
        "name": "커피",
        "status_display": true,
        "status_best": false,
        "filter_color": 0,
        "filter_size": 0,
        "parent": [{ "_id": "66f1c1...", "name": "커피" }]
      },
      "subscription": null,
      "delivery_shipping": {},
      "delivery_shipping_bundle": {},
      "review_count": 12,
      "review_average": 4.5,
      "created_at": "2026-09-01T10:00:00+09:00"
    }
  ],
  "count": 37,
  "page": 1,
  "limit": 20
}json
필드 타입 설명
list array 상품 목록 (아래 상품 목록 항목​)
count integer 조건에 맞는 전체 상품 수
page integer 실제로 적용한 page
limit integer 실제로 적용한 limit

상품 목록 항목 — 주요 필드만 적습니다.

필드 타입 설명
product_id string 상품 ID
project_id, seller_id string 프로젝트·판매자 ID
name, desc string 상품명, 짧은 설명
images string[] 대표 이미지 URL
type, tax_type, content_type string 위 enum 표
display_price number 판매가(할인 전)
cost_price, tax_free_price number 원가, 면세 금액
use_discount, discount_price, discount_price_type 할인 사용 여부·값·방식
use_discount_period, discount_start_at, discount_end_at 할인 기간
use_stock, stock, use_stock_safe, stock_safe, use_option_stock 재고 설정
status_display, use_display_period, display_start_at, display_end_at 전시 상태·기간
status_sale, use_sale_period, sale_start_at, sale_end_at 판매 상태·기간
status_visible, status_frozen, status_review, save_by 노출·판매금지·심사 상태, 저장 상태(1 자동 임시저장, 2 임시저장, 3 발행)
use_option, use_product_option, use_additional_option boolean 옵션 사용 여부
use_subscription, use_subscription_times, subscription_setting_id 정기구독 상품 여부·설정
use_delivery_shipping, delivery_shipping_id, use_delivery_shipping_bundle, delivery_shipping_bundle_id 배송 템플릿
sku, barcode, tags, search_tags, event_tags, target_user_tags, delivery_tags, emotion_tags 식별·검색 태그
use_seo, seo_page_title, seo_meta_description, seo_meta_tags SEO
category_id, category 카테고리 ID, 카테고리 요약(parent 는 최상위부터 자신까지의 경로)
ex_uid string 외부 연동 ID
options array 목록에서는 빈 배열입니다. 옵션은 상세에서 확인하세요
option_count integer 옵션 수
subscription object 구독 상품일 때 구독 설정, 아니면 null
subscription_default_period, subscription_periods 구독 상품일 때 기본 기간·기간별 가격
delivery_shipping, delivery_shipping_bundle object 배송 템플릿. 쓰지 않으면 {}
review_count, review_average number 리뷰 수·평균 평점 (저장된 요약값)
created_at, updated_at string ISO 8601

오류

HTTP error_code 언제
442 MALL_INACTIVE 쇼핑몰이 비활성 상태

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-14 잘못된 page·limit 을 고쳐서 조회하고, 응답에 적용한 page·limit 을 함께 돌려줍니다
  • 2026-08-26 sort·keyword 가 무시되던 문제 수정
  • 2026-09-23 문서 최초 작성

POST /v1/products

상품을 등록합니다.

알려진 문제​: 현재 이 API 는 상품을 저장한 뒤 응답을 만드는 단계에서 500 SERVER_ERROR 를 돌려줍니다. 500 을 받아도 상품은 만들어져 있을 수 있으니, 재시도하기 전에 GET /v1/products?ex_uid=... 로 먼저 확인하세요(ex_uid 를 함께 보내면 찾기 쉽습니다).

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:product_create
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

본문은 JSON 입니다. 이미지 파일을 함께 올릴 때만 multipart/form-data 를 씁니다.

위치 이름 타입 필수 기본값 설명
body save_by integer 3 발행, 2 임시저장, 1 자동 임시저장. 3 을 보내세요 — 아래 설명
body name string 상품명
body desc string 짧은 설명
body content string 상세 설명(HTML)
body images file[] 대표 이미지 파일. 업로드에 실패하면 이미지 없이 저장됩니다
body type integer 0 상품 유형 (위 enum 표)
body tax_type integer 0 과세 유형. 보내지 않으면 0 으로 저장되니 꼭 보내세요​(보통 1 과세)
body display_price number 0 판매가
body tax_free_price number 0 면세 금액
body use_discount boolean 할인 사용
body discount_price number 0 할인 값
body discount_price_type integer 0 1 정률, 2 정액
body use_discount_period boolean 할인 기간 사용
body discount_start_at, discount_end_at string 할인 기간(ISO 8601). 둘 다 있어야 저장됩니다
body status_display boolean 전시 여부
body use_display_period boolean 전시 기간 사용
body display_start_at, display_end_at string 전시 기간. 둘 다 있어야 저장됩니다
body status_sale boolean 판매 여부
body use_sale_period boolean 판매 기간 사용
body sale_start_at, sale_end_at string 판매 기간. 둘 다 있어야 저장됩니다
body status_time_sale boolean 타임세일 사용
body time_sale_start_at, time_sale_end_at string 타임세일 기간
body time_sale_discount_percent number 0 타임세일 할인율
body use_stock boolean 재고 관리
body stock integer 0 재고 수량
body use_stock_safe, stock_safe boolean, integer 안전 재고
body use_option_stock boolean 옵션별 재고
body use_setup_fee boolean 초기 설치비 사용
body setup_fee_type, setup_fee_value integer, number 0 설치비 방식(1 정률, 2 정액)·값
body use_accumulation boolean 적립 사용
body accumulation_point, accumulation_point_type number, integer 0 적립 값·방식
body use_coupon boolean 쿠폰 적용 가능
body use_minor boolean 미성년자 구매 가능
body use_free_gift boolean 사은품 사용
body use_able_refund boolean 환불 가능
body use_able_cart boolean 장바구니 담기 가능
body use_seo boolean SEO 사용
body used boolean 중고 상품
body status_visible boolean 노출 여부
body status_review integer | string 0 심사 상태. 숫자 또는 auto_confirm·waiting·pending·confirm·reject
body category_id string 카테고리 ID. 키를 보내고 값을 비우면 카테고리 해제
body ex_uid string 외부 연동 ID. external_uid·uid 로 보내도 됩니다
body use_subscription boolean 정기구독 상품
body subscription_setting_id string 구독 설정 ID (use_subscription=true 일 때)
body use_subscription_times boolean 횟수 지정 구독
body usage_api_url string 사용량 기반 구독 상품의 사용량 조회 URL
body use_delivery_shipping boolean 배송 템플릿 사용 — 아래 제한 참고
body use_delivery_shipping_bundle boolean 묶음배송 템플릿 사용 — 아래 제한 참고
body digital_provisioning_type string 비실물 상품 지급 방식
body digital_files object[] {file_id, file_name, mime_type, size} 배열. file_id 가 빈 항목은 버립니다. 빈 배열은 전체 삭제
body digital_link_url string 지급 링크
body digital_access_code string 접근 코드
body code_distribution_mode string shared 코드 배포 방식. 코드 풀(pool) 방식이면 use_stock 이 항상 true 로 저장됩니다
body digital_instruction string 이용 안내
body digital_expires_in_days integer 이용 기한(일)
body digital_download_limit integer 다운로드 횟수 제한
body refund_policy object 환불 정책
body checkout_open_mode integer 결제창 여는 방식

save_by — 3(발행)일 때만 구독 설정·배송 템플릿 존재 확인, 사용량 URL 확인이 돌아갑니다. save_by 를 보내지 않으면 발행 상태로 저장되지만 이 확인을 건너뜁니다.

이 API 로 할 수 없는 것 — 옵션(options), 구독 기간별 가격(subscription_periods), 배송 템플릿 ID(delivery_shipping_id·delivery_shipping_bundle_id)는 받지 않습니다. 그래서 save_by=3 으로

  • use_delivery_shipping=true 또는 use_delivery_shipping_bundle=true 를 보내면 404 로 거절되고,
  • 옵션 없는 정기구독 상품은 기간별 가격이 없어 409 PRODUCT_PRICE_INVALID 로 거절됩니다.

이런 상품은 관리자에서 등록하세요.

응답

200 OK (정상 동작 시)

{
  "product_id": "66f1c2a9e1b2c3d4e5f60789",
  "save_by": 3
}json

현재는 위 알려진 문제 때문에 이 응답 대신 500 이 옵니다.

오류

HTTP error_code 언제
400 INVALID_PARAMETER status_review 를 해석할 수 없음
400 SUBSCRIPTION_SETTIGN_NEED_USAGE_API_URL 사용량 기반 구독 상품인데 usage_api_url 이 없음
400 SUBSCRIPTION_SETTING_CONSENT_TEXT_ON_DEMAND_ONLY 수시결제 구독이 아닌 상품에 자동결제 동의 문구가 있음
404 PRODUCT_SUBSCRIPTION_SETTING_NOT_FOUND use_subscription=true 인데 구독 설정을 찾을 수 없음 (save_by=3)
404 DELIVERY_SHIPPING_NOT_FOUND use_delivery_shipping=true (save_by=3)
404 DELIVERY_SHIPPING_BUNDLE_NOT_FOUND use_delivery_shipping_bundle=true (save_by=3)
409 PRODUCT_PRICE_INVALID 판매가가 0 원 이하이거나 구독 기간별 가격이 없음
500 SERVER_ERROR 위 알려진 문제

변경 이력

  • 2026-08-13 desc·content·subscription_setting_id 를 받도록 수정, save_by 를 문자열로 보내도 숫자로 처리
  • 2026-08-01 save_by 가 저장 상태에 반영되도록 수정
  • 2026-09-23 문서 최초 작성

GET /v1/products/:id

공개 상품 하나의 상세를 조회합니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:product_detail
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

위치 이름 타입 필수 기본값 설명
path id string O 상품 ID

응답

200 OK

{
  "product_id": "66f1c2a9e1b2c3d4e5f60789",
  "project_id": "66a0...",
  "javascript_key": "66a0...",
  "name": "드립백 커피 10개입",
  "display_price": 15000,
  "content": "<p>...</p>",
  "content_type": "html",
  "seller": { "seller_id": "65f0...", "company_name": "부트커피" },
  "category": { "_id": "66f1c1...", "name": "커피", "parent": [] },
  "options": [],
  "subscription": null,
  "subscription_periods": null,
  "delivery_shipping": {},
  "delivery_shipping_bundle": {},
  "digital_pool_available": null,
  "refund_policy_view": null,
  "resolved_delivery_after": 2,
  "resolved_lead_time_source": "template"
}json

목록 항목의 필드(options·option_count·review_count·review_average·subscription_default_period 제외)에 다음이 더해집니다.

필드 타입 설명
javascript_key string 이 프로젝트의 JavaScript 키 (결제창 호출용)
seller object 판매자 요약 (seller_id, company_name, email, tel 등 — 상점의 seller 와 같음)
content, content_images, content_blocks 상세 설명 본문
options array 사용 중인 옵션 목록
use_information, information_* 상품 정보 고시
model_id, model_name, brand_id, brand_name, manufacturer_id, manufacturer_name, origin_code, origin_name, importer 모델·브랜드·제조사·원산지
use_certification_array, certification_array 인증 정보
use_setup_fee, setup_fee_type, setup_fee_value, setup_fee_text, setup_fee_name 초기 설치비
usage_api_url, auto_charge_consent_text string 사용량 조회 URL, 자동결제 동의 문구
use_migrate_plan_approval, migration_candidate_ids 플랜 변경 설정
digital_provisioning_type, digital_files, digital_link_url, digital_access_code, code_distribution_mode, digital_instruction, digital_expires_in_days, digital_download_limit 비실물 상품 지급 정보
digital_pool_available integer 코드 풀 방식일 때 남은 코드 수, 아니면 null
refund_policy, refund_policy_expose_type, refund_policy_custom 환불 정책
refund_policy_view object refund_policy_expose_type=0(쇼핑몰 기본)일 때 쇼핑몰 정책을 조립한 값, 아니면 null
resolved_use_made, resolved_delivery_after, resolved_delivery_after_jeju, resolved_delivery_after_remote, resolved_expected_delivery_period_type, resolved_expected_delivery_direct_input, resolved_lead_time_source 출고 리드타임 최종값(상품 설정 우선, 없으면 배송 템플릿)

오류

HTTP error_code 언제
404 PRODUCT_NOT_FOUND 없는 ID·잘못된 형식·다른 프로젝트 상품·공개 상품이 아님
442 MALL_INACTIVE 쇼핑몰이 비활성 상태

변경 이력

  • 2026-09-14 다른 프로젝트 상품을 없는 상품과 같은 404 로 응답
  • 2026-09-23 문서 최초 작성

PUT /v1/products/:id

상품을 수정합니다. PATCH 도 같습니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:product_update
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

path 의 id(상품 ID)에 더해 POST /v1/products 와 같은 본문 필드를 받습니다(images 제외 — 이미지는 이 API 로 바꿀 수 없습니다).

보내지 않은 필드의 처리

  • 문자열·boolean 필드와 category_id·digital_files: 보내지 않으면 기존 값을 유지합니다. category_id 는 키를 보내고 값을 비우면 해제합니다.
  • 숫자 필드​(type, tax_type, display_price, tax_free_price, discount_price, discount_price_type, stock, stock_safe, setup_fee_type, setup_fee_value, accumulation_point, accumulation_point_type, time_sale_discount_percent, status_review): 보내지 않으면 0 으로 저장됩니다. 수정할 때는 현재 값을 상세에서 읽어 함께 보내세요.

판매금지(status_frozen) 상품은 수정할 수 없습니다.

응답

200 OK

{
  "product_id": "66f1c2a9e1b2c3d4e5f60789",
  "save_by": 3
}json

오류

HTTP error_code 언제
400 PRODUCT_FROZEN 판매금지된 상품
400 INVALID_PARAMETER status_review 를 해석할 수 없음
400 SUBSCRIPTION_SETTIGN_NEED_USAGE_API_URL 사용량 기반 구독 상품인데 usage_api_url 이 없음
400 SUBSCRIPTION_SETTING_CONSENT_TEXT_ON_DEMAND_ONLY 수시결제 구독이 아닌 상품에 자동결제 동의 문구가 있음
404 PRODUCT_NOT_FOUND 없는 ID 또는 다른 프로젝트 상품
404 PRODUCT_SUBSCRIPTION_SETTING_NOT_FOUND 구독 설정을 찾을 수 없음 (save_by=3)
404 DELIVERY_SHIPPING_NOT_FOUND use_delivery_shipping=true (save_by=3)
404 DELIVERY_SHIPPING_BUNDLE_NOT_FOUND use_delivery_shipping_bundle=true (save_by=3)
409 PRODUCT_PRICE_INVALID 판매가가 0 원 이하이거나 구독 기간별 가격이 없음

변경 이력

  • 2026-08-31 다른 프로젝트 상품을 수정할 수 있던 문제 수정 (이제 404)
  • 2026-08-13 category_id 를 보내지 않으면 기존 카테고리를 유지
  • 2026-08-01 응답 본문을 {product_id, save_by} 로 통일
  • 2026-09-23 문서 최초 작성

DELETE /v1/products/:id

상품을 삭제합니다. 되돌릴 수 없습니다.

전시 중이거나 판매 중인 상품, 진행 중인 정기구독이 있는 구독 상품은 지울 수 없습니다. 먼저 PUT /v1/products/:id/status 로 status_display=false, status_sale=false 로 바꾸세요.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:product_delete
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

위치 이름 타입 필수 기본값 설명
path id string O 상품 ID

응답

200 OK — 본문에 의미 있는 값이 없습니다.

오류

HTTP error_code 언제
400 PRODUCT_FROZEN 판매금지된 상품
400 PRODUCT_ACTIVE_CANNOT_BE_DELETED 전시 중·판매 중이거나 진행 중인 구독이 있음
404 PRODUCT_NOT_FOUND 없는 ID 또는 다른 프로젝트 상품

변경 이력

  • 2026-08-31 다른 프로젝트 상품을 삭제할 수 있던 문제 수정 (이제 404)
  • 2026-09-23 문서 최초 작성

PUT /v1/products/:id/status

상품의 전시·판매 상태, 기간, 재고만 바꿉니다. 다른 필드는 바뀌지 않습니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:product_status
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

위치 이름 타입 필수 기본값 설명
path id string O 상품 ID
body status_display boolean 전시 여부
body use_display_period boolean 전시 기간 사용
body display_start_at, display_end_at string 전시 기간(ISO 8601)
body status_sale boolean 판매 여부
body use_sale_period boolean 판매 기간 사용
body sale_start_at, sale_end_at string 판매 기간
body use_discount_period boolean 할인 기간 사용
body discount_start_at, discount_end_at string 할인 기간
body status_time_sale boolean 타임세일 사용
body time_sale_start_at, time_sale_end_at string 타임세일 기간
body time_sale_discount_percent number 0 타임세일 할인율
body use_stock boolean 재고 관리
body stock integer 0 재고 수량
body use_stock_safe boolean 안전 재고 사용
body stock_safe integer 0 안전 재고 수량
body use_option_stock boolean 옵션별 재고
body status_frozen boolean 판매금지
body status_review integer | string 0 심사 상태 (위 enum 표)

boolean·날짜 필드는 보내지 않으면 기존 값을 유지합니다. stock·stock_safe·time_sale_discount_percent·status_review 는 보내지 않으면 0(status_review 는 auto_confirm)으로 저장됩니다. 재고를 쓰는 상품이면 현재 재고를 함께 보내세요.

응답

200 OK — 본문에 의미 있는 값이 없습니다. 바뀐 값은 상세 API 로 확인합니다.

오류

HTTP error_code 언제
400 PRODUCT_FROZEN 판매금지된 상품
400 INVALID_PARAMETER status_review 를 해석할 수 없음
404 PRODUCT_NOT_FOUND 없는 ID 또는 다른 프로젝트 상품

변경 이력

  • 2026-08-31 다른 프로젝트 상품의 상태를 바꿀 수 있던 문제 수정 (이제 404)
  • 2026-08-27 status_review 에 enum 문자열도 받음
  • 2026-09-23 문서 최초 작성

GET /v1/products/:id/reviews

공개 상품의 리뷰 목록을 조회합니다. 숨김·삭제된 리뷰는 빠집니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • scope 검사 없음
  • 회원(선택): Bootpay-User-JWT 헤더 또는 user_id 파라미터 중 하나 — 회원 JWT. 보내면 각 리뷰의 helpful_by_me 가 그 회원 기준으로 채워집니다. 둘 다 없으면 익명으로 조회하고 helpful_by_me 는 모두 false 입니다
    • JWT 가 있으면 JWT 가 우선입니다. JWT 가 유효하지 않거나 만료됐으면 오류 없이 익명​​으로 조회합니다(같이 보낸 user_id 로 넘어가지 않습니다)
    • user_id 는 쇼핑몰 서버가 자기 로그인 세션의 회원을 지정할 때 씁니다(Basic 인증이므로 서버 호출 전용)
    • 유효한 JWT 와 user_id 가 서로 다른 회원이면 403 USER_NOT_MATCH

요청

위치 이름 타입 필수 기본값 설명
path id string O 상품 ID
query page integer 1 페이지네이션 규칙
query limit integer 20 1~100
query sort_by string recent recent(최신순), rating_high(평점 높은순), rating_low(평점 낮은순), helpful(도움돼요 많은순). 그 밖의 값은 최신순
query rating integer 이 평점(1~5) 리뷰만. 비우면 전체, 범위 밖이면 빈 목록
query photo_only string true 면 사진 리뷰만
query user_id string 뷰어 회원(선택). 24자리 ObjectId 형식이면 회원 _id, 아니면 가맹점 회원 ID(ex_uid). user_ex_uid 로 보내도 됩니다. 이 몰 회원이 아니거나 탈퇴한 회원이면 404

응답

200 OK

{
  "list": [
    {
      "product_review_id": "66f2...",
      "product_id": "66f1c2a9e1b2c3d4e5f60789",
      "user_id": "66e0...",
      "rating": 5,
      "content": "향이 좋아요",
      "is_photo_review": true,
      "helpful_count": 3,
      "images": [{ "url": "https://.../r1.jpg" }],
      "image_count": 4,
      "reply": {
        "reply_id": "66f3...",
        "content": "감사합니다",
        "created_at": "2026-09-02T09:00:00+09:00",
        "updated_at": "2026-09-02T09:00:00+09:00"
      },
      "author": "김​**",
      "option_text": "용량 200g / 분쇄 홀빈",
      "helpful_by_me": false,
      "created_at": "2026-09-01T10:00:00+09:00",
      "updated_at": "2026-09-01T10:00:00+09:00"
    }
  ],
  "count": 12,
  "page": 1,
  "limit": 20
}json
필드 타입 설명
list[].product_review_id string 리뷰 ID
list[].product_id, user_id string 상품·작성 회원 ID
list[].rating integer 평점 1~5
list[].content string 본문
list[].is_photo_review boolean 사진 리뷰 여부
list[].helpful_count integer 도움돼요 수
list[].images object[] 앞의 최대 3장 {url}
list[].image_count integer 전체 사진 수
list[].reply object 판매자 답글. 없으면 키가 빠집니다
list[].author string 표시 이름. 닉네임, 없으면 가린 실명(김​**), 둘 다 없으면 구매자
list[].option_text string 구매한 옵션 (키 값 / 키 값). 없으면 null
list[].helpful_by_me boolean 이 회원이 도움돼요를 눌렀는지
count integer 조건에 맞는 전체 리뷰 수
page, limit integer 실제로 적용한 값

오류

HTTP error_code 언제
404 PRODUCT_NOT_FOUND 없는 ID·다른 프로젝트 상품·공개 상품이 아님
404 USER_NOT_FOUND (2300) user_id 가 이 몰의 회원이 아님(없는 회원·다른 몰 회원·탈퇴 회원)
403 USER_NOT_MATCH (2302) 유효한 Bootpay-User-JWT 의 회원과 user_id 가 다름
442 MALL_INACTIVE 쇼핑몰이 비활성 상태

변경 이력

  • 2026-09-28 JWT 대신 user_id 로도 뷰어 회원을 지정할 수 있게 함(helpful_by_me). 무효 JWT 는 계속 익명(단 user_id 를 함께 보내면 그 회원)
  • 2026-09-14 page·limit 정규화(이전에는 limit=0 이 전체 조회), 빈 rating 은 필터 없음, 선택 회원 JWT 로 helpful_by_me 계산, 응답에 page·limit 추가
  • 2026-09-14 다른 프로젝트 상품의 리뷰를 읽을 수 없게 수정
  • 2026-09-23 문서 최초 작성

GET /v1/products/:id/review_stats

공개 상품의 리뷰 통계를 조회합니다. 리뷰 목록과 같은 대상(숨김·삭제 제외)으로 계산합니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • scope 검사 없음
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

위치 이름 타입 필수 기본값 설명
path id string O 상품 ID

응답

200 OK

{
  "statistics": {
    "review_count": 12,
    "review_average": 4.58,
    "review_sum": 55,
    "photo_review_count": 5
  },
  "rating_distribution": { "5": 8, "4": 3, "3": 1, "2": 0, "1": 0 }
}json
필드 타입 설명
statistics.review_count integer 전체 리뷰 수 (필터 없는 리뷰 목록의 count 와 같음)
statistics.review_average number 평균 평점 (1~5점 리뷰 기준, 소수 둘째 자리)
statistics.review_sum integer 평점 합계
statistics.photo_review_count integer 사진 리뷰 수 (photo_only=true 목록의 count 와 같음)
rating_distribution object 평점별 리뷰 수. 키는 "5"~`"1" (rating=n목록의count` 와 같음)

오류

HTTP error_code 언제
404 PRODUCT_NOT_FOUND 없는 ID·다른 프로젝트 상품·공개 상품이 아님
442 MALL_INACTIVE 쇼핑몰이 비활성 상태

변경 이력

  • 2026-09-14 상품에 저장된 요약값 대신 리뷰 목록과 같은 대상에서 계산
  • 2026-09-23 문서 최초 작성

함께 보기