장바구니

구매자의 장바구니를 다룹니다. 두 종류의 API 가 있습니다.

  • 회원 장바구니​: 서버에 저장되는 회원 본인의 장바구니입니다. 조회·담기·수량 변경·삭제·주문서 전환이 여기에 속하며 회원 지정이 필수​​입니다. 회원은 회원 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 입니다.
  • 비회원(저장 없는) 계산​: validate·delivery-fee·order-preview 는 요청 본문의 cart_items 만으로 계산하고 아무것도 저장하지 않습니다. 비회원 장바구니를 브라우저에 보관하는 스토어프론트가 씁니다.

공통 사항

  • 모든 요청은 Basic 인증이 필요합니다.
  • 장바구니 항목 ID(cart_item_id)는 GET /v1/cart 응답의 cart_items[].cart_item_id 입니다.
  • 금액은 원 단위 숫자입니다.
  • 배송비 delivery_fee 가 0 이어도 무료라는 뜻은 아닙니다. 배송비 정책이 착불(fee_pay_type 이 2 가 아님)이면 결제 금액에 넣지 않고 0 으로 내려옵니다. 화면에는 "착불 base_fee원" 처럼 따로 표시하세요.
  • 구분 값: corporate_type 1=개인, 2=기업, 3=부서 / fee_type 0=해당 없음, 1=무료, 2=유료 / fee_pay_type 1=착불, 2=선결제.

체크아웃 그룹(group_key)

회원 장바구니 항목은 구독 여부 + 구매 유형(corporate_type) 으로 묶여 따로 결제합니다. group_key 는 "<regular|subscription>_<corporate_type>" 형식입니다(예: regular_1 개인 일반, subscription_2 기업 구독). GET /v1/cart 응답의 checkout_groups[].group_key 를 그대로 쓰세요.

GET /v1/cart

회원 장바구니를 조회합니다. 장바구니가 아직 없으면 빈 장바구니를 돌려줍니다(저장하지 않음).

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:cart_list
  • 회원: JWT 또는 user_id 필수 — Bootpay-User-JWT 헤더 또는 user_id(쇼핑몰 서버 지정) — 회원 JWT

요청

파라미터 없음.

응답

200 OK

