배송 정책

상품에 연결하는 배송 정책(배송 방법·배송비·지역 추가비·반품/교환 설정)을 관리합니다. 상품은 정책을 연결하는 시점의 내용을 복사해 두므로, 정책을 고쳐도 이미 만들어진 주문에는 영향이 없습니다.

  • 인증은 인증, 오류 형식은 오류를 봅니다.
  • 조회는 user·supervisor, 생성·수정·삭제는 supervisor 역할 scope 가 필요합니다(각 엔드포인트의 인증 참고).

배송비 코드

필드 값
fee_type 0 해당 없음, 1 무료, 2 유료, 3 조건부 무료(free_shipping_threshold 이상 무료), 4 수량별, 5 구간별
fee_pay_type 1 착불, 2 선결제, 3 착불 또는 선결제
expected_delivery_period_type 1 직접 입력(expected_delivery_direct_input), 2~`14` 결제 후 N일
claim_return_type 6 지정 반품 택배, 7 일반 반품 택배, 8 구매자 직접 반송, 9 판매자에게 수거 요청, 11 구매자가 선택
attribute_type_array 1 일반, 2 오늘 출발, 3 옵션별 오늘 출발, 4 희망일 배송, 5 당일 도착, 6 새벽 배송, 7 주문 후 제작

fee_pay_type 이 2(선결제)가 아니면 결제 금액에 배송비가 들어가지 않습니다. 배송비가 0원으로 계산돼도 착불​​이면 무료배송이 아니니 구매자에게 "착불 N원"으로 안내하세요.

GET /v1/delivery_shippings

이 프로젝트의 사용 중인 배송 정책 목록을 최신순으로 조회합니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:delivery_shipping_list · supervisor:delivery_shipping_list — Bootpay-Role 은 user·supervisor 만 받습니다(그 밖의 값은 401 API_ROLE_NOT_SUPPORT). 헤더를 보내지 않으면 user 입니다
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

위치 이름 타입 필수 기본값 설명
query page integer 1 페이지 번호
query limit integer 24 페이지당 개수

page·limit 은 페이지네이션 공통 규칙이 아니라 받은 값을 정수로 바꿔 그대로 씁니다. 상한이 없고, 0 이하 값은 검사하지 않으니 1 이상을 보내세요.

응답

200 OK

{
  "list": [
    {
      "delivery_shipping_id": "66c1...",
      "template_name": "기본 택배",
      "use_parcel": true,
      "use_direct": false,
      "use_quick": false,
      "use_pickup": false,
      "attribute_type_array": [1],
      "delivery_company_code": "CJ",
      "use_made": false,
      "delivery_after": 2,
      "delivery_after_jeju": 4,
      "delivery_after_remote": 4,
      "use_bundle_shipping": true,
      "quick_service_areas": null,
      "fee_type": 3,
      "fee_pay_type": 2,
      "base_fee": 3000,
      "area_jeju_fee": 3000,
      "area_remote_fee": 5000,
      "area_jeju_able": true,
      "area_remote_able": true,
      "free_shipping_threshold": 50000,
      "weight_surcharge_threshold": null,
      "expected_delivery_period_type": 2,
      "expected_delivery_direct_input": null,
      "shipping_address_id": "66c0...",
      "return_address_id": "66c0...",
      "pickup_address_id": null,
      "claim_return_type": 8,
      "claim_return_delivery_fee": 3000,
      "claim_exchange_delivery_fee": 6000,
      "claim_return_delivery_company_code": null,
      "status": 1
    }
  ],
  "count": 1
}json
필드 타입 설명
list[].delivery_shipping_id string 배송 정책 ID
list[].template_name string 정책 이름
list[].use_parcel / use_direct / use_quick / use_pickup boolean 택배 / 직접 전달 / 퀵 / 방문 수령 사용
list[].attribute_type_array array 배송 속성 (코드)
list[].delivery_company_code string 출고 택배사 코드
list[].use_made boolean 주문 후 제작 상품
list[].delivery_after / delivery_after_jeju / delivery_after_remote integer 결제 후 발송까지 일수 (일반 / 제주 / 도서산간)
list[].use_bundle_shipping boolean 묶음 배송 가능
list[].quick_service_areas array 퀵 배송 가능 지역
list[].fee_type / fee_pay_type integer 배송비 코드
list[].base_fee number 기본 배송비
list[].area_jeju_fee / area_remote_fee number 제주 / 도서산간 추가 배송비
list[].area_jeju_able / area_remote_able boolean 제주 / 도서산간 배송 가능
list[].free_shipping_threshold number 조건부 무료 기준 금액
list[].weight_surcharge_threshold number 무게 할증 기준(kg)
list[].expected_delivery_period_type / expected_delivery_direct_input integer / string 배송 예정 안내
list[].shipping_address_id / return_address_id / pickup_address_id string 출고지 / 반품·교환지 / 방문 수령지 주소 ID
list[].claim_return_type integer 반품 방법 (코드)
list[].claim_return_delivery_fee / claim_exchange_delivery_fee number 반품 / 교환 배송비
list[].claim_return_delivery_company_code string 반품 택배사 코드
list[].status integer 1 사용 중
count integer 전체 개수

