# API 자주 묻는 질문 ### 0. API 공통 / 일반
Q. API 응답값이 None인 경우 성공/실패 확인 방법 A. 문서상 Response Body가 None으로 표기되어 있더라도, 실제 응답에는 `resultType`이 반드시 포함됩니다. 이 값이 `SUCCESS`인지 `FAIL`인지로 성공 여부를 판단하시면 됩니다.
Q. String 파라미터의 최대 길이 **A.** 필드마다 다르지만 대부분 **255자** 이내입니다. 단, 상품 상세설명(`description`)과 같은 필드는 **1500자**까지 가능합니다.
Q. clientId & clientSecret 발급 절차 **A.** 토스쇼핑 파트너 시스템 계정 발급 후, 토스 쇼핑 API 서버 및 테스트앱 접근 가이드를 통해 발급받으실 수 있습니다.
*** ### 1. 상품 등록
Q. 상품명 / 브랜드명 입력 규칙 **A.** * **상품명**: 1\~100자 (바이트가 아닌 글자수 기준) * 허용 정규식: `^[0-9a-zA-Z가-힣 ()\\-·\\[\\]/&+,~.*_#]{1,100}$` * 허용 특수문자: `( ) - · [ ] / & + , ~ . * _ #` 및 스페이스 * `@`, `!`, `%`, `$` 등은 사용 불가 * **브랜드명**: 최대 50자 * 허용 문자: `[0-9a-zA-Z가-힣 ()-+/.,]` * 금지 단어: `없음` / `중국` / `기타` / `OEM` / `협력사` * 일반 상품과 자유옵션 모두 **동일 규칙** 적용
Q. brandName을 등록하려고 합니다. 브랜드 조회 API가 있나요? **A.** 별도 브랜드 조회/검색 API는 **미제공**입니다. 토스쇼핑은 브랜드코드 방식이 아닌 **브랜드명(문자열) 직접 입력** 방식입니다. 상품 수정 API로 브랜드명 변경이 가능합니다.
Q. 브랜드 필드에 출판사명/협력사명을 넣어도 되나요? **A.** 브랜드 필드는 자유 텍스트로 설정 가능하며, 코드 레벨에서 강제하는 규칙은 없습니다. 예를 들어 도서의 경우 **출판사명**을 넣는 것이 일반적이며, 운영 정책에 맞춰 사용하면 됩니다. (단, 금지 단어는 피해야 함)
Q. 상품 준비 기간(preparationDays)이 무엇인가요? **A.** 주문 후 판매자가 상품을 발송 준비하는 데 필요한 \*\*리드타임(일 단위)\*\*입니다. (토스쇼핑 파트너스 내 '발송예정일'과 동일) * \*\*일반배송(NORMAL)\*\*에만 적용, **0\~14일** 범위 * **미입력 시 기본값 3일**, 14일 초과 시 API validation error 발생 * \*\*당일배송(TODAY\_DELIVERY)\*\*은 `deliveryDeadline`(마감시간)을 사용하므로 `preparationDays` 미사용
Q. 검색어(searchKeywords)는 필수인가요? **A.** `exposure` 객체는 상품등록 시 필수 파라미터이나, 내부의 `searchKeywords` 자체는 **선택** 항목입니다. 각 키워드는 **1\~10자**로 등록 가능하며, 등록 시 검색 노출에 도움이 됩니다.
Q. 옵션(stocks)은 최대 몇 개까지 등록할 수 있나요? **A.** `stocks` 배열은 **최대 300개**까지 등록 가능합니다. API는 단독형(옵션 단위 등록) 기준이며, 토스쇼핑파트너스 어드민에는 조합형으로 노출됩니다.
Q. 이미 등록된 옵션의 이름을 변경할 수 있나요? **A.** **변경 불가**. 상품 수정 API(`PUT /products/{productId}/v2`)로 `stocks` 옵션 **추가**는 가능하나, 기 생성된 옵션의 **이름은 변경 불가**합니다. **삭제 후 새로운 옵션을 추가**하는 방식으로 진행해야 합니다.
Q. 카테고리별 필수 판매옵션 체계는? 예외 처리가 가능한가요? **A.** * 카테고리별 필수 판매옵션은 `GET /category/{categoryId}/constraint-templates` API의 `categorySalesOptions`로 제공됩니다. * **2025.06.16부터** `isOption` 여부와 무관하게 **전부 필수값**입니다. `valueCandidates`가 빈 배열인 옵션만 자유 입력이 가능합니다. * **예외 처리는 원칙적으로 불가**. 카테고리별 필수 옵션을 충족해야 상품 등록이 가능하며, 자동 매핑이 어려운 경우 기본값 입력 후 수기 보완이 필요할 수 있습니다.
Q. 상품 등록 후 카테고리를 변경할 수 있나요? **A.** **변경 불가**. 상품 수정 API(`PUT /products/{productId}/v2`)에서는 **카테고리 외 항목만** 변경 가능합니다. 카테고리 변경이 필요한 경우 기존 상품 **삭제(숨기기 → 삭제) 후 새 카테고리로 재등록** 방식으로 처리해야 합니다.
Q. 판매 기간(시작일/종료일) 설정이 가능한가요? **A.** 토스쇼핑은 **날짜 기반 판매기간 설정이 아닌 노출 상태(`exposureStatus`) 기반**으로 관리합니다. * **숨기기**: `POST /products/hide` → `UNEXPOSURE` * **보이기**: `POST /products/show` → `EXPOSURE` * 상태: `UNEXPOSURE` / `EXPOSURE_WAITING` / `EXPOSURE` / `EXPOSURE_FINISHED` * 판매 종료 시에는 **숨기기 API**를 호출하면 됩니다.
Q. 구매 개수 제한(1인당 최대 수량) 규칙은? **A.** * **별도 API로** 등록해야 하며, **검수 승인 완료 상품만** 등록 가능 * `startTs`: **익일 이후**만 가능 (당일/과거 불가) * `endTs`: 시작일 이후여야 함 * `maxQuantityPerUser`: 1 이상의 양수 * **동일 옵션에 기간이 겹치는 제한**은 등록 불가 * "기간 없는 상시 제한"은 미지원. 반드시 시작일/종료일 지정 필요
Q. 정보제공고시(notice)에서 KC 인증 정보는 어디에 입력하나요? **A.** KC 인증 등 인증 정보는 `notice` 필드에 기재합니다. * 카테고리별로 필수 정보제공고시 항목이 다르며, `GET /category/{categoryId}/constraint-templates` API로 확인 가능합니다. * 유아/어린이 도서 중 **어린이 상품에 해당하는 추가 구성품**이 있다면 **유아동 서적이 아닌 'KC 어린이 상품' 카테고리로 등록**해야 합니다. * 정보고시 오타/오등록은 시스템 검증이 없어 등록은 처리되나, 카테고리와 다른 정보제공고시 호출은 **권장되지 않습니다**(반려 가능).
Q. 원산지는 어느 필드에 등록하나요? **A.** 상품 등록 항목에는 **별도 원산지 필수 필드가 없음**. 카테고리별 고시 항목(`notice`)에 등록하며, `content`(최대 4,000자)에 **"상품상세 설명 참고"** 로 입력하는 것도 허용됩니다.
Q. 영세 과세(SMALL) 상품은 어떻게 구분하나요? **A.** `isTaxFree: Boolean`으로만 구분합니다. * `true` = 면세, `false` = 과세 * 내부적으로는 `TaxEnums`(TAX / SMALL / EXEMPTION)가 존재하나 외부 API에는 boolean만 제공 * **영세 상품은 `isTaxFree=false`(과세)** 로 설정합니다.
Q. 상품 썸네일/상세이미지 스펙은? **A.** * **썸네일 이미지** * 정사각형 비율(1:1) 권장 (현행 필수에 가까움) * **600×600px 이상** 해상도만 등록 가능 (550×550 등 미달 이미지는 **등록 실패**) * **GIF 포맷 및 움짤 이미지 등록 제한** * **상품 상세이미지** * 허용 포맷: **JPEG, JPG, PNG, GIF, WEBP, AVIF** * 일반 이미지(JPEG/PNG/WEBP/AVIF): **최대 20MB** * GIF: 최대 10MB
*** ### 2. 상품 검수
Q. 검수 상태(inspectionStatus)의 종류와 의미는? **A.** 3가지 상태로 관리됩니다. 이미지 단위도 동일한 3가지 상태를 가집니다. * **LLM\_INSPECTION\_READY**: 검수 중 (판매 불가) * **COMPLETE**: 검수 완료 (판매 가능) * **REJECT**: 검수 반려 (판매 불가). `rejectionReasons`에 사유 노출
Q. 검수 상태별로 어떤 필드를 변경할 수 있나요? **A.** * **검수 준비(검수 중)**: 모든 항목 변경 불가 * **검수 완료(COMPLETE)**: 가격/재고, 배송정책만 변경 가능. **상품명, 카테고리, 옵션 변경 불가** * **반려(REJECT)**: 모든 항목 변경 가능 (상품명, 카테고리, 브랜드명, 가격/재고, 배송정책, 면세여부, 검색태그)
Q. 상품명을 수정하고 싶습니다. **A.** 상품명은 **최초 등록 시점**과 **검수 반려 시점**에만 수정 가능합니다. 승인 중이거나 검수 완료(COMPLETE) 상태에서는 수정할 수 없으며, 이 경우 **삭제 후 재등록(soft delete)** 방식으로 처리해야 합니다. 참고) 등록 상품명 ≠ 노출 상품명. 고객에게는 카탈로그명으로 노출됩니다.
Q. 검수 소요 시간과 카탈로그 반영 시간은? **A.** * **검수 완료 시간**: 4월 평균 0.05일 ≈ **약 1시간 30분** * **카탈로그 반영 시간**: 검수 완료 후 **12시간 이내** (요청 당일 내에 대부분 해소)
Q. 이미지를 변경하면 재검수가 도는 기준은? **A.** 판매자가 요청한 이미지의 **`requestedUrl` + `type` + `order`** 조합을 기준으로 diff를 판단합니다. * **동일 URL로 재요청** 시에는 변경으로 인식되지 않습니다. * **이미지 변경 감지** 시 자동 재검수 (품질/정책 위반 이미지 방지 목적) * **이미지 외 항목**(가격/재고/배송정보) 변경은 즉시 반영 (검수 없음)
Q. 상품 등록 중 이미지 등록만 실패하는 경우가 있나요? **A.** 상품 등록은 **단일 트랜잭션**으로 처리됩니다. 내부적으로 이미지 URL을 다운로드하여 저장하는데, 이미지 다운로드가 실패하면 상품 등록 자체가 실패합니다 (**부분 성공 없음**). "상품은 등록되었으나 이미지만 실패"하는 케이스는 발생하지 않습니다. 응답 시간은 거의 즉시 \~ 최대 **30분**까지 소요될 수 있습니다.
Q. 검수 승인 전에도 API 연동(등록/수정)이 가능한가요? **A.** 상품 등록/수정은 가능합니다. 단, **구매 개수 제한 설정은 검수 승인 완료 상품에만** 가능합니다.
*** ### 3. 상품 관리
Q. 상품 등록/수정 방식 (단건 vs 다건) **A.** **단건 등록 API** 사용을 권장합니다. * 다건 등록은 추후 지원 중단(Deprecate) 검토 중입니다. * **검수:** 단건 등록 시에도 자동으로 검수 요청 프로세스가 동작합니다.
Q. 가격(salePrice) 및 재고 설정 **A.** * **할인 적용:** `salePrice`에는 **할인이 적용된 최종 판매가**를 입력해야 합니다. (예: 정상가 10,000원, 2,000원 할인 → `salePrice`: 8,000원) * **옵션:** `options`와 `stocks.options`는 동일한 옵션값을 의미합니다.
Q. 상품 식별자 매핑 (stocks.id) **A.** `stocks.id`는 `stocks.itemId`와 1:1 관계이며, 옵션의 유니크한 키로 사용 가능합니다. * **주의:** 옵션 ID가 별도로 없는데 기존 옵션을 추가/제거해서 전송하면 **새로운 옵션 ID가 발급**됩니다.
Q. 판매 중지 / 재개 / 숨김 처리 API **A.** 별도의 상태 변경 API를 사용합니다. * **판매 중지:** 재고 수정 API를 통해 재고를 0으로 변경. * **숨김 처리:** `상품 정보 노출 상태 숨기기로 변경` API 사용 (앱 미노출). * **삭제 확인:** 삭제된 상품의 정보는 조회 불가.
Q. 배송비 템플릿과 정책의 관계 (deliveryPolicy) **A.** **배송비 묶음 그룹과 배송비 정책은 서로 결합되어 있지 않습니다.** * **템플릿 역할:** 배송비 템플릿(`isMain=true` 등)은 상품 등록 시 정책을 **Pre-fill(미리 채워주기)** 해주는 역할만 합니다. * **적용:** 템플릿 유무와 관계없이, 상품 등록 시 입력한 개별 `deliveryPolicy`가 최종적으로 적용됩니다.
Q. 묶음 배송(deliveryLocationId) 및 조건부 무료 로직 **A.** * **ID Null:** 묶음 배송 불가 (개별 배송). * **ID 동일:** 동일한 `deliveryLocationId`를 가진 상품끼리 묶음 배송 가능. * **배송비 부과 기준:** 같은 그룹 내 상품 중 **가장 낮은 배송비**를 보장하는 정책 하나가 적용됩니다. * **조건부 무료(`minimumPurchasePrice`):** 동일한 묶음 배송 그룹에 속한 상품들의 **판매가 합계**를 기준으로 충족 여부를 판단합니다.
Q. 제주/도서산간 지역 설정 **A.** 제주와 도서산간의 배송 가능 여부를 **각각 분리하여 설정할 수 없습니다.** (통합 설정만 가능)
*** ### 4. 주문
Q. 주문 식별자 (Unique Key) **A.** * **주문:** `orderId` * **주문 상품:** `orderProductId` (주문상품번호). 각 품목(Item)에 대한 유니크 키입니다.
Q. 주문/배송 정보 상세 **A.** * **무통장 입금:** 미지원. * **제주/도서산간 여부:** 제주는 6으로 시작하는 우편번호, 도서산간은 토스쇼핑 자체 우편번호 목록 기준. * **송장 유효성:** API 단계에서 가송장 여부 등 유효성은 체크하지 않습니다. * **교환/반품 송장:** 교환/반품 송장 등록 기능은 현재 지원하지 않습니다.
Q. 주문 상태 변경 (취소/거부) **A.** '판매자 취소', '취소 거부', '취소 승인' 등은 API로 제공되지 않으며 토스 셀러 어드민에서 처리해야 합니다.
Q. 배송비의 유형과 정산 **A.** 1. **배송비 (초도배송비):** 최초 주문 시 부과. 2. **반품/교환 배송비:** 고객 귀책 시 발생. 3. **도서산간 추가 배송비:** 지역 특성에 따라 추가 부과.
Q. 주문 상태 전이 전체 플로우는? 정상 흐름: `BEFORE_PAYMENT` → `PAID`(결제완료) → `PREPARING_PRODUCT`(상품준비중) → `DELIVERING`(배송중) → `DELIVERED`(배송완료) → `CONFIRMED_ORDER`(구매확정) 취소/클레임: `CLAIM_REQUESTED_CANCEL`(취소요청), `CANCELED_PAYMENT`(결제취소), `CLAIM_REJECTED_CANCEL`(취소거절), `REQUESTED_EXCHANGE` / `ONGOING_EXCHANGE` / `COMPLETED_EXCHANGE` / `CLAIM_REJECTED_EXCHANGE`(교환), `REQUESTED_RETURN` / `ONGOING_RETURN` / `COMPLETED_RETURN` / `CLAIM_REJECTED_RETURN`(반품), `CLAIM_COLLECTING`(수거중), `CLAIM_COLLECTED`(수거완료), `CLAIM_DELIVERING`(재배송중), `REVOKED_REQUEST`(구매자 요청 철회)
Q. 주문번호(orderId) 생성 체계는? **A.** **Auto-increment** 방식으로 자동 증가. 기존보다 낮은 번호로 생성될 수 없습니다. * 1회 주문 시 `orderId` 1개 생성, 아이템별로 `orderProductId`가 각각 부여됨 * 묶음배송 여부와 관계없이 동일 구조 (동일 `orderId` 내 복수 `orderProductId`)
Q. 실시간 주문/재고 체크용 Webhook/Hook API가 있나요? **A.** **미제공**. 결제 전 실시간 재고/가격 체크 전용 훅 API는 없습니다. * 주문: `GET /orders/v2`로 **주기적 폴링**(예: 10분 배치) 후 `PAID` 상태 주문 수집, `PUT /orders/products/status`로 '상품준비중' 처리 * 재고: `GET /products/{productId}`로 직접 호출
*** ### 5. 배송
Q. 토스쇼핑 배송 방법(deliveryMethod)은 어떻게 구분되나요? **A.** 2가지입니다. * **`NORMAL`**(일반배송): 기본값 3일, 최대 14일. 발송지연 시 최대 30일까지 연장 가능 (주문당 1회) * **`TODAY_DELIVERY`**(오늘출고): 결제 당일 **오후 2시 이내** 출고. `deliveryDeadline`(10:00\~23:00, 30분 단위) 필수 설정 설치 상품 등 30일 초과 배송이 필요한 경우 **2026.04.20부터 배포되는 '희망 배송일' 설정** 기능을 활용할 수 있습니다.
Q. 택배사는 어떤 곳을 지원하나요? **A.** CJ대한통운, 우체국택배, 한진, 로젠, 롯데 등 **48개 이상** 지원합니다. **'직접전달'** 옵션도 택배사 필드에 포함되어 있어 택배사 코드 없이 발송 처리가 가능합니다. 택배사와의 연동(수거/송장 자동화)은 미지원이므로 **판매자 직접 접수** 방식입니다.
Q. 발송지연은 어떻게 처리하나요? **A.** `PUT /orders/products/status`에서 `status='발송지연'` + `shippingDeadlineAt`(발송예정일) 설정. * **주문당 1회**만 가능 * **결제완료 후 3영업일 이내** 주문건만 적용 * 최대 **30일**까지 연장 * 발송지연 후 '상품준비중' 상태로 복귀 불가
Q. 발송 기한 내 미처리 시 자동 환불되나요? **A.** 직접 자동환불은 아니지만, **구매자 취소요청 후 7영업일 미처리 시 자동 승인+환불 처리**됩니다.
Q. 우편번호 자릿수는? **A.** 현행 우정사업본부 **5자리** 우편번호 기준입니다. 주문/교환반품지 등록 시 모두 동일한 `zipCode` 필드 사용.
Q. 개별 우편번호 단위 배송불가 설정이 가능한가요? **A.** **불가**. 제주/도서산간 단위(`isJejuAndIslandsMountainsDelivery=false`)로만 배송불가 설정이 가능하며, 개별 우편번호 단위의 세부 배송불가 지역 설정 API는 없습니다. 결제 완료 후 배송 불가 사유로 주문 실패 처리 시에는 판매자 직접 취소 API(`seller-cancel`)로 즉시 결제취소+환불 처리 가능합니다.
Q. 한 주문에 배송지를 2개 이상 지정할 수 있나요? **A.** **불가**. 토스쇼핑 주문 구조상 **1개 주문(`orderId`)에 1개 배송지**만 입력 가능합니다. 복수배송지가 필요하면 고객이 별도 주문으로 분리해야 합니다.
Q. 배송비 최대/최소 제한 금액이 있나요? **A.** 없습니다. 최소 > 0 조건만 존재합니다.
Q. 반품비/교환비 등록 단위는? (보완) **A.** * 반품비: **편도 기준** (`refundOneWayDeliveryFee`) * 교환비: **왕복 기준** (`exchangeRoundTripDeliveryFee` = 수거비 + 재배송 합산) * 각각 별도 필드로 등록하며, 제주/도서산간 추가비는 반품=편도추가비, 교환=편도추가비×2 방식으로 합산 부과됩니다. > 파트너사에서 반품/교환을 각각 '왕복'으로 등록 중인 경우, **토스쇼핑 반품비는 왕복금액의 1/2를 편도로 환산**하여 입력해야 합니다.
Q. 묶음배송 기준은 판매자의 출하지 기준인가요? **A.** **맞습니다**. 출고지가 같아야 묶음이 가능하며, 동일 `deliveryLocationId` 내에서 묶음배송이 적용됩니다. 배송비는 **묶음 내 최저 배송비 기준**. 혼합주문(묶음+비묶음)은 최저 배송비 + 미설정 상품 배송비 합산.
Q. 아이템별 분리발송(멀티 송장)이 가능한가요? **A.** * **아이템별 개별 송장 등록**: 가능. `PUT /orders/products/delivery`가 `orderProductId` 단위이므로 아이템별 서로 다른 택배사+송장번호 등록 가능 * **수량 단위 분리발송**: 불가. 동일 아이템의 수량을 분리 배송하거나, 동일 아이템을 여러 송장으로 쪼개는 것은 지원하지 않습니다. 부분취소/반품도 옵션 단위만 가능하며 수량 단위 부분 처리는 불가. * **송장번호 유일성 검증 없음**: 동일 송장번호를 여러 아이템/여러 주문에 등록 가능. 가송장 여부는 API 단계에서 검증하지 않습니다.
Q. 택배사 정보 없이 '직접전달'로 처리하면 배송완료는 어떻게 잡히나요? **A.** '직접전달' 옵션 사용 시 택배사 자동 추적이 불가하므로, **엑셀 일괄 업로드 또는 파트너스 어드민에서 수동으로 배송완료 처리**하면 됩니다. 파트너사와 토스쇼핑이 각자 택배사 배송추적을 독립적으로 처리하는 것도 가능합니다.
*** ### 6. 클레임 (취소/교환/반품)
Q. 부분 취소/교환/반품 가능 여부 **A.** * **가능:** 주문 내 상품 A, B 중 A만 취소. * **불가능:** 상품 A를 2개 샀을 때, **1개만 부분 취소(수량 분할)** 하는 것은 불가능.
Q. 철회 기능 **A.** 고객은 셀러 승인 전까지 요청을 철회할 수 있습니다.
Q. [상세] 고객 귀책 반품/교환 시 비용 청구 공식 **A.** 제주/도서산간 추가 비용은 아래 공식대로 합산되어 고객에게 결제 요청됩니다. **1. 반품 시 (`refundOneWayDeliveryFee`)** * 일반: `반품배송비(편도)` * 제주: `반품배송비(편도)` + `제주 추가비(편도)` * 도서산간: `반품배송비(편도)` + `도서산간 추가비(편도)` **2. 교환 시 (`exchangeRoundTripDeliveryFee`)** * 일반: `교환배송비(왕복)` * 제주: `교환배송비(왕복)` + **`제주 추가비(편도) * 2`** * 도서산간: `교환배송비(왕복)` + **`도서산간 추가비(편도) * 2`**
Q. [상세] 고객 귀책 반품 시 '초도배송비' 차감 로직 **A.** 반품 배송비 외에 **초도배송비**가 환불금에서 차감되는 경우는 다음 두 가지입니다. 1. **조건부 무료 깨짐:** (부분)반품으로 인해 무료배송 조건이 미충족 된 경우. 2. **전체 반품:** 무료배송으로 받은 건을 전체 반품한 경우. * *참고: 판매자 귀책 시에는 배송비 추가 결제나 차감이 없습니다.*
Q. 주문 취소 API에는 어떤 종류가 있나요? **A.** 1. **판매자 직접 취소** (`POST /order-products/{orderProductId}/seller-cancel`) * 판매자가 직접 취소. 거의 모든 상태(PAID, 상품준비중, 배송중, 배송완료, 구매확정, 교환/반품 진행중 등)에서 `CANCELED_PAYMENT`로 강제 전이 가능 (BEFORE\_PAYMENT, COMPLETED\_RETURN 제외) * `reason`(취소사유), `deliveryPenaltyCharger`(USER/MERCHANT) 필드 포함 2. **구매자 취소요청 승인** (`POST /claims/{claimId}/cancel/approval`): 자동 환불 + 결제 취소 3. **구매자 취소요청 거절** (`POST /claims/{claimId}/cancel/rejection`): 택배사 + 송장번호 필수 → 배송중 전환 4. **결제완료 상태에서 구매자 취소**: 자동 처리 (판매자 API 호출 불필요)
Q. 품절로 인한 주문 취소 처리는? **A.** 판매자 직접 취소 API로 처리합니다. 클레임 진행 중에도 가능합니다. * `remainingCount=0`으로 재고 수정 시, **이후 발생하는 주문은 자동으로 주문 취소**되므로 판매취소 API를 별도로 호출할 필요는 없습니다. * 단, 상품의 판매 상태 자체가 '일시품절'로 자동 변경되지는 않습니다 (재고 0만 반영).
Q. 판매자 동의 없이 토스쇼핑이 강제 취소하는 경우가 있나요? **A.** **있습니다**. 구매자 취소요청 후 **7영업일 미처리** 시 자동 승인 + 환불 처리됩니다 (강제 취소). 기한 내 승인 또는 거절 처리가 필요합니다.
Q. 반품 프로세스 흐름은? **A.** `REQUESTED`(반품요청) → 판매자 승인(`POST /claims/{claimId}/return/approval`) → `COLLECTING`(수거중) → `COLLECTED`(수거완료) → 판매자가 반품완료 API(`POST /claims/{claimId}/return/completion`) 호출 → `COMPLETED`(반품완료 + 환불) * **선환불이 아닌 후환불** 구조: 수거완료 후 반품완료 처리 시점에 환불 실행 * 수거 완료 후 상품 확인 후 반품 완료 또는 거절(`POST /claims/{claimId}/return/rejection` 또는 `collection-rejection`) 처리 가능 * **수거완료 후 8영업일 미처리 시 자동 반품완료 + 환불** (수거완료 후 5영업일 이상 환불 미처리 시 페널티 부과) * 택배사 연동 미지원 → **판매자가 직접 수거 접수** 필요
Q. 반품 수거 전/후 거절 시 반품배송비는? **A.** * 수거 **전** 거절: 반품배송비 환불됨 * 수거 **후** 거절(`collection-rejection`): 반품배송비 **미환불** (구매자와 별도 소통 필요)
Q. 반품 요청이 들어왔는데 고객이 철회했습니다. **A.** 클레임 상태에 `REVOKED_REQUEST`(구매자의 요청 철회)가 존재합니다. 수거 전에는 구매자가 직접 철회 가능하며, 수거 진행 중에는 판매자가 `collection-rejection`으로 거절 처리 가능합니다.
Q. 반품 수거 전/후 거절 시 반품배송비는? **A.** * 수거 **전** 거절: 반품배송비 환불됨 * 수거 **후** 거절(`collection-rejection`): 반품배송비 **미환불** (구매자와 별도 소통 필요)
Q. 구매확정 이후에 반품이 가능한가요? **A.** * **구매자**: 구매확정 이후 취소/반품 요청 **불가** (결제완료/상품준비중/발송지연 상태에서만 취소 요청 가능) * **판매자**: 구매확정 상태에서도 주문취소 가능 (반품배송비 차감/미차감 선택)
Q. 교환 프로세스와 반품의 차이는? **A.** 토스쇼핑에서 반품과 교환은 **별도 클레임**으로 관리됩니다 (`ClaimType`: `CANCEL` / `EXCHANGE` / `RETURN`). * **교환**: 승인(`/exchange/approval`) → `COLLECTING`(수거중) → `COLLECTED`(수거완료) → `DELIVERING`(재배송중, `/exchange/delivery`에 택배사+송장번호 입력) → `COMPLETED`(교환완료). 즉 **선수거 후 재배송** 방식 * **교환 거절**(`/exchange/rejection`, 거절사유 최대 150자) 후 **반품으로 자동 전환은 불가**. 고객이 별도로 반품 클레임을 생성해야 합니다. * **교환 거절일로부터 7일 후 자동 구매확정**
Q. 교환 수거 전/후 거절 시 교환배송비는? **A.** * 수거 **전** 거절: 교환배송비 환불 * 수거 **후** 거절(`exchange/collection-rejection`): 교환배송비 **미환불**
Q. 부분취소/부분반품의 허용 범위는? (보완) **A.** * **아이템별 부분취소/반품**: 가능 (주문 내 상품 A, B 중 A만 취소/반품) * **수량별 부분취소/반품**: 불가 (동일 상품 2개 중 1개만 부분 처리 불가)
*** ### 7. 정산 및 데이터 대사
Q. 정산 데이터 구조 * **데이터 분리:** 상품 정산 내역과 배송비 정산 내역은 **별도의 Row**로 나뉘어 들어옵니다. * **배송비 매핑:** 배송비 객체에도 `orderId`가 있어 원주문과 연결 가능합니다. * **상태값:** `CONFIRMED_ORDER` (구매확정), `CANCELED_PAYMENT` (결제취소/반품).
Q. 정산 지급 일정 (D+2 영업일) 지급일(`payoutDate`) 당일, 배치 작업 완료 후 API 조회가 가능합니다. | **구매확정 요일** | **정산 지급(조회) 요일** | | ----------- | ---------------- | | 월요일 | **수요일** | | 화요일 | **목요일** | | 수요일 | **금요일** | | 목요일 | **월요일** | | 금/토/일요일 | **화요일** |
Q. 세금계산서 품목 및 결제수단 매핑 API에서 제공하는 정보를 통해 아래와 같이 4개 품목으로 매핑합니다. | **세금계산서 품목 (Group)** | **매핑할 실제 결제수단 (API 값)** | | -------------------- | ----------------------- | | **카드** | 신용카드, 체크카드 | | **토스머니** | 토스머니, 토스페이머니, 계좌이체 |
Q. 정산 API의 조회 조건(dateCondition)에는 어떤 값이 있나요? **A.** `GET /settlement-steps`에서 다음 조건으로 조회 가능합니다. * `PAYOUT_DATE`(지급일) * `PAYOUT_BASE_DATE`(지급기준일 = 구매확정일) * `TRANSACTION_DATE`(거래일) * `DIFF_SETTLEMENT_PAYOUT_DATE`(차액정산 지급일)
Q. 수수료 반올림 처리 규칙은? **A.** * **수수료**: 소수점 **버림** * **부가세(VAT)**: 소수점 **반올림**
Q. 배송비에는 어떤 수수료가 붙나요? **A.** 배송비에는 **결제수수료만** 부과됩니다. 상품판매수수료는 배송비에 적용되지 않습니다.
Q. 수수료 산정 기준이 언제 변경되나요? **A.** * **\~2026.01.18**: 할인쿠폰/적립금 등 차감 **전** 판매가액 기준 * **2026.01.19\~**: **판매가액 - 셀러부담쿠폰 할인액** 기준 (`feeBaseAmount`)
Q. 탈퇴 유저 환불 시 수수료/세금계산서 처리는? **A.** 탈퇴 유저의 환불은 **수수료 및 계산서 반영이 불가**한 케이스가 있습니다 (상세 기준은 확인 중). 반영 불가의 범위(환불 금액 전체 vs 취소수수료만)는 케이스별로 구분됩니다.
Q. 광고비는 별도 정산인가요? **A.** **별도 정산**됩니다. 판매수수료와 분리되어 다음 방식으로 처리됩니다. * 광고 진행월 **1일\~말일** 기준 집행된 광고비(유상 비즈니스 머니 기준)로 정산 * **세금계산서는 익월 3영업일** 발행 (선불/판매대금 상계 방식과 무관) * CPC(토스애즈)는 익월 **3영업일 고정**, DA는 광고 집행월 익월 **3\~5영업일** 발행 * 익월 2영업일 이전 발행은 **현행 정책상 지원하지 않음**
Q. 세금계산서 발행 일자/기준은? **A.** * **판매 정산(수수료) 세금계산서**: 구매확정일 기준, 매월 1일\~말일 수수료 기준, **매월 1영업일 오전**에 전월분 발행 * 구매자 세금계산서 발행은 미지원 (카드영수증 / 현금영수증으로 대체)
*** ### 9. 운영(문의, 쿠폰, 고객)
Q. 장바구니 쿠폰 미적용 디폴트 설정이 가능한가요? **A.** API로는 불가. 필요 시 **토스쇼핑파트너스 어드민에서 상품/상점 단위로 직접 설정**해야 합니다.
Q. 토스쇼핑 상품이 네이버 가격비교 등 외부에 노출되나요? **A.** **노출되지 않습니다**. 토스쇼핑은 토스 앱 내에서만 운영되며, 외부 가격비교 사이트에는 별도 노출되지 않습니다.
Q. 특정 상품/셀러의 쿠폰 적용을 제어할 수 있나요? **A.** **상품별 쿠폰 제어 전용 API는 미제공**입니다. 대신 토스쇼핑파트너스 어드민에서 **상품(옵션) 단위** 또는 **상점 단위**로 직접 설정 가능합니다. 셀러 부담 쿠폰(`shoppingDiscountMerchant`)도 파트너스 어드민에서 별도 생성/제어합니다.
Q. 판매자가 이미 할인 중인 상품은 판매가와 할인가를 각각 연동하면 되나요? **A.** * `originPrice`: 정상가 (권장소비자가 / 원래 가격) * `salePrice`: 판매가 (쿠폰 적용 전, 셀러가 지정한 실제 판매 가격). 토스쇼핑 UI에는 정상가 취소선 + 판매가 노출 구조 * **토스쇼핑은 상품 단위에 '할인가'를 별도 필드로 두지 않음**. 쿠폰이 적용된 최종 판매가는 상품 정보에서 다루지 않고 정산 시에만 다룸 * 셀러의 할인가를 `salePrice`에 넣을지, `originPrice`에 원가를 넣고 `salePrice`에 할인가를 넣을지는 운영 정책에 따라 결정
Q. 고객 연락처는 안심번호로만 제공되나요? **A.** 주문 조회 시 두 종류의 필드가 제공됩니다. * `ordererPhone` / `receiverPhone`: **안심번호(가상번호)**. 기본 노출 * `ordererRealPhone` / `receiverRealPhone`: **실번호**(nullable). 제공 여부는 별도 협의 필요 * 이름/연락처/상세주소는 기본적으로 **마스킹 처리** 되며, 판매자가 '마스킹 해제'로 열람 가능 * 안심번호 유효기간: 주문이 **종결(구매확정 또는 취소)** 되기 전까지 유지
Q. 판매자 CS 번호/이메일 설정은? **A.** * CS 번호: **대표번호로 수정 가능** * CS 이메일: 고객에게 노출되지 않으나, 회사 대표메일 또는 별도 메일로 등록 가능 * 판매자 → 토스쇼핑 문의는 **파트너스 우측 하단 채팅 상담** 또는 **1644-2944** 사용 * 별도 핫라인 제도는 공식 운영하지 않으며, B2B 고객센터 문의 시 개발팀 확인 가능한 채널로 인입 가능
Q. 고객 알림(SMS/알림톡)은 누가 발송하나요? **A.** 토스쇼핑은 **알림톡**으로 고객 알림을 발송하며, 발송 지연 시 자동 안내 알림톡이 나갑니다. 주문 접수 시 실시간 알림은 미발송(판매자가 수동 확인 필요). 판매자가 별도 알림톡(개인정보 취득, 배송안내, 품절 취소 등)을 보내는 프로세스는 없습니다.
Q. Q&A(1:1 문의)는 어떻게 제공되나요? **A.** 기존 게시판 형태에서 **비즈톡으로 변경**되었습니다 (이전 게시판 형태는 없어짐). 문의 API로 조회 및 답변 가능하며, 셀러가 직접 답변을 작성합니다.
Q. API Rate Limit 세부 스펙은? **A.** * **쓰기 API**: 초당 **30건** / 버킷 100 (Token Bucket) * **읽기 API**: 초당 **50건** / 버킷 100 * 한 IP당 초당 50개씩 충전해 주고 최대 200개 까지 요청 가능 * Rate Limit 키: `api:{METHOD PATH}:{merchantId}` (셀러 × API x IP 단위로 제한) * 초과 시: HTTP **200** + body `errorCode = "TOO_MANY_REQUEST"` * API별 독립 제한이 아닌 **전체 쓰기 / 전체 읽기 기준**으로 적용됩니다.
Q. 블랙리스트 고객 관리가 되나요? **A.** **불가**. 현재 블랙 고객 관리 정책/기능은 없습니다. 판매자가 요청하더라도 개별 고객 블랙 처리는 지원하지 않습니다.
Q. 라이브 스트리밍 송출이나 편성표 노출이 지원되나요? **A.** **미지원**. 라이브 스트리밍 연동, 편성표 노출, 전용 매장/전문관/브랜드샵 UX/UI, 전용 노출 영역 등은 현재 모두 미지원입니다.
Q. 판매자 어드민에서 등록한 상품과 API 등록 상품을 동기화할 수 있나요? **A.** 현재 **EP(Export/Publish) 기능은 미지원**. 데이터 싱크가 필요하면 **상품 수정 API**로 업데이트하는 방식을 권장합니다. API로 등록한 상품의 어드민 수정 자체는 가능합니다.
Q. 재고 연동 비중(예: 20% 재고만 연동)에 토스쇼핑 측 제한이 있나요? **A.** 없음. `remainingCount`는 **셀러가 API 호출 시 직접 설정**하는 값이므로 연동 비중은 **셀러 자체 결정 사항**입니다. 토스쇼핑 시스템상 별도 제한은 없습니다.
*** ### 정산 산식 모음
Q. 주요 금액 필드 산식 | **항목** | **API 필드명** | **계산 산식 (Formula)** | **비고** | | ---------------------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | | **정산 기준금** | `orderProductPrice` | **판매가 × 수량** | | | `stockPrice * quantity` | **\[변경됨]** 쿠폰 차감 전 순수 판매가 총액 | | | | **수수료 기준금** | `feeBaseAmount` | **정산 기준금 - 셀러쿠폰** | | | `orderProductPrice - shoppingDiscountMerchant` | **\[신규]** 수수료 부과 기준액 | | | | **유저 결제액** | `orderProductPaidAmount` | `orderProductPrice` - `TotalDiscount` | 고객 실 결제 금액 | | **실 지급액** | `settlementAmount` | `feeBaseAmount` - `TotalFees` | 최종 입금액 | | **상품 수수료율** | **`productFeeRate`** | **`productFee`(상품 수수료) / `amountForFee`** | *(참고: 이 공식으로 수수료율이 역산되어 계산됩니다)* | | **정산금액** | **`settlementAmount`** | **(주문금액) - (모든 수수료 및 부가세) - (셀러부담쿠폰)** | • 상세: `주문금액(판매가+배송비)` - `결제수수료` - `결제VAT` - `상품수수료` - `상품VAT` - `셀러부담쿠폰할인액` | | **프로모션 할인 금액** | `shoppingDiscount` | `shoppingDiscountToss`(토스 부담 쿠폰 할인) + `shoppingDiscountMerchant`(셀러 부담 쿠폰 할인) + `extraDiscout`(주문 상품별 안분된 추가 할인 금액) | |
Q. 할인 항목 매핑 (토스쇼핑파트너스 어드민과 비교) * `shoppingDiscountMerchant` = 어드민 **'쿠폰 할인 부담금'** * `shoppingDiscountToss` = 토스 부담 쿠폰 + 추가할인(`extraDiscount`)
Q. 결제 상태별 상세 산식 **1. PAY (결제 건)** * `orderProductPaidAmount` = `orderProductPrice` - `shoppingDiscount` - `tossPayDiscount` - `tossPayPoint` * `settlementAmount` = `feeBaseAmount` - (`수수료 합계`) **2. REFUND (환불 건)** * `orderProductPaidAmount` = `orderProductPrice` + `shoppingDiscount` + `tossPayDiscount` + `tossPayPoint` * `settlementAmount` = `feeBaseAmount` + (`수수료 환급`)
--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://shopping-docs.toss.im/dev/faq.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.