{
  "cart_id": "66f1...",
  "user_id": "66a0...",
  "cart_items": [
    {
      "cart_item_id": "66f1...",
      "product_id": "65b2...",
      "product_option_id": null,
      "quantity": 2,
      "product_name": "드립백 커피 10입",
      "price": 12000,
      "original_price": 15000,
      "product_sell_price": 12000,
      "option_price": 0,
      "image": "https://...",
      "product_option_name": null,
      "product_option_keys": null,
      "discount": { "applied": true, "type": 1, "value": 3000, "amount": 3000 },
      "time_sale": { "active": false, "discount_percent": null, "start_at": null, "end_at": null },
      "is_available": true,
      "unavailable_reason": null,
      "status": 1,
      "delivery_shipping_id": "65c0...",
      "delivery_shipping_bundle_id": null,
      "delivery_base_fee": 3000,
      "delivery_free_shipping_threshold": 30000,
      "is_bundle": false,
      "use_delivery": true,
      "subtotal": 24000,
      "is_subscription": false,
      "corporate_type": 1,
      "user_group_id": null,
      "user_group_name": null
    }
  ],
  "delivery_groups": [
    {
      "delivery_shipping_id": "65c0...",
      "delivery_shipping_bundle_id": null,
      "items": ["66f1..."],
      "cart_item_ids": ["66f1..."],
      "total_price": 24000,
      "item_count": 1,
      "total_quantity": 2,
      "delivery_fee": 3000,
      "is_bundle": false,
      "base_fee": 3000,
      "free_shipping_threshold": 30000,
      "fee_type": 2,
      "fee_pay_type": 2
    }
  ],
  "summary": {
    "total_items": 1,
    "available_items": 1,
    "unavailable_items": 0,
    "total_price": 24000,
    "total_quantity": 2
  },
  "checkout_groups": [
    {
      "group_key": "regular_1",
      "label": "개인 일반",
      "is_subscription": false,
      "corporate_type": 1,
      "items": [
        { "cart_item_id": "66f1...", "product_id": "65b2...", "product_option_id": null, "quantity": 2, "product_name": "드립백 커피 10입", "price": 12000 }
      ],
      "summary": { "item_count": 1, "total_price": 24000 }
    }
  ],
  "item_count": 1,
  "total_summary": {
    "total_items": 1,
    "available_items": 1,
    "total_price": 24000,
    "total_delivery_fee": 3000,
    "total_order_price": 27000
  },
  "created_at": "2026-09-20 10:00:00 +0900",
  "updated_at": "2026-09-22 09:12:00 +0900"
}json
필드 타입 설명
cart_id string 장바구니 ID. 아직 저장된 장바구니가 없으면 임시 값이 옵니다
user_id string 회원 ID
cart_items[] array 담긴 항목. 현재 상품 정보 기준으로 채웁니다
cart_items[].cart_item_id string 장바구니 항목 ID. 수정·삭제·주문 시 사용
cart_items[].price number 단가. 선택 옵션은 상품 판매가 + 옵션가, 추가 옵션은 옵션가만
cart_items[].original_price number 할인 전 단가
cart_items[].product_sell_price / option_price number 단가 구성(상품 판매가 / 옵션가)
cart_items[].discount object 상품 할인 정보 (applied·type·value·amount)
cart_items[].time_sale object 타임세일 정보 (active·discount_percent·start_at·end_at)
cart_items[].is_available boolean 구매 가능 여부. 상품이 삭제·판매중지면 false
cart_items[].unavailable_reason string|null 구매 불가 사유 문구
cart_items[].delivery_base_fee number 이 상품 배송 정책의 기본 배송비(무료 정책이면 0)
cart_items[].delivery_free_shipping_threshold number 조건부 무료배송 기준 금액
cart_items[].is_bundle boolean 묶음배송이 실제로 성립했는지(같은 묶음 정책의 서로 다른 상품 2개 이상)
cart_items[].subtotal number price × quantity
cart_items[].is_subscription boolean 구독 항목 여부
cart_items[].subscription_period object 구독 항목만. id·label·duration·duration_type·display_price·use_discount·discount_price·discount_price_type
cart_items[].first_payment_adjustments array 구독 항목 중 첫 결제 금액이 조정되는 상품만. [{ name, price }] (설치비·회차 할인 등, 할인은 음수)
cart_items[].first_payment_adjust number 위 조정 금액 합계
cart_items[].corporate_type integer 구매 유형
cart_items[].user_group_id / user_group_name string|null 기업·부서 구매 시 소속 그룹
delivery_groups[] array 구매 가능한 항목을 배송비 계산 단위로 묶은 결과
delivery_groups[].delivery_fee number 결제 시 청구할 배송비. 착불이면 0
delivery_groups[].is_bundle boolean 묶음배송 그룹 여부. 묶음이면 use_lowest_fee·bundle_fee_type 이, 개별이면 fee_type·fee_pay_type 이 추가됩니다
summary object 전체 항목 수·구매 가능 항목 수·구매 불가 항목 수·구매 가능 항목 금액 합계(total_price)·수량 합계
checkout_groups[] array 체크아웃 그룹. POST /v1/cart/checkout 의 group_key 로 씁니다
total_summary object 합계 요약. total_order_price = total_price + total_delivery_fee

summary.total_price·total_summary.total_price·checkout_groups[].items[].price 는 상품 할인가만으로 계산한 참고 값입니다(옵션가·구독 기간 가격 미포함). 결제될 금액은 POST /v1/cart/order-preview 로 확인하세요.

오류

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)

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-28 회원을 JWT 또는 user_id(쇼핑몰 서버 지정)로 정할 수 있게 변경
  • 2026-09-14 회원 JWT 필수로 변경
  • 2026-09-23 문서 최초 작성

POST /v1/cart

회원 장바구니에 상품을 담습니다. 같은 상품·옵션·구독 여부·구독 기간·구매 유형의 항목이 이미 있으면 수량만 더합니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:cart_create
  • 회원: JWT 또는 user_id 필수 — Bootpay-User-JWT 헤더 또는 user_id(쇼핑몰 서버 지정) — 회원 JWT

요청

위치 이름 타입 필수 기본값 설명
body product_id string O 상품 ID
body product_option_id string 옵션 ID. 옵션 선택이 필요한 상품이면 필수
body quantity integer 1 담을 수량
body is_subscription boolean false 구독으로 담기. true 또는 "true" 만 구독으로 봅니다
body period integer 구독 기간 값(상품 구독 기간의 duration, 예: 3). is_subscription 일 때만 사용
body corporate_type integer 1 구매 유형 1=개인, 2=기업, 3=부서
body user_group_id string 기업·부서 구매 시 소속 그룹 ID. 로그인한 회원이 속한 그룹이어야 합니다
{ "product_id": "65b2...", "product_option_id": "65b3...", "quantity": 2 }json

응답

200 OK — 본문은 null 입니다. 담긴 결과는 GET /v1/cart 로 다시 조회하세요.

오류

