기본 배송비, 제주·도서산간 추가금, 무료배송 기준, 반품·교환 배송비를 담는 템플릿이에요. 상품에 이 정책을 붙이면 주문 금액 계산이 여기서 나와요.
장바구니 견적의 summary.total_delivery_fee와 delivery_groups는 이 정책을 바탕으로 계산돼요. 제주·도서산간 추가비는 견적 요청에 shipping_address.zipcode를 넣어 확정해요. 필드와 오류의 전체 계약은 배송 정책 API를 확인해요.
이 API는 Basic 인증이 필요하고 별도 scope 검사는 하지 않아요. 회원 JWT는 필요 없어요.
목록 조회
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
page |
Integer | 선택 | 페이지 번호 (기본: 1) |
limit |
Integer | 선택 | 페이지당 데이터 수 (기본: 24). 상한·0 이하 검사가 없으므로 1 이상을 보내요 |
200 OK 응답은 { "list": [배송 정책], "count": 전체 건수 }예요. 사용 중(status: 1)인 이 프로젝트의 정책이 최신순으로 와요.
생성
파라미터가 많아 묶어서 봐요. 넘기지 않은 값은 모델 기본값이 쓰여요.
기본
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
template_name |
String | 선택 | 정책 이름 (관리자에서 고를 때 쓰는 이름) |
status |
Integer | 선택 | 사용 여부 |
is_default |
Boolean | 선택 | 값이 있으면 프로젝트 기본 배송 정책으로 지정해요. 문자열 "false"도 지정되므로 쓰지 않을 때는 필드를 빼요 |
delivery_company_code |
String | 선택 | 기본 택배사 코드 |
attribute_type_array |
Array | 선택 | 정책 속성 타입 배열 (정수) |
배송 수단
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
use_parcel |
Boolean | 선택 | 택배 사용 |
use_direct |
Boolean | 선택 | 직접 배송 사용 |
use_quick |
Boolean | 선택 | 퀵 서비스 사용 |
use_pickup |
Boolean | 선택 | 매장 수령 사용 |
use_made |
Boolean | 선택 | 주문 제작 여부 |
use_bundle_shipping |
Boolean | 선택 | 묶음배송 사용 |
quick_service_areas |
Array | 선택 | 퀵 서비스 가능 지역 |
배송비
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
fee_type |
Integer | 선택 | 배송비 부과 방식 |
fee_pay_type |
Integer | 선택 | 선불·착불 구분 |
base_fee |
Number | 선택 | 기본 배송비 |
area_jeju_fee |
Number | 선택 | 제주 추가 배송비 |
area_remote_fee |
Number | 선택 | 도서산간 추가 배송비 |
free_shipping_threshold |
Number | 선택 | 이 금액 이상이면 무료배송 |
weight_surcharge_threshold |
Number | 선택 | 무게 추가금 기준 |
출고·도착 예정
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
delivery_after |
Integer | 선택 | 결제 후 며칠 이내 발송인지 (상품 상세의 「N일 이내 발송 예정」) |
delivery_after_jeju |
Integer | 선택 | 제주 기준 출고 리드타임 |
delivery_after_remote |
Integer | 선택 | 도서산간 기준 출고 리드타임 |
expected_delivery_period_type |
Integer | 선택 | 도착 예정 표기 방식 |
expected_delivery_direct_input |
String | 선택 | 도착 예정을 직접 문구로 쓸 때 |
delivery_after · delivery_after_jeju · delivery_after_remote 를 비워 두면 기존 값이 유지돼요. 새로 만든 정책이라면 모델 기본값(4)이 「제주·도서산간 4일」로 상품 상세에 그대로 뜨니 꼭 채워요.
반품·교환
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
claim_return_type |
Integer | 선택 | 반품 배송비 부과 방식 |
claim_return_delivery_fee |
Number | 선택 | 반품 배송비 |
claim_exchange_delivery_fee |
Number | 선택 | 교환 배송비 |
claim_return_delivery_company_code |
String | 선택 | 반품 수거 택배사 코드 |
주소
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
shipping_address_id |
String | 선택 | 출고지 주소 ID |
return_address_id |
String | 선택 | 반품지 주소 ID. 보낸다면 shipping_address_id도 함께 보내요 |
pickup_address_id |
String | 선택 | 매장 수령지 주소 ID. 보낸다면 shipping_address_id도 함께 보내요 |
200 OK여도 생성된 정책 객체가 본문으로 오지 않아요. 목록을 다시 조회해 delivery_shipping_id를 확인해요. area_jeju_able·area_remote_able은 이 API로 변경할 수 없어요.
수정
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
delivery_shipping_id |
String | 필수 | 수정할 정책 ID. 본문에 넣어요 — 경로 값만 넣으면 못 찾아요 |
나머지는 생성과 같아요. 넘기지 않은 값은 그대로 남아요.
200 OK 응답에 수정된 정책 객체가 오지 않아요. 목록을 다시 조회해 결과를 확인해요.
정책을 고쳐도 이미 만들어진 주문은 주문 당시 스냅샷을 그대로 써요. 과거 주문의 배송비가 소급해서 바뀌지 않아요.
삭제
이 API는 상품 연결 여부를 검사하지 않고 정책을 삭제해요. 삭제는 되돌릴 수 없으므로 상품 조회에서 사용 중인 상품을 확인해요. 다른 프로젝트의 정책을 삭제하면 404 DELIVERY_SHIPPING_NOT_FOUND예요.
200 OK 응답 본문은 JSON true예요.
에러 코드
인증·권한 관련 에러는 커머스 API 인증 에러를 참고해요.
| 코드 | 메시지 | 대처 방법 |
|---|---|---|
DELIVERY_SHIPPING_NOT_FOUND |
배송비 정책을 찾을 수 없어요 | 수정은 HTTP 500, 삭제는 HTTP 404예요. 정책 ID를 확인해요 |
DELIVERY_SHIPPING_NOT_MATCH |
수정 대상이 이 프로젝트의 정책이 아니에요 | 다른 프로젝트의 정책 ID를 쓰지 않았는지 확인해요 |
생성·수정 중 주소 및 정책 오류는 HTTP 500으로 올 수 있어요. 삭제의 DELIVERY_SHIPPING_NOT_FOUND는 HTTP 404예요. 본문의 error_code도 함께 확인해요.