2026.04.04 희망일 배송/착불 배송 추가

4월 20일부터 상품 등록·수정·조회 API에 희망일 배송 및 착불배송 관련 필드가 추가됩니다.

희망일 배송은 구매자가 원하는 날짜에 배송받을 수 있도록 배송 가능 기간을 설정하는 기능이며, 착불배송은 배송비를 구매자가 수령 시 직접 결제하는 배송 방식입니다.

1. 희망일 배송

변경되는 API

다음 세 가지 API에 배송 타입, 희망일배송방법, 배송 가능 일자 필드가 추가됩니다.

• 상품 등록: POST /api/v3/shopping-fep/products/v2

• 상품 수정: PUT /api/v3/shopping-fep/products/{productId}/v2

• 상품 조회: GET /api/v3/shopping-fep/products/{productId}/v2

희망일 배송을 사용하려면 deliveryType을 PREFERRED_DATE로 설정해주시기 바랍니다.

희망일 배송 기간 설정 방식

두 가지 방식 중 하나를 선택할 수 있습니다. 방식별로 사용하는 필드가 배타적이므로, 해당하지 않는 필드를 함께 보내면 오류가 발생합니다. 하기 필수 값들은 deliveryType 이 PREFERRED_DATE 일 때 필수로 들어갑니다.

방식 1. 주문일 기준 (preferredDateType: ORDER_DATE)

주문한 날로부터 N일 뒤 ~ M일까지 선택 가능한 기간을 지정합니다.

필드	타입	필수	설명	제약
preferredDateType	String	O	ORDER_DATE 고정
preferredDateFromDays	Int	O	선택 시작일 (주문일+N일)	1~30
preferredDateToDays	Int	O	선택 종료일 (주문일+M일)	30~90, fromDays 이상
preferredDateFromDate	-	X	사용 불가 (입력 시 에러)
preferredDateToDate	-	X	사용 불가 (입력 시 에러)

예시: fromDays: 3, toDays: 30 → 주문일로부터 3일 뒤 ~ 30일까지 선택 가능

방식 2. 캘린더 기준 (preferredDateType: CALENDAR)

절대 날짜로 선택 가능 기간을 고정합니다.

필드	타입	필수	설명	제약
preferredDateType	String	O	CALENDAR 고정
preferredDateFromDate	LocalDate	O	선택 시작 날짜	오늘 이후, 오늘+30일 이내
preferredDateToDate	LocalDate	O	선택 종료 날짜	오늘+90일 이내, fromDate 이후
preferredDateFromDays	-	X	사용 불가 (입력 시 에러)
preferredDateToDays	-	X	사용 불가 (입력 시 에러)

예시: fromDate: 2026-04-20, toDate: 2026-05-20 → 4/20~5/20 중 선택 가능

알아두실 점

• 희망일 배송 상품은 배송비 묶음이 불가합니다. 상품 등록·수정 시 묶음배송으로 설정하면 오류가 발생합니다.

• 희망일 배송만 별도로 설정하는 API는 없습니다. 상품 수정 API를 통해 함께 전달해주시기 바랍니다.

• 캘린더 기준으로 기간을 설정한 경우, 기간이 만료되면 상품이 자동 미노출 처리되고 상태가 [확인필요]로 바뀝니다. 기간을 다시 설정하면 [판매중]으로 복귀됩니다.

---

2. 착불 배송

같은 날짜에 착불배송 관련 필드도 함께 추가됩니다. 착불배송은 배송비를 구매자가 수령 시 직접 결제하는 방식으로, 배송 템플릿의 배송비 타입을 착불로 설정하면 사용할 수 있습니다.

변경되는 API

희망일 배송과 동일한 세 가지 API에 착불배송 관련 필드가 추가됩니다.

• 상품 등록: POST /api/v3/shopping-fep/products/v2

• 상품 수정: PUT /api/v3/shopping-fep/products/{productId}/v2

• 상품 조회: GET /api/v3/shopping-fep/products/{productId}/v2

착불배송을 사용하려면 배송 템플릿의 배송비 타입을 착불로 설정해주시기 바랍니다.

착불배송 관련 필드

필드	타입	필수	설명	비고
deliveryFeeType	String	O	배송비 타입, 기존에 존재하던 필드	착불배송 시 COLLECT_ON_DELIVERY로 설정
canLongDistanceDelivery	Boolean	X	제주 및 도서산간 지역 배송 가능 여부	true: 추가 배송비 받고 배송 가능, false: 배송 불가

알아두실 점

• 착불배송 상품은 묶음배송이 불가합니다. 상품 등록·수정 시 묶음배송으로 설정하면 오류가 발생합니다.

• 착불배송에서는 기본 배송비 기준 금액만 구매자에게 노출됩니다. 지역별 배송비가 따로 존재하는 경우, 상세페이지에 안내 문구를 통해 고지됩니다.

• 배송 환경에 따라 추가 요금이 발생할 수 있습니다 (사다리차 여부, 철거 및 설치 등).

문의가 있으면 토스쇼핑 파트너스 고객센터로 연락해주세요.

감사합니다.