HTTP error_code 언제
404 PRODUCT_NOT_FOUND 없는 상품
400 CART_ITEM_UNAVAILABLE 판매 중이 아닌 상품
400 CART_ITEM_STOCK_OUT 재고 부족
400 CART_PRODUCT_OPTION_REQUIRED 옵션 선택이 필요한데 product_option_id 가 없음
404 PRODUCT_OPTION_NOT_FOUND 그 상품의 옵션이 아님
400 CART_SUBSCRIBE_PRODUCT_NOT_ALLOWED 구독으로 담았는데 구독 상품이 아님
400 CART_SUBSCRIPTION_SETTING_NOT_FOUND 상품에 구독 설정이 없음
400 CART_SUBSCRIPTION_PERIOD_NOT_FOUND period 에 맞는 구독 기간이 없음
400 CART_USER_GROUP_TYPE_INVALID corporate_type 이 1~3 이 아님
404 CART_USER_GROUP_NOT_FOUND user_group_id 가 이 회원의 그룹이 아님
400 CART_USER_GROUP_PENDING_APPROVAL 그룹이 승인 대기 중
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-14 user_group_id 는 로그인한 회원이 속한 그룹만 허용
  • 2026-09-23 문서 최초 작성

PUT /v1/cart/:id

장바구니 항목의 수량을 바꿉니다. PATCH 로 호출해도 같습니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:cart_update
  • 회원: JWT 또는 user_id 필수 — Bootpay-User-JWT 헤더 또는 user_id(쇼핑몰 서버 지정) — 회원 JWT

요청

위치 이름 타입 필수 기본값 설명
path id string O 장바구니 항목 ID(cart_item_id)
body quantity integer O 바꿀 수량. 1 이상

옵션은 바꿀 수 없습니다. 옵션을 바꾸려면 항목을 지우고 다시 담으세요.

응답

200 OK

{ "id": "66f1...", "product_id": "65b2...", "product_option_id": null, "quantity": 3 }json
필드 타입 설명
id string 장바구니 항목 ID
product_id string 상품 ID
product_option_id string|null 옵션 ID
quantity integer 바뀐 수량

오류

HTTP error_code 언제
400 PRODUCT_QTY_INVALID quantity 가 없거나 0 이하
404 CART_NOT_FOUND 회원 장바구니가 없음
404 CART_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 문서 최초 작성

DELETE /v1/cart/:id

장바구니 항목 하나를 지웁니다. 이미 없는 항목이어도 성공으로 응답합니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:cart_delete
  • 회원: JWT 또는 user_id 필수 — Bootpay-User-JWT 헤더 또는 user_id(쇼핑몰 서버 지정) — 회원 JWT

요청

위치 이름 타입 필수 기본값 설명
path id string O 장바구니 항목 ID(cart_item_id)

응답

200 OK — 본문은 null 입니다.

오류

HTTP error_code 언제
404 CART_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 문서 최초 작성

PATCH /v1/cart/:id/update_period

구독 항목의 구독 기간을 바꿉니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:cart_update_period
  • 회원: JWT 또는 user_id 필수 — Bootpay-User-JWT 헤더 또는 user_id(쇼핑몰 서버 지정) — 회원 JWT

요청

위치 이름 타입 필수 기본값 설명
path id string O 장바구니 항목 ID(cart_item_id)
body subscription_period_id string 구독 기간 ID(subscription_period.id). 담을 때의 period(기간 값)와 달리 ID 를 받습니다. 비우면 기간 지정이 해제됩니다

응답

200 OK

{ "cart_item_id": "66f1...", "subscription_period_id": "65d4..." }json

오류

HTTP error_code 언제
404 CART_NOT_FOUND 회원 장바구니가 없음
404 CART_ITEM_NOT_FOUND 이 장바구니에 없는 항목
400 CART_SUBSCRIBE_PRODUCT_NOT_ALLOWED 구독 항목이 아님
404 PRODUCT_NOT_FOUND 상품이 삭제됨
400 CART_SUBSCRIPTION_PERIOD_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 문서 최초 작성

DELETE /v1/cart/destroy_items

선택한 항목들을 한 번에 지웁니다. 이 장바구니에 없는 ID 는 무시합니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:cart_destroy_items
  • 회원: JWT 또는 user_id 필수 — Bootpay-User-JWT 헤더 또는 user_id(쇼핑몰 서버 지정) — 회원 JWT

요청

위치 이름 타입 필수 기본값 설명
body 또는 query item_ids string[] O 지울 장바구니 항목 ID 목록. 쿼리로 보낼 때는 item_ids[]=a&item_ids[]=b

응답

200 OK

{ "success": true, "cart_count": 3, "removed_count": 2 }json
필드 타입 설명
success boolean 항상 true
cart_count integer 남은 항목 수
removed_count integer 실제로 지운 항목 수

오류

HTTP error_code 언제
404 CART_NOT_FOUND 회원 장바구니가 없음
400 CART_EMPTY item_ids 가 비었음
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 문서 최초 작성

DELETE /v1/cart/clear