오류

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

변경 이력

  • 2026-09-23 문서 최초 작성
  • 2026-09-29 scope 검사 추가 — 이전에는 Basic 인증만 통과하면 어떤 키로도 호출됐습니다. supervisor 가 아닌 키체인은 해당 scope 를 부여받아야 합니다

POST /v1/delivery_shippings

배송 정책을 만듭니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: supervisor:delivery_shipping_create — Bootpay-Role: supervisor 로 부릅니다(생략하면 supervisor 로 봅니다). 다른 역할은 401 API_ROLE_NOT_SUPPORT
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

모든 필드가 선택입니다. 보내지 않은 필드는 기본값(목록 응답 예시의 기본값: 택배 사용, fee_type 1 무료, fee_pay_type 2 선결제, 발송 2일/제주·도서산간 4일, claim_return_type 8)으로 저장됩니다. 코드 값은 배송비 코드를 봅니다.

위치 이름 타입 설명
body template_name string 정책 이름
body use_parcel / use_direct / use_quick / use_pickup boolean 배송 방법
body attribute_type_array array<integer> 배송 속성
body delivery_company_code string 출고 택배사 코드
body use_made boolean 주문 후 제작 상품
body delivery_after / delivery_after_jeju / delivery_after_remote integer 결제 후 발송까지 일수
body use_bundle_shipping boolean 묶음 배송 가능
body quick_service_areas array 퀵 배송 가능 지역
body fee_type / fee_pay_type integer 배송비 유형 / 결제 방식
body base_fee number 기본 배송비
body area_jeju_fee / area_remote_fee number 제주 / 도서산간 추가 배송비
body free_shipping_threshold number 조건부 무료 기준 금액
body weight_surcharge_threshold number 무게 할증 기준(kg)
body expected_delivery_period_type / expected_delivery_direct_input integer / string 배송 예정 안내
body shipping_address_id string 출고지 주소 ID (이 프로젝트의 주소)
body return_address_id string 반품·교환지 주소 ID. shipping_address_id 와 함께 보내야 합니다
body pickup_address_id string 방문 수령지 주소 ID. shipping_address_id 와 함께 보내야 합니다
body claim_return_type integer 반품 방법
body claim_return_delivery_fee / claim_exchange_delivery_fee number 반품 / 교환 배송비
body claim_return_delivery_company_code string 반품 택배사 코드
body status integer 상태
body is_default boolean 값이 있으면 이 정책을 프로젝트 기본 배송 정책으로 지정. 문자열 "false" 도 지정으로 처리되니 쓰지 않을 때는 필드를 빼세요

area_jeju_able·area_remote_able(제주·도서산간 배송 가능 여부)은 이 API 로 바꿀 수 없습니다.

응답

200 OK

