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 }]
})javascriptvalidate는 구매 불가 항목도 빼지 않고 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"
}jsoncart_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입니다. 헤더가 없으면 이전 동작 그대로입니다.
담기까지 성공한 뒤 찜 삭제가 실패해 요청 자체가 실패로 끝난 경우에는, 같은 키의 재시도가 다시 실행됩니다(주문 준비의 멱등 계약과 같습니다). 응답을 받은 뒤의 재전송·다중 클릭은 차단됩니다.



