쇼핑몰 상품을 조회·등록·수정·삭제하고, 상품의 리뷰와 리뷰 통계를 읽습니다. 모든 요청은 인증된 프로젝트(쇼핑몰)의 상품만 다룹니다. 다른 프로젝트의 상품 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
- JWT 가 있으면 JWT 가 우선입니다. JWT 가 유효하지 않거나 만료됐으면 오류 없이 익명으로 조회합니다(같이 보낸
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| 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 문서 최초 작성
