2026.03.03 배송 정책 변경 Phase 1

2026.03.03 대고객 배포되는 배송 정책 변경에 따른 API 변경 사항입니다.

최초 공지 시 2/23까지 대응 요청드렸으나, 대고객 오픈되는 3/3 전까지 적용해주시면 됩니다.

[정책 변경] 토스쇼핑파트너스 상품 배송 설정 변경 및 정책 안내

1. 배송 설정 방식 변경 (상품 → 옵션 단위)

기존에는 상품 전체에 하나의 배송 정보만 설정했으나, 이제는 옵션(품목) 단위로 배송 정보를 입력해야합니다.

• 기본: 전체 옵션 일괄 적용 가능

• 상세: 옵션이 여러 개일 경우, 빨리 보낼 수 있는 옵션(오늘출고)과 주문 제작 옵션(일반출고)을 구분하여 설정 가능

2. 배송 유형별 설정 및 페널티 정책 안내

배송 정보 입력 시 [오늘출고] 적용 여부에 따라 입력 값과 준수 사항이 달라집니다.

A. '오늘출고' 설정 시

구매자에게 "오늘 출발"을 약속합니다.

• 마감시간 선택: 10:00 ~ 23:00 사이에서 30분 단위로 자유롭게 설정 가능 (예: 15:30, 20:00)

• 설정한 마감시간 이전에 들어온 주문은 반드시 당일 발송해야 합니다.

B. '오늘출고' 미적용 시 (일반 출고)

당일 발송이 힘든 경우, 상품 준비에 걸리는 기간(상품 출고 소요일)을 정확히 입력해야 합니다.

• 입력 값: 결제일 기준 며칠 내 출고 가능한지 숫자 입력 (예: 1일⇒1, 3일⇒3)

• ⚠️ 주의사항: 입력하신 상품 출고 소요 일을 초과하여 발송할 경우 페널티가 부과됩니다.

📢 관련 정책 필독 변경된 배송 설정을 정확히 입력하지 않거나 출고 기한을 어길 시 불이익이 발생할 수 있습니다. 아래 공지를 꼭 참고해주세요.

• [필독1] 토스쇼핑파트너스 패널티 정책 공지 👉 https://shopping-seller.toss.im/docs/44863

• [필독2] 배송 품질 개선 정책 변경안 👉 https://shopping-seller.toss.im/docs/44895

---

[개발 가이드] 배송 정보 필드 변경 상세

1. 대상 API

구분	Method	Endpoint (현행 유지)
상품 등록	POST	https://shopping-fep.toss.im/api/v3/shopping-fep/products/v2
상품 수정	PUT	https://shopping-fep.toss.im/api/v3/shopping-fep/products/{productId}/v2
상품 조회	GET	https://shopping-fep.toss.im/api-public/v3/shopping-fep/{sellerType}/products/{productId}/v2
택배사 조회 (신규)	GET, request parameter 없음 하단에 응답 json 첨부	https://shopping-fep.toss.im/api-public/v3/shopping-fep/{sellerType}/delivery-companies

---

2. 필드(Parameter) 변경 상세

배송 관련 필드가 Product(최상위) 레벨에서 Stocks.deliveryPolicy (stocks 하위에 배송정책 신규 생성) 레벨로 이동하며, 시간 설정 포맷이 변경됩니다.

2-1. 배송 설정 위치 변경

• AS-IS: product 객체 내 deliveryPolicy 존재

• TO-BE: stocks 객체 내 deliveryPolicy 추가

  • 배송 설정은 옵션 단위로 저장되므로, 옵션이 여러개라면 전체 옵션에 대해 deliveryPolicy를 채워줘야 합니다.

2-2. 주요 필드 스펙 (dedeliveryPolicy 하위)

필드명	타입	필수	설명 및 변경점
deliveryType	String (Enum)	O	[신규 추가] NORMAL 일반 배송 NO_DELIVERY 배송 없음 DIRECT_DELIVERY 직접 배송
deliverySpeed	String (Enum)	O	[변경] 기존 deliveryMethod 대체 기등록된 상품의 경우, deliveryMethod값 마이그레이션됨 NORMAL 일반 배송 TODAY_DELIVERY 오늘 출고
✅ deliveryCutoffTime	String	△	[변경] 기존 deliveryDeadline 대체, 오늘 출발 배송 설정 시 필수
✅ preparationDays	Integer	△	[변경] 오늘 출고 미적용 시(= 일반 배송 설정 시) 필수 기등록된 상품의 경우, default값 3 적용
canLongDistanceDelivery	Boolean	O	[변경] 기존 isJejuAndIslandsMountainsDelivery 대체
deliveryCompanyId	Integer	O	[신규 추가] 택배사 조회 API 결과 사용

✅ deliveryCutoffTime

• 조건: 오늘 출 설정 시, deliveryCutoffTime 필수

• 포맷: HH:mm (24시간제, 30분 단위)

• 범위: 10:00 ~ 23:00

• 예: "15:30", "23:00" (기존 "12시" 불가)

✅ preparationDays