장바구니를 비웁니다. group_key 를 주면 그 체크아웃 그룹(탭)만 비웁니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:cart_clear
  • 회원: JWT 또는 user_id 필수 — Bootpay-User-JWT 헤더 또는 user_id(쇼핑몰 서버 지정) — 회원 JWT

요청

위치 이름 타입 필수 기본값 설명
body 또는 query group_key string 비울 체크아웃 그룹(예: regular_1). 없으면 전체를 비웁니다

응답

200 OK

{ "success": true, "cart_count": 0, "removed_count": 4 }json

오류

HTTP error_code 언제
404 CART_NOT_FOUND 회원 장바구니가 없음
400 CART_CHECKOUT_GROUP_NOT_FOUND group_key 형식이 <종류>_<유형> 이 아님
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/cart/batch

여러 상품을 한 번에 담습니다(최대 50개). 담을 수 없는 상품은 오류 없이 건너뛰고 개수만 알려 줍니다. 구독 상품은 담지 않습니다(건너뜀).

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:cart_batch
  • 회원: JWT 또는 user_id 필수 — Bootpay-User-JWT 헤더 또는 user_id(쇼핑몰 서버 지정) — 회원 JWT

요청

위치 이름 타입 필수 기본값 설명
body items object[] O 담을 상품 목록, 최대 50개
body items[].product_id string O 상품 ID
body items[].product_option_id string 옵션 ID
body items[].quantity integer 1 수량

건너뛰는 경우: 없는 상품, 판매 중이 아닌 상품, 구독 상품, 재고 부족, 없는 옵션. 같은 상품·옵션이 이미 있으면 수량을 더합니다.

{ "items": [ { "product_id": "65b2...", "quantity": 1 }, { "product_id": "65b5...", "product_option_id": "65b6...", "quantity": 2 } ] }json

응답

200 OK

{ "added_count": 1, "updated_count": 1, "skipped_count": 0, "total_items": 5 }json
필드 타입 설명
added_count integer 새로 담은 항목 수
updated_count integer 수량을 더한 항목 수
skipped_count integer 건너뛴 항목 수
total_items integer 담은 뒤 장바구니 항목 수

오류

HTTP error_code 언제
400 CART_EMPTY items 가 빈 배열
500 SERVER_ERROR items 를 보내지 않았거나 50개를 넘김 (현재 400 이 아니라 서버 오류로 끝납니다. 호출 전에 확인하세요)
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/cart/merge

로그인 전에 브라우저에 보관하던 비회원 장바구니를 회원 장바구니로 합칩니다. 로그인 직후 한 번 호출합니다. 담을 수 없는 항목은 오류 없이 건너뜁니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:cart_merge
  • 회원: JWT 또는 user_id 필수 — Bootpay-User-JWT 헤더 또는 user_id(쇼핑몰 서버 지정) — 회원 JWT

요청

위치 이름 타입 필수 기본값 설명
body cart_items object[] 비회원 장바구니 항목, 최대 50개. 비었으면 아무것도 하지 않습니다
body cart_items[].product_id string O 상품 ID
body cart_items[].product_option_id string 옵션 ID
body cart_items[].quantity integer 1 수량
body cart_items[].is_subscription boolean false 구독 항목 여부
body cart_items[].subscription_period_id integer 구독 기간 값(duration)

건너뛰는 경우: product_id 없음, 수량 0 이하, 없는 상품, 구독 상품이 아닌데 구독 요청, 그 상품의 옵션이 아님, 맞는 구독 기간이 없음. 같은 상품·옵션·구독 여부 항목이 있으면 수량을 더합니다. 합친 항목은 모두 개인(corporate_type 1)으로 담깁니다.

응답

200 OK

{ "merged_count": 2, "skipped_count": 1, "total_items": 6 }json

cart_items 가 비었으면 본문은 null 입니다.

필드 타입 설명
merged_count integer 합친(새로 담거나 수량을 더한) 항목 수
skipped_count integer 건너뛴 항목 수
total_items integer 합친 뒤 장바구니 항목 수

오류

HTTP error_code 언제
400 CART_MERGE_FAILED cart_items 가 50개를 넘음
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/cart/checkout

선택한 장바구니 항목으로 주문서를 만듭니다. 응답의 url 로 구매자를 결제 화면에 보냅니다. 결제가 끝나면 주문한 항목은 장바구니에서 빠집니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:cart_checkout
  • 회원: JWT 또는 user_id 필수 — Bootpay-User-JWT 헤더 또는 user_id(쇼핑몰 서버 지정) — 회원 JWT

요청

