상품에 연결하는 배송 정책(배송 방법·배송비·지역 추가비·반품/교환 설정)을 관리합니다. 상품은 정책을 연결하는 시점의 내용을 복사해 두므로, 정책을 고쳐도 이미 만들어진 주문에는 영향이 없습니다.
배송비 코드
| 필드 | 값 |
|---|---|
| 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만 받습니다(그 밖의 값은 401API_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 로 봅니다). 다른 역할은 401API_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 로 봅니다). 다른 역할은 401API_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 로 봅니다). 다른 역할은 401API_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 를 부여받아야 합니다