본문으로 만든 정책의 데이터가 오지 않습니다(객체 표기 문자열이 옵니다). 결과는 목록으로 다시 조회해 delivery_shipping_id 를 확인하세요.

오류

HTTP error_code 언제
500 ADDRESS_NOT_FOUND 없는 주소 ID
500 ADDRESS_NOT_MATCH 다른 판매자·프로젝트의 주소 ID
500 SERVER_ERROR return_address_id·pickup_address_id 만 보내고 shipping_address_id 를 빼는 등 처리할 수 없는 입력

이 API 의 도메인 오류는 현재 HTTP 500 으로 응답합니다. 분기는 error_code 로 하세요. 공통 오류(인증·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-08-12 delivery_after_jeju·delivery_after_remote 입력 지원
  • 2026-09-23 문서 최초 작성
  • 2026-09-29 scope 검사 추가 — 이전에는 Basic 인증만 통과하면 어떤 키로도 호출됐습니다. supervisor 가 아닌 키체인은 해당 scope 를 부여받아야 합니다

PUT /v1/delivery_shippings/:id

배송 정책을 고칩니다. 보낸 필드만 바뀌고 나머지는 유지됩니다.

경로의 :id 는 쓰이지 않습니다. 고칠 정책은 본문의 delivery_shipping_id 로 지정​​합니다. 경로와 본문에 같은 ID 를 넣으세요.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: supervisor:delivery_shipping_update — Bootpay-Role: supervisor 로 부릅니다(생략하면 supervisor 로 봅니다). 다른 역할은 401 API_ROLE_NOT_SUPPORT
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

위치 이름 타입 필수 기본값 설명
path id string O 배송 정책 ID (현재 무시됨)
body delivery_shipping_id string O 고칠 배송 정책 ID
body (그 외) 생성과 같은 필드

응답

200 OK

생성과 마찬가지로 본문으로 정책 데이터가 오지 않습니다. 결과는 목록으로 확인하세요.

오류

HTTP error_code 언제
500 DELIVERY_SHIPPING_NOT_FOUND delivery_shipping_id 가 없거나 없는 정책
500 DELIVERY_SHIPPING_NOT_MATCH 다른 판매자·프로젝트의 정책
500 ADDRESS_NOT_FOUND 없는 주소 ID
500 ADDRESS_NOT_MATCH 다른 판매자·프로젝트의 주소 ID

이 API 의 도메인 오류는 현재 HTTP 500 으로 응답합니다. 분기는 error_code 로 하세요. 공통 오류(인증·방화벽)는 오류를 봅니다.

변경 이력

  • 2026-09-23 문서 최초 작성
  • 2026-09-29 scope 검사 추가 — 이전에는 Basic 인증만 통과하면 어떤 키로도 호출됐습니다. supervisor 가 아닌 키체인은 해당 scope 를 부여받아야 합니다

DELETE /v1/delivery_shippings/:id

배송 정책을 삭제합니다. 되돌릴 수 없습니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: supervisor:delivery_shipping_delete — Bootpay-Role: supervisor 로 부릅니다(생략하면 supervisor 로 봅니다). 다른 역할은 401 API_ROLE_NOT_SUPPORT
  • 회원 JWT(Bootpay-User-JWT): 필요 없음

요청

위치 이름 타입 필수 기본값 설명
path id string O 배송 정책 ID (delivery_shipping_id)

응답

200 OK

truejson

오류

HTTP error_code 언제
404 DELIVERY_SHIPPING_NOT_FOUND 없는 정책 또는 다른 프로젝트의 정책(같은 판매자 포함)

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

변경 이력

  • 2026-09-23 문서 최초 작성
  • 2026-09-28 인증된 프로젝트의 정책만 삭제 — 없는·다른 프로젝트 정책은 404 DELIVERY_SHIPPING_NOT_FOUND(이전: 판매자만 비교, 오류는 500)
  • 2026-09-29 scope 검사 추가 — 이전에는 Basic 인증만 통과하면 어떤 키로도 호출됐습니다. supervisor 가 아닌 키체인은 해당 scope 를 부여받아야 합니다

함께 보기