위치 이름 타입 필수 기본값 설명
body item_ids string[] O 주문할 장바구니 항목 ID 목록
body group_key string 체크아웃 그룹(예: regular_1). 주면 item_ids 중 그 그룹에 속한 항목만 주문합니다
  • 한 주문에는 한 그룹만 담깁니다. 구독과 일반, 서로 다른 구매 유형은 함께 주문할 수 없습니다.
  • 구독은 한 번에 한 상품·한 기간 만 주문할 수 있습니다.
  • item_ids 는 항상 배열로 보내세요. group_key 도 item_ids 도 없으면 400 REQUIRED_PARAMETER_IS_MISSING(payload.field: item_ids) 입니다.
  • 주문서는 지정한 회원의 주문서로 만들어집니다(비회원 주문서가 아님). user_id 로 부른 경우 응답 url 을 구매자 브라우저가 열 때 결제 화면의 회원 로그인은 별도로 필요합니다.

응답

200 OK

{ "order_pre_id": "66f2...", "url": "https://..." }json
필드 타입 설명
order_pre_id string 만들어진 주문서 ID
url string 결제 화면 주소

오류

HTTP error_code 언제
404 CART_NOT_FOUND 회원 장바구니가 없음
400 REQUIRED_PARAMETER_IS_MISSING group_key·item_ids 가 모두 없음
400 CART_EMPTY 장바구니가 비었거나, 선택한 항목이 장바구니에 없음, group_key 와 함께 보낸 item_ids 가 비었음
400 CART_CHECKOUT_GROUP_NOT_FOUND group_key 형식이 틀렸거나 그 그룹에 해당하는 항목이 없음
400 CART_HAS_UNAVAILABLE_ITEMS 구독·일반 혼합, 서로 다른 구매 유형 혼합, 구독 상품·기간이 둘 이상
400 PRODUCT_NOT_AVAILABLE 삭제됐거나 판매 중이 아닌 상품
404 PRODUCT_OPTION_NOT_FOUND 옵션이 삭제됨
400 ORDER_OPTION_STOCK_OUT 옵션 재고 부족
400 ORDER_PRODUCT_STOCK_OUT 상품 재고 부족
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-28 group_key·item_ids 없이 부르면 500 이던 것을 400 REQUIRED_PARAMETER_IS_MISSING 으로 변경
  • 2026-09-23 문서 최초 작성

POST /v1/cart/validate

비회원 장바구니 항목을 검증하고 현재 상품명·가격·이미지를 채워 돌려줍니다. 아무것도 저장하지 않습니다. 잘못된 항목도 빼지 않고 is_available: false 와 reason 으로 돌려줍니다.

판정·가격 규칙은 POST /v1/cart/order-preview, 결제 준비와 같습니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:cart_validate
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

위치 이름 타입 필수 기본값 설명
body cart_items object[] O 검증할 항목, 최대 50개
body cart_items[].product_id string O 상품 ID
body cart_items[].product_option_id string 옵션 ID
body cart_items[].quantity integer 1 정수 1~999. 1.5·"abc" 는 잘라내지 않고 invalid_quantity 로 판정
body cart_items[].is_subscription boolean false 구독 항목 여부
body cart_items[].subscription_period_id string 구독 기간 값(duration, 예: "3") 또는 구독 기간 ID

응답

200 OK

{
  "cart_items": [
    {
      "product_id": "65b2...",
      "product_option_id": null,
      "quantity": 2,
      "is_available": true,
      "reason": null,
      "price": 12000,
      "original_price": 15000,
      "product_name": "드립백 커피 10입",
      "product_option_name": null,
      "product_option_keys": null,
      "image": "https://...",
      "subtotal": 24000
    },
    {
      "product_id": "65ff...",
      "product_option_id": null,
      "quantity": 1,
      "is_available": false,
      "reason": "not_found",
      "price": null,
      "original_price": null,
      "product_name": null,
      "product_option_name": null,
      "product_option_keys": null,
      "image": null,
      "subtotal": 0
    }
  ]
}json
필드 타입 설명
cart_items[] array 요청 순서 그대로의 결과
cart_items[].quantity integer|null 정규화한 수량. 수량이 잘못됐으면 null
cart_items[].is_available boolean 구매 가능 여부
cart_items[].reason string|null 구매 불가 사유. 가능하면 null
cart_items[].price number|null 단가(할인·옵션가 반영). 선택 옵션은 상품가 + 옵션가, 추가 옵션은 옵션가만. 구매 불가면 null
cart_items[].original_price number|null 할인 전 단가
cart_items[].product_name / product_option_name / product_option_keys / image 구매 가능할 때만 채웁니다
cart_items[].subtotal number price × quantity. 구매 불가면 0

reason 값

값 뜻
invalid_line 항목이 객체가 아님
product_id_required product_id 없음
not_found 없는 상품(다른 쇼핑몰 상품 포함)
option_unavailable 그 상품의 옵션이 아니거나 비활성 옵션
invalid_quantity 수량이 정수 1~999 가 아님
invalid_subscription_period 구독 상품이 아닌데 구독 요청, 또는 없는 구독 기간
not_visible 비공개 상품
not_on_sale 판매 중이 아님
sale_not_started / sale_ended 판매 기간 전 / 후
option_required 옵션 선택이 필요한 상품
insufficient_stock 재고 부족

