회원의 관심상품(찜) 목록입니다. 모든 API 가 회원 전용이라 Basic 인증과 회원 지정이 필수입니다. 회원은 회원 JWT(Bootpay-User-JWT) 또는 user_id 중 하나로 정합니다.
user_id는 쇼핑몰 서버가 자기 로그인 세션의 회원 ID 를 넣어 보냅니다(쿼리 또는 본문). 24자리 회원 ID 면 Bootpay 회원 ID, 그 밖의 값은 이 몰의 외부 회원 ID(ex_uid)로 찾습니다.user_ex_uid·user_external_uid·user_uid도 같은 뜻입니다.user_id는 secretKey 인증(Basic·Bearer)일 때만 받습니다. 브라우저가 보낸 값을 그대로 넘기지 마세요 — 인증 — 호출 구조.둘 다 보내면 JWT 가 우선이고, 서로 다른 회원이면 403
USER_NOT_MATCH입니다.회원 한 명이 한 쇼핑몰에 찜할 수 있는 항목은 최대 100개입니다.
같은 상품·옵션 조합은 한 번만 찜할 수 있습니다.
찜 항목 ID(
wishlist_id)는GET /v1/wishlist응답에 있습니다.
GET /v1/wishlist
찜 목록을 최근에 찜한 순서로 돌려줍니다. 페이지네이션은 없습니다(최대 100개).
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:wishlist_list - 회원: JWT 또는 user_id 필수 —
Bootpay-User-JWT헤더 또는user_id(쇼핑몰 서버 지정) — 회원 JWT
요청
파라미터 없음.
응답
200 OK
{
"wishlist_items": [
{
"wishlist_id": "66f3...",
"product_id": "65b2...",
"product_option_id": null,
"product_name": "드립백 커피 10입",
"product_option_name": null,
"image": "https://...",
"price": 12000,
"available": true,
"unavailable_label": null
}
],
"total_items": 1
}json| 필드 | 타입 | 설명 |
|---|---|---|
| wishlist_items[].wishlist_id | string | 찜 항목 ID. 삭제·장바구니 이동에 사용 |
| wishlist_items[].product_id | string | 상품 ID |
| wishlist_items[].product_option_id | string|null | 옵션 ID |
| wishlist_items[].product_name | string|null | 현재 상품명. 상품이 삭제됐으면 null |
| wishlist_items[].product_option_name | string|null | 옵션명 |
| wishlist_items[].image | string|null | 대표 이미지 URL |
| wishlist_items[].price | number | 현재 상품 가격(할인 중이면 할인가). 옵션가 미포함 |
| wishlist_items[].available | boolean | 지금 구매할 수 있는지 |
| wishlist_items[].unavailable_label | string|null | 구매 불가 사유: 판매중단(삭제·판매중지) 또는 품절 |
| total_items | integer | 항목 수 |
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 401 | USER_SESSION_INVALID |
JWT·user_id 가 모두 없거나 JWT 세션이 끝남 |
| 403 | USER_NOT_MATCH |
JWT 와 user_id 가 서로 다른 회원 |
| 404 | USER_NOT_FOUND |
user_id 가 이 몰의 회원이 아니거나 탈퇴한 회원 |
| 400 | API_PARAM_INVALID |
clientKey 만으로 인증한 요청에 user_id 를 보냄 (payload.reason: merchant_auth_required) |
| 401 | USER_JWT_INVALID |
JWT 서명이 틀렸거나 만료됨 |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-28 회원을 JWT 또는
user_id(쇼핑몰 서버 지정)로 정할 수 있게 변경 - 2026-09-21 회원 JWT 필수로 변경
- 2026-09-23 문서 최초 작성
POST /v1/wishlist
상품을 찜합니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:wishlist_create - 회원: JWT 또는 user_id 필수 —
Bootpay-User-JWT헤더 또는user_id(쇼핑몰 서버 지정) — 회원 JWT
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| body | product_id | string | O | 이 쇼핑몰의 상품 ID | |
| body | product_option_id | string | 옵션 ID. 그 상품의 옵션이어야 합니다 |
응답
200 OK — 본문은 null 입니다. 새 항목의 wishlist_id 는 GET /v1/wishlist 로 확인하세요.
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 404 | PRODUCT_NOT_FOUND |
없는 상품(다른 쇼핑몰 상품 포함) |
| 400 | PRODUCT_NOT_AVAILABLE |
판매 중이 아닌 상품 |
| 404 | PRODUCT_OPTION_NOT_FOUND |
그 상품의 옵션이 아님 |
| 400 | WISHLIST_FULL |
이미 100개를 찜함 |
| 400 | WISHLIST_ITEM_ALREADY_EXISTS |
같은 상품·옵션을 이미 찜함 |
| 401 | USER_SESSION_INVALID |
JWT·user_id 가 모두 없거나 JWT 세션이 끝남 |
| 403 | USER_NOT_MATCH |
JWT 와 user_id 가 서로 다른 회원 |
| 404 | USER_NOT_FOUND |
user_id 가 이 몰의 회원이 아니거나 탈퇴한 회원 |
| 400 | API_PARAM_INVALID |
clientKey 만으로 인증한 요청에 user_id 를 보냄 (payload.reason: merchant_auth_required) |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-28 회원을 JWT 또는
user_id(쇼핑몰 서버 지정)로 정할 수 있게 변경 - 2026-09-21 이 쇼핑몰의 상품만 찜할 수 있도록 변경
- 2026-09-23 문서 최초 작성
DELETE /v1/wishlist/:id
찜 항목 하나를 지웁니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:wishlist_delete - 회원: JWT 또는 user_id 필수 —
Bootpay-User-JWT헤더 또는user_id(쇼핑몰 서버 지정) — 회원 JWT
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | id | string | O | 찜 항목 ID(wishlist_id). 상품 ID 가 아닙니다 |
응답
200 OK — 본문은 null 입니다.
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 404 | WISHLIST_ITEM_NOT_FOUND |
없는 항목이거나 다른 회원의 항목 |
| 401 | USER_SESSION_INVALID |
JWT·user_id 가 모두 없거나 JWT 세션이 끝남 |
| 403 | USER_NOT_MATCH |
JWT 와 user_id 가 서로 다른 회원 |
| 404 | USER_NOT_FOUND |
user_id 가 이 몰의 회원이 아니거나 탈퇴한 회원 |
| 400 | API_PARAM_INVALID |
clientKey 만으로 인증한 요청에 user_id 를 보냄 (payload.reason: merchant_auth_required) |
공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-28 회원을 JWT 또는
user_id(쇼핑몰 서버 지정)로 정할 수 있게 변경 - 2026-09-23 문서 최초 작성
POST /v1/wishlist/:id/to_cart
찜 항목을 장바구니로 옮깁니다. 수량 1개로 회원 장바구니에 담고 찜 목록에서 지웁니다. 장바구니에 같은 상품·옵션(개인·일반 구매)이 있으면 수량이 1 늘어납니다.
인증
Authorization: Basic base64(clientKey:secretKey)필수 — 인증- 필요한 scope:
user:wishlist_to_cart - 회원: JWT 또는 user_id 필수 —
Bootpay-User-JWT헤더 또는user_id(쇼핑몰 서버 지정) — 회원 JWT
요청
| 위치 | 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|---|
| path | id | string | O | 찜 항목 ID(wishlist_id) |
|
| header | Idempotency-Key | string | 재시도 키(선택). 아래 참고 |
Idempotency-Key 를 보내면 이 API 는 공통 멱등 규칙 대신 회원 단위로 처리합니다.
- 같은 회원이 같은 키로 같은 찜 항목을 다시 보내면 장바구니 수량을 다시 올리지 않고 처음 응답을 그대로 돌려줍니다. 담은 뒤 응답을 못 받아 다시 누른 경우를 위한 것입니다. 회원을 JWT 로 정했든
user_id로 정했든 같은 회원이면 같은 범위입니다. - 같은 키를 다른 찜 항목에 쓰면
409 IDEMPOTENCY_REQUEST_MISMATCH입니다. - 앞선 요청이 아직 처리 중이면 잠시 기다렸다가 결과를 주고, 그래도 끝나지 않으면
409 IDEMPOTENCY_REQUEST_IN_PROGRESS입니다.payload.retry_after(초) 뒤에 다시 시도하세요. - 키가 없으면 매번 새 요청으로 처리합니다.
응답
200 OK — 본문은 null 입니다.
오류
| HTTP | error_code | 언제 |
|---|---|---|
| 404 | WISHLIST_ITEM_NOT_FOUND |
없는 항목이거나 다른 회원의 항목 (이미 옮긴 항목 포함) |
| 404 | PRODUCT_NOT_FOUND |
찜한 상품이 삭제됨 |
| 400 | CART_ITEM_UNAVAILABLE |
판매 중이 아닌 상품 |
| 400 | CART_ITEM_STOCK_OUT |
재고 부족 |
| 400 | CART_PRODUCT_OPTION_REQUIRED |
옵션 없이 찜했는데 옵션 선택이 필요한 상품 |
| 404 | PRODUCT_OPTION_NOT_FOUND |
찜한 옵션이 삭제됨 |
| 409 | IDEMPOTENCY_REQUEST_MISMATCH |
같은 Idempotency-Key 를 다른 찜 항목에 사용 |
| 409 | IDEMPOTENCY_REQUEST_IN_PROGRESS |
같은 키의 앞선 요청이 아직 처리 중 |
| 401 | USER_SESSION_INVALID |
JWT·user_id 가 모두 없거나 JWT 세션이 끝남 |
| 403 | USER_NOT_MATCH |
JWT 와 user_id 가 서로 다른 회원 |
| 404 | USER_NOT_FOUND |
user_id 가 이 몰의 회원이 아니거나 탈퇴한 회원 |
| 400 | API_PARAM_INVALID |
clientKey 만으로 인증한 요청에 user_id 를 보냄 (payload.reason: merchant_auth_required) |
담기에 실패하면 찜 항목은 그대로 남습니다. 공통 오류(인증·scope·방화벽)는 오류를 봅니다.
변경 이력
- 2026-09-28 회원을 JWT 또는
user_id(쇼핑몰 서버 지정)로 정할 수 있게 변경 - 2026-09-21 회원 단위
Idempotency-Key지원, 다른 회원·다른 쇼핑몰 항목은 404 - 2026-09-23 문서 최초 작성
