장바구니·찜·견적

v1 장바구니 API는 회원의 장바구니 관리와 주문 전 가격 견적을 제공합니다. 엔드포인트별 필드와 오류는 장바구니 API 원문을 확인합니다.

모든 URL은 https://api.bootapi.com 기준이며 서버 Basic 인증을 사용합니다. 회원 장바구니에는 Bootpay-User-JWT 또는 쇼핑몰 서버가 secretKey로 인증하고 지정한 user_id가 필요합니다. 두 값을 함께 보내면 같은 회원이어야 합니다. client_key만으로 인증한 호출에서는 user_id를 사용할 수 없습니다.

장바구니 HTTP 계약

메서드·URL 본문 성공 본문
GET /v1/cart 없음 장바구니 객체
POST /v1/cart product_id, product_option_id?, quantity null — 추가 후 다시 조회
PUT /v1/cart/:id 또는 PATCH quantity 변경된 항목
DELETE /v1/cart/:id 없음 null
DELETE /v1/cart/destroy_items item_ids: string[] success와 제거/남은 개수
DELETE /v1/cart/clear 선택 group_key success와 제거/남은 개수
POST /v1/cart/merge cart_items: object[] 비회원 장바구니 병합 결과
POST /v1/cart/batch items: object[] 일괄 추가 결과
POST /v1/cart/checkout item_ids: string[], 선택 group_key { "order_pre_id": "...", "url": "..." }
PATCH /v1/cart/:id/update_period subscription_period_id 기간 변경 결과

:id는 상품 ID가 아니라 장바구니 항목 ID​​입니다. 추가는 단건 본문이고 일괄 추가는 items 배열입니다. 수량 변경 액션은 옵션 변경을 처리하지 않습니다. 옵션을 바꾸려면 항목 삭제/추가 흐름을 사용합니다.

추가 API는 is_subscription, period, corporate_type, user_group_id도 읽습니다. 회원/기업 권한과 상품 소속을 서버에서 검증한 값만 전달합니다.

await commerce.post('cart', {
  product_id: productId,
  product_option_id: optionId,
  quantity: 2
}, { headers: { 'Bootpay-User-JWT': customerJwt } })

const cart = await commerce.get('cart', {
  headers: { 'Bootpay-User-JWT': customerJwt }
})javascript

조회 객체에는 cart_id, user_id, cart_items, delivery_groups, summary, checkout_groups, item_count, total_summary, created_at, updated_at가 있습니다. checkout_groups[].group_key는 일반/구독 및 구매 유형별 결제 그룹을 구분합니다. POST /v1/cart/checkout에서는 item_ids를 배열로 보내고, 한 주문에는 한 그룹만 담습니다. item_ids와 group_key를 모두 생략하면 REQUIRED_PARAMETER_IS_MISSING입니다. group_key를 함께 보내면 해당 그룹의 항목만 주문합니다. 성공 응답의 url로 결제 화면을 열고, 결제가 끝난 뒤 장바구니 항목이 빠집니다.

/v1/cart/preview, /v1/cart/benefits API 는 없습니다. 아래 order-preview 를 사용합니다.

비회원 상품 검증·배송비·미리보기

메서드·URL 요청 응답
POST /v1/cart/validate cart_items { cart_items: [...] }
POST /v1/cart/delivery-fee cart_items { delivery_groups: [...] }
POST /v1/cart/order-preview cart_items, 선택 shipping_address.zipcode checkout_ready, amounts, quote_token, expires_at 등
const preview = await commerce.cart.orderPreview({
  cart_items: [{ product_id: productId, product_option_id: optionId, quantity: 2 }]
})javascript

validate는 구매 불가 항목도 빼지 않고 is_available: false와 reason을 돌려줍니다. 견적은 상품 금액·배송비를 주문 준비와 같은 규칙으로 계산합니다. shipping_address.zipcode를 넣으면 제주·도서산간 추가 배송비까지 확정합니다. 쿠폰·적립금은 반영하지 않고 구독 상품은 이 견적으로 결제할 수 없습니다.

{
  "checkout_ready": true,
  "amounts": {
    "product_price": 20000,
    "delivery_price": 3000,
    "total_price": 23000
  },
  "quote_token": "q1.eyJ2Ijo...",
  "expires_at": "2026-09-29T03:00:00Z"
}json

cart_items는 최대 50개이며 수량은 각 항목과 같은 상품·옵션의 합계 모두 1~999여야 합니다. 구매 불가 항목이 하나라도 있으면 checkout_ready: false, amounts: null이며 토큰이 없습니다. 견적 토큰은 10분 동안 유효합니다. 회원 장바구니에서 결제한다면 항목마다 cart_item_id를 보냅니다. 결제 완료 후 해당 줄에서 결제한 수량만 차감합니다.

회원 견적은 JWT 또는 secretKey 인증의 user_id를 사용합니다. 비회원 견적에 Bootpay-Device-UUID를 보냈다면 준비 요청에도 같은 값을 보내야 합니다. 견적과 준비의 구매자가 달라지면 ORDER_QUOTE_SESSION_MISMATCH로 거절됩니다. 미리보기가 성공해도 주문서나 재고 예약은 생성되지 않습니다.

찜

메서드·URL 본문 성공 본문
GET /v1/wishlist 없음 { "wishlist_items": [], "total_items": 0 }
POST /v1/wishlist product_id, 선택 product_option_id null
DELETE /v1/wishlist/:id 없음 null
POST /v1/wishlist/:id/to_cart 없음 null; 장바구니에 수량 1 추가 후 찜 삭제

:id는 wishlist_items[].wishlist_id입니다. 항목에는 product_id, product_option_id, product_name, product_option_name, image, price, available, unavailable_label이 있습니다. to_cart가 성공하면 찜과 장바구니를 다시 조회합니다.

찜 API도 회원 전용입니다. Bootpay-User-JWT 또는 secretKey 인증의 user_id로 회원을 지정합니다. POST /v1/wishlist는 다른 상점의 상품 ID를 PRODUCT_NOT_FOUND로 거절합니다. 다른 회원의 wishlist_id로 삭제·이동하면 404입니다. 필드와 오류는 찜 API 원문을 확인합니다.

to_cart 재시도

POST /v1/wishlist/:id/to_cart에 Idempotency-Key 헤더를 보내면, 같은 회원이 같은 항목으로 재전송해도 장바구니 수량이 다시 오르지 않고 최초 결과를 돌려줍니다. 같은 키로 다른 항목​​을 보내면 409 IDEMPOTENCY_REQUEST_MISMATCH입니다. 헤더가 없으면 이전 동작 그대로입니다.

담기까지 성공한 뒤 찜 삭제가 실패해 요청 자체가 실패로 끝난 경우에는, 같은 키의 재시도가 다시 실행됩니다(주문 준비의 멱등 계약과 같습니다). 응답을 받은 뒤의 재전송·다중 클릭은 차단됩니다.

API 원문

세부 요청·응답 필드와 오류 코드는 장바구니 API, 주문서 생성 방식은 주문 API를 참고합니다.

함께 보기