오류

HTTP error_code 언제
400 REQUIRED_PARAMETER_IS_MISSING cart_items 가 없거나 비었음
400 INVALID_PARAMETER cart_items 가 배열이 아님
400 CART_FULL 50개 초과

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-14 현재 쇼핑몰 상품만 검증(다른 쇼핑몰 상품은 not_found), 잘못된 항목도 reason 과 함께 돌려주도록 변경, 수량 정수 1~999 규칙
  • 2026-09-23 문서 최초 작성

POST /v1/cart/delivery-fee

비회원 장바구니의 배송비를 배송 그룹별로 계산합니다. 아무것도 저장하지 않습니다. 배송지를 받지 않으므로 제주·도서산간 추가 배송비는 포함하지 않습니다. 추가비까지 확정하려면 POST /v1/cart/order-preview 에 우편번호를 넣어 호출하세요.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:cart_delivery_fee
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

POST /v1/cart/validate 와 같은 cart_items(최대 50개)를 받습니다. 규칙은 order-preview 와 같습니다.

  • 수량은 정수 1~999. 어긋난 항목이 하나라도 있으면 계산하지 않고 400 입니다.
  • 같은 상품·옵션(·구독 요청·기간) 항목은 합산하며, 합산 수량도 999 이하여야 합니다.
  • 모든 항목이 이 쇼핑몰의 상품(과 그 상품의 활성 옵션)이어야 합니다.

응답

200 OK

{
  "delivery_groups": [
    {
      "seller_id": "64aa...",
      "delivery_shipping_id": "65c0...",
      "delivery_shipping_bundle_id": null,
      "bundle_id": null,
      "items": [
        { "product_id": "65b2...", "product_option_id": null, "quantity": 2, "price": 12000 }
      ],
      "total_price": 24000,
      "total_quantity": 2,
      "delivery_fee": 3000,
      "fee_type": 2,
      "fee_pay_type": 2,
      "base_fee": 3000,
      "free_shipping_threshold": 30000
    }
  ]
}json
필드 타입 설명
delivery_groups[].seller_id string 판매자 ID
delivery_groups[].delivery_shipping_id string|null 배송비 정책 ID
delivery_groups[].delivery_shipping_bundle_id / bundle_id string|null 묶음배송 정책 ID (묶음배송 상품만)
delivery_groups[].items[] array 그룹에 속한 항목. price 는 할인·옵션가를 반영한 단가
delivery_groups[].total_price number 그룹 상품 금액(단가 × 수량 합) — 조건부 무료배송 판정 기준
delivery_groups[].total_quantity integer 그룹 수량 합
delivery_groups[].delivery_fee number 결제 시 청구할 배송비. 착불 정책이면 0
delivery_groups[].fee_type / fee_pay_type integer 정책의 과금 방식 / 선결제·착불
delivery_groups[].base_fee integer 정책 기본 배송비. 착불일 때 표시할 금액
delivery_groups[].free_shipping_threshold integer 조건부 무료배송 기준 금액

오류

HTTP error_code 언제
400 REQUIRED_PARAMETER_IS_MISSING cart_items 가 비었거나 항목에 product_id 가 없음 (payload.errors[])
400 INVALID_PARAMETER cart_items 가 배열이 아니거나 항목이 객체가 아님
400 CART_FULL 50개 초과
400 PRODUCT_QTY_INVALID 수량이 정수 1~999 가 아니거나 합산 수량이 999 초과 (payload.errors[])
442 CART_HAS_UNAVAILABLE_ITEMS 이 쇼핑몰의 상품이 아니거나, 그 상품에 연결되지 않은·비활성 옵션이 섞임

400 오류의 payload.errors[] 는 { "index": 0, "indexes": [0], "reason": "invalid_quantity" } 형태로 문제 항목의 요청 위치를 알려 줍니다. reason 은 invalid_line·product_id_required·invalid_quantity·quantity_limit_exceeded 중 하나입니다.

공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-14 다른 쇼핑몰 상품이 섞이면 442 로 거절, 입력 규칙을 order-preview 와 통일(잘못된 항목을 건너뛰지 않고 400), 조건부 무료배송 기준을 할인·옵션가 반영 금액으로 변경
  • 2026-09-23 문서 최초 작성

POST /v1/cart/order-preview