• 조건: 오늘 출고 미적용 시, preparationDays 필수, (NORMAL) 입력

• 포맷 : Integer

• 내용: 출고 소요 영업일 (예: 1, 3)

  • 기존 등록된 상품,옵션은 default 3일(=이용 약관 상 패널티 받지 않는 최대 기한)로 마이그레이션 완료

• 주의: 설정일 초과 시 페널티 부과 |

2-3. 택배사 정보 (신규 필수)

• deliveryCompanyId (Integer): 상품 등록/수정 시 사용할 택배사 ID를 필수로 입력해야 합니다. (별도 조회 API 제공 /api-public/v3/shopping-fep/{sellerType}/delivery-companies)

---

3. JSON 데이터 구조 비교 (Example)

❌ [AS-IS] 기존 전송 방식 (변경 전)

배송 정보가 상품(Root) 레벨에 있었음

POST /api/v3/shopping-fep/products/v2 HTTP/1.1
Host: shopping-fep.toss.im
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 1379

{
  "name": "리클라이너",
  "brandName": "토스",
  "categoryId": 12345,
  "stocks": [
    {
      "options": [
        {
          "groupName": "색상",
          "valueName": "블랙"
        }
      ],
      "remainingCount": 100,
      "isHide": false,
      "isMainPrice": true,
      "isSoldOut": false,
      "originPrice": 50000,
      "salePrice": 45000,
      "isPurchasableAlone": true,
      "searchOption": {
        "searchOptionWithValue": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        }
      },
      "managementCode": "OPT-001",
      "images": [
        {
          "url": "https://picsum.photos/600",
          "order": 0
        }
      ]
    }
  ],
  "images": [
    {
      "type": "THUMBNAIL",
      "productItemId": 67890,
      "url": "https://picsum.photos/600",
      "html": "<div>상품 설명</div>",
      "order": 0
    }
  ],
  "exposure": {
    "searchKeywords": [
      "text"
    ],
    "description": "편안한 리클라이너 의자입니다",
    "serialNumber": "RC-2024-001"
  },
  "isTaxFree": false,
  "deliveryPolicy": {
    "deliveryMethod": "NORMAL",
    "deliveryDeadline": "12시",
    "deliveryLocationId": 1001,
    "deliveryFeeType": "CONDITIONALLY_FREE",
    "deliveryFee": 3000,
    "minimumPurchasePrice": 50000,
    "isJejuAndIslandsMountainsDelivery": true,
    "jejuDeliveryFee": 5000,
    "islandsMountainsDeliveryFee": 5000
  },
  "exchangeReturnPolicy": {
    "exchangeRefundLocationId": 2001,
    "refundOneWayDeliveryFee": 3000,
    "exchangeRoundTripDeliveryFee": 6000,
    "applicationMethodDescription": "고객센터를 통해 신청해주세요",
    "applicationTermDescription": "구매 후 7일 이내"
  },
  "notice": {
    "categoryCode": "CLOTHING",
    "items": [
      {
        "id": 101,
        "content": "면 100%"
      }
    ]
  },
  "isCultureDeduction": false,
  "managementCode": "PROD-001"
}

✅ [TO-BE] 변경된 전송 방식 (상품 등록)

배송 정보가 옵션(Stocks) 레벨로 이동 + 택배사 ID 추가

POST /api/v3/shopping-fep/products/v2 HTTP/1.1
Host: shopping-fep.toss.im
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 1379

{
  "name": "리클라이너",
  "brandName": "토스",
  "categoryId": 12345,
  "stocks": [
    {
      "options": [
        {
          "groupName": "색상",
          "valueName": "블랙"
        }
      ],
      "remainingCount": 100,
      "isHide": false,
      "isMainPrice": true,
      "isSoldOut": false,
      "originPrice": 50000,
      "salePrice": 45000,
      "isPurchasableAlone": true,
      "searchOption": {
        "searchOptionWithValue": {
          "additionalProp1": "string",
          "additionalProp2": "string",
          "additionalProp3": "string"
        }
      },
      "managementCode": "OPT-001",
      "images": [
        {
          "url": "https://picsum.photos/600",
          "order": 0
        }
      ],
      "deliveryPolicy": {
        "deliveryType": "NORMAL",
        "groupDeliveryLocationId": 1001,
        "deliverySpeed": "NORMAL",
        "preparationDays": 1,
        "deliveryCutoffTime": "14:00",
        "deliveryFeeType": "CONDITIONALLY_FREE",
        "deliveryFee": 3000,
        "minimumPurchasePrice": 50000,
        "canLongDistanceDelivery": true,
        "jejuDeliveryFee": 3000,
        "islandsMountainsDeliveryFee": 5000,
        "refundOneWayDeliveryFee": 3000,
        "exchangeRoundTripDeliveryFee": 6000,
        "deliveryCompanyId": 1
      }
    }
  ],
  "images": [
    {
      "type": "THUMBNAIL",
      "productItemId": 67890,
      "url": "https://picsum.photos/600",
      "html": "<div>상품 설명</div>",
      "order": 0
    }
  ],
  "exposure": {
    "searchKeywords": [
      "string"
    ],
    "description": "편안한 리클라이너 의자입니다",
    "serialNumber": "RC-2024-001"
  },
  "isTaxFree": false,
  <------------ 제거 예정 --------------->
  "deliveryPolicy": {
    "deliveryMethod": "NORMAL",
    "deliveryDeadline": "12시",
    "deliveryLocationId": 1001,
    "deliveryFeeType": "CONDITIONALLY_FREE",
    "deliveryFee": 3000,
    "minimumPurchasePrice": 50000,
    "isJejuAndIslandsMountainsDelivery": true,
    "jejuDeliveryFee": 5000,
    "islandsMountainsDeliveryFee": 5000
  },
<------------------------------------>
  "exchangeReturnPolicy": {
    "exchangeRefundLocationId": 2001,
    "refundOneWayDeliveryFee": 3000,
    "exchangeRoundTripDeliveryFee": 6000,
    "applicationMethodDescription": "고객센터를 통해 신청해주세요",
    "applicationTermDescription": "구매 후 7일 이내"
  },
  "notice": {
    "categoryCode": "CLOTHING",
    "items": [
      {
        "id": 101,
        "content": "면 100%"
      }
    ]
  },
  "isCultureDeduction": false,
  "managementCode": "PROD-001"
}

