찜

회원의 관심상품(찜) 목록입니다. 모든 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 문서 최초 작성

함께 보기