장바구니 가격 견적입니다. 결제 준비(POST /v1/orders/prepare)와 같은 규칙​​으로 상품 금액·배송비·최종 합계를 계산합니다. 주문서·결제·재고 예약을 만들지 않으며, 견적을 받았다고 재고가 잡히지 않습니다.

  • 모든 항목이 구매 가능하고 배송비가 확정되면 checkout_ready: true 와 quote_token 을 줍니다. quote_token 은 결제 준비 요청에 넣어 견적과 같은 금액으로 결제되는지 확인하는 데 씁니다. 유효 시간은 발급 후 10분(expires_at)입니다.
  • 항목이 하나라도 구매 불가면 그 항목을 빼고 계산한 합계를 주지 않습니다. amounts 가 null 이고 quote_token 도 없습니다.
  • 쿠폰·적립금은 이 견적에 반영하지 않습니다(discount_price 는 항상 0).
  • 구독 상품은 이 견적으로 결제할 수 없습니다. 해당 항목은 reason 으로 알려 줍니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:cart_order_preview
  • 회원: JWT 또는 user_id 선택 — Bootpay-User-JWT 가 유효하면 그 회원, JWT 가 없고 user_id(쇼핑몰 서버 지정, secretKey 인증 한정)가 있으면 그 회원의 견적입니다. JWT 가 무효인데 user_id 가 있으면 그 회원, 둘 다 없거나 JWT 가 무효이고 user_id 도 없으면 비회원 견적 — 회원 JWT
  • 회원 판정은 결제 준비(POST /v1/orders/prepare)와 같습니다. quote_token 은 견적 때의 구매자에 묶이므로 결제 준비도 같은 인증·같은 회원 지정(JWT 또는 같은 user_id)으로 호출​​하세요. 다르면 결제 준비에서 403 ORDER_QUOTE_SESSION_MISMATCH 입니다.
  • Bootpay-Device-UUID 헤더(선택): 비회원 견적을 그 기기에 묶습니다. 비회원이 결제 준비를 할 때도 같은 값을 보내야 quote_token 이 맞습니다.

요청

위치 이름 타입 필수 기본값 설명
body cart_items object[] O 견적할 항목, 최대 50개. 필드는 POST /v1/cart/validate 와 같습니다
body cart_items[].cart_item_id string (회원) 이 항목이 온 장바구니 줄 ID(GET /v1/cart 의 cart_item_id). 보내면 결제 완료 때 그 줄에서 이 항목 수량만큼 빠집니다
body shipping_address object 배송지
body shipping_address.zipcode string 우편번호 5자리. 주면 제주·도서산간 추가 배송비까지 확정합니다

입력 규칙은 POST /v1/cart/delivery-fee 와 같습니다(수량 정수 1~999, 같은 상품·옵션 합산 999 이하, 하나라도 어긋나면 400).

장바구니 정리 — 회원이 장바구니에서 결제할 때는 항목마다 cart_item_id 를 보내세요. 서버가 그 줄이 이 회원 장바구니에 있고 상품·옵션이 같은지 확인한 뒤 quote_token 에 서명해 두고, 결제가 완료되면 줄마다 결제한 수량만큼 빼고 0 이 되면 줄을 지웁니다. 결제하는 동안 늘린 수량은 남습니다. 클라이언트가 장바구니를 따로 지울 필요가 없습니다. 바로 구매처럼 cart_item_id 를 보내지 않으면 장바구니는 바뀌지 않습니다.

{
  "cart_items": [ { "product_id": "65b2...", "quantity": 2 } ],
  "shipping_address": { "zipcode": "63000" }
}json

응답

200 OK