✅ [TO-BE] 변경된 전송 방식 (상품 수정)

PUT /api/v3/shopping-fep/products/{productId}/v2 HTTP/1.1
Host: shopping-fep.toss.im
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*

{
  "name": "리클라이너",
  "brandName": "토스",
  "stocks": [
    {
      "options": [
        {
          "groupName": "색상",
          "valueName": "블랙"
        }
      ],
      "remainingCount": 100,
      "isMainPrice": true,
      "isSoldOut": false,
      "isHide": false,
      "originPrice": 100000,
      "salePrice": 80000,
      "isPurchasableAlone": true,
      "searchOption": {
        "searchOptionWithValue": {
          "additionalProp1": "string",
          "additionalProp2": "string",
          "additionalProp3": "string"
        }
      },
      "managementCode": "OPT-001",
      "representativeThumbnailImage": "https://picsum.photos/600",
      "images": [
        {
          "url": "string",
          "order": 0
        }
      ],
      "deliveryPolicy": {
        "deliveryType": "NORMAL",
        "groupDeliveryLocationId": 1001,
        "deliverySpeed": "NORMAL",
        "preparationDays": 1,
        "deliveryCutoffTime": "14:00",
        "deliveryFeeType": "CONDITIONALLY_FREE",
        "deliveryFee": 3000,
        "minimumPurchasePrice": 50000,
        "canLongDistanceDelivery": true,
        "jejuDeliveryFee": 3000,
        "islandsMountainsDeliveryFee": 5000,
        "refundOneWayDeliveryFee": 3000,
        "exchangeRoundTripDeliveryFee": 6000,
        "deliveryCompanyId": 1
      }
    }
  ],
  "images": [
    {
      "type": "THUMBNAIL",
      "url": "https://picsum.photos/600",
      "html": "<div>상품 설명</div>",
      "order": 0
    }
  ],
  "exposure": {
    "searchKeywords": [
      "string"
    ],
    "description": "편안한 리클라이너 의자입니다",
    "serialNumber": "RC-2024-001"
  },
  "isTaxFree": false,
  "isCultureDeduction": false,
  <------------ 제거 예정 --------------->
  "deliveryPolicy": {
    "deliveryMethod": "NORMAL",
    "deliveryDeadline": "12시",
    "deliveryLocationId": 1001,
    "deliveryFeeType": "CONDITIONALLY_FREE",
    "deliveryFee": 3000,
    "minimumPurchasePrice": 50000,
    "isJejuAndIslandsMountainsDelivery": true,
    "jejuDeliveryFee": 5000,
    "islandsMountainsDeliveryFee": 5000
  },
  <------------ 제거 예정 --------------->
  "exchangeReturnPolicy": {
    "exchangeRefundLocationId": 2001,
    "refundOneWayDeliveryFee": 3000,
    "exchangeRoundTripDeliveryFee": 6000,
    "applicationMethodDescription": "고객센터를 통해 신청해주세요",
    "applicationTermDescription": "구매 후 7일 이내"
  },
  "notice": {
    "categoryCode": "CLOTHING",
    "items": [
      {
        "id": 101,
        "content": "면 100%"
      }
    ]
  },
  "categoryId": 1001,
  "managementCode": "PROD-2024-001"
}

✅ [신규] 택배사 목록 조회

{
  "resultType": "SUCCESS",
  "error": {
    "errorType": 0,
    "errorCode": "string",
    "reason": "string",
    "data": {
      "additionalProp1": {},
      "additionalProp2": {},
      "additionalProp3": {}
    },
    "title": "string"
  },
  "success": [
    {
      "id": 1,
      "name": "CJ대한통운",
      "code": "04",
      "isEnabled": true
    }
  ]
}