{
  "cart_id": null,
  "user_id": "",
  "delivery_groups": [
    {
      "group_key": "...",
      "seller_id": "64aa...",
      "delivery_shipping_id": "65c0...",
      "delivery_shipping_bundle_id": null,
      "items": [
        { "cart_item_id": null, "product_id": "65b2...", "product_option_id": null, "product_name": "드립백 커피 10입", "quantity": 2, "price": 12000, "subtotal": 24000 }
      ],
      "total_price": 24000,
      "total_quantity": 2,
      "delivery_fee": 6000,
      "fee_type": 2,
      "fee_pay_type": 2,
      "base_fee": 3000,
      "free_shipping_threshold": 30000,
      "delivery_discount": 0,
      "delivery_area_fee": 3000,
      "collect_on_delivery": false,
      "collect_fee": 0
    }
  ],
  "summary": {
    "total_items": 1,
    "total_product_price": 24000,
    "total_delivery_fee": 6000,
    "total_order_price": 30000,
    "total_quantity": 2
  },
  "unavailable_items": [],
  "checkout_ready": true,
  "quote_token": "q1....",
  "expires_at": "2026-09-23T01:10:00Z",
  "currency": "KRW",
  "items": [
    {
      "index": 0,
      "source_indexes": [0],
      "product_id": "65b2...",
      "product_option_id": null,
      "quantity": 2,
      "is_available": true,
      "reason": null,
      "unit_price": 12000,
      "original_unit_price": 15000,
      "option_price": 0,
      "subtotal": 24000,
      "product_name": "드립백 커피 10입",
      "product_option_name": null,
      "product_option_type": null
    }
  ],
  "amounts": {
    "product_price": 24000,
    "discount_price": 0,
    "delivery_price": 6000,
    "total_price": 30000,
    "origin_price": 30000,
    "delivery_area_price": 3000
  },
  "shipping_status": "confirmed",
  "errors": []
}json
필드 타입 설명
cart_id null 항상 null (저장하지 않는 견적)
user_id string 회원 견적이면 회원 ID, 비회원이면 ""
delivery_groups[] array 구매 가능한 항목의 배송 그룹
delivery_groups[].delivery_fee number 결제 시 청구할 배송비(추가 배송비 포함, 배송비 할인 차감). 착불이면 0
delivery_groups[].delivery_discount number 조건부 무료배송 등으로 빠진 금액
delivery_groups[].delivery_area_fee number 제주·도서산간 추가 배송비
delivery_groups[].collect_on_delivery boolean 착불 여부. true 면 결제 금액에 넣지 않습니다
delivery_groups[].collect_fee integer 착불일 때 받는 사람이 낼 기본 배송비. 선결제면 0
summary object 구매 가능한 항목만의 합계
unavailable_items[] array 구매 불가 항목 { product_id, product_name, reason }
checkout_ready boolean 모든 항목 구매 가능 + 배송비 확정 + 결제 가능한 구매자일 때만 true
quote_token string|null 결제 준비에 넘길 견적 토큰. checkout_ready 일 때만
expires_at string|null 토큰 만료 시각(ISO 8601, UTC)
currency string KRW
items[] array 요청 항목별 결과. 같은 상품·옵션 항목은 합쳐서 한 줄이며 source_indexes 가 원래 위치입니다
items[].unit_price / original_unit_price / option_price number|null 단가 / 할인 전 단가 / 옵션가. 구매 불가면 null
items[].product_name string|null 비공개 상품이면 null
amounts object|null 최종 금액. 항목이 하나라도 구매 불가면 null
amounts.total_price number product_price + delivery_price
amounts.origin_price number 할인 전 상품 금액
shipping_status string confirmed 또는 requires_address(추가 배송비가 붙을 수 있는 선결제 정책인데 우편번호가 없음)
errors[] array { index, indexes, product_id, product_option_id, reason }. 구매자 단위 사유는 index: null

reason 값은 POST /v1/cart/validate 의 표와 같고, 추가로 다음이 있습니다.

값 뜻
subscription_requires_member 비회원이 구독 상품을 요청
subscription_not_supported 구독 항목 — 이 견적으로 결제하지 않음. 구독 주문 흐름을 쓰세요
guest_checkout_disabled 비회원 주문을 허용하지 않는 쇼핑몰의 비회원 견적 (errors[] 에만, index: null)

오류

HTTP error_code 언제
400 REQUIRED_PARAMETER_IS_MISSING cart_items 가 비었거나 항목에 product_id 가 없음
400 INVALID_PARAMETER cart_items 가 배열이 아니거나 항목이 객체가 아님
400 CART_FULL 50개 초과
400 PRODUCT_QTY_INVALID 수량이 정수 1~999 가 아니거나 합산 수량이 999 초과
400 ORDER_QUOTE_ZIPCODE_INVALID shipping_address 가 객체가 아니거나 우편번호가 5자리 숫자가 아님
400 CART_ITEM_NOT_FOUND cart_item_id 를 쓸 수 없음. payload.errors[].reason: cart_item_requires_member(비회원) · cart_item_not_found(이 회원 장바구니에 없음) · cart_item_mismatch(줄의 상품·옵션과 다름) · cart_item_duplicated(같은 줄 ID 를 두 번)
442 CART_HAS_UNAVAILABLE_ITEMS 이 쇼핑몰의 상품이 아니거나 연결되지 않은 옵션이 섞임
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)

400 오류의 payload.errors[] 형식은 POST /v1/cart/delivery-fee 와 같습니다. 공통 오류(인증·scope·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-28 JWT 가 없을 때 user_id(쇼핑몰 서버 지정)로 회원 견적을 받을 수 있게 변경 — 결제 준비와 같은 회원 판정
  • 2026-09-28 cart_items[].cart_item_id 지원 — 결제 완료 시 그 장바구니 줄에서 결제 수량만큼 뺌. 택배 상품 견적이 500 이던 결함 수정
  • 2026-09-14 결제 준비와 같은 규칙의 가격 견적으로 변경, quote_token·checkout_ready·items·amounts·shipping_status·errors 추가
  • 2026-09-23 문서 최초 작성

함께 보기