API 자주 묻는 질문
API 연동/사용에 대한 FAQ입니다.
0. API 공통 / 일반
Q. API 응답값이 None인 경우 성공/실패 확인 방법
A. 문서상 Response Body가 None으로 표기되어 있더라도, 실제 응답에는 resultType이 반드시 포함됩니다. 이 값이 SUCCESS인지 FAIL인지로 성공 여부를 판단하시면 됩니다.
Q. clientId & clientSecret 발급 절차
A. 토스쇼핑 파트너 시스템 계정 발급 후, 토스 쇼핑 API 서버 및 테스트앱 접근 가이드를 통해 발급받으실 수 있습니다.
1. 상품 관리
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): 동일한 묶음 배송 그룹에 속한 상품들의 판매가 합계를 기준으로 충족 여부를 판단합니다.
2. 주문 및 배송
Q. 주문/배송 정보 상세
A.
무통장 입금: 미지원.
제주/도서산간 여부: 제주는 6으로 시작하는 우편번호, 도서산간은 토스쇼핑 자체 우편번호 목록 기준.
송장 유효성: API 단계에서 가송장 여부 등 유효성은 체크하지 않습니다.
교환/반품 송장: 교환/반품 송장 등록 기능은 현재 지원하지 않습니다.
3. 클레임 (취소/교환/반품)
Q. [상세] 고객 귀책 반품/교환 시 비용 청구 공식
A. 제주/도서산간 추가 비용은 아래 공식대로 합산되어 고객에게 결제 요청됩니다.
1. 반품 시 (refundOneWayDeliveryFee)
일반:
반품배송비(편도)제주:
반품배송비(편도)+제주 추가비(편도)도서산간:
반품배송비(편도)+도서산간 추가비(편도)
2. 교환 시 (exchangeRoundTripDeliveryFee)
일반:
교환배송비(왕복)제주:
교환배송비(왕복)+제주 추가비(편도) * 2도서산간:
교환배송비(왕복)+도서산간 추가비(편도) * 2
Q. [상세] 고객 귀책 반품 시 '초도배송비' 차감 로직
A. 반품 배송비 외에 초도배송비가 환불금에서 차감되는 경우는 다음 두 가지입니다.
조건부 무료 깨짐: (부분)반품으로 인해 무료배송 조건이 미충족 된 경우.
전체 반품: 무료배송으로 받은 건을 전체 반품한 경우.
참고: 판매자 귀책 시에는 배송비 추가 결제나 차감이 없습니다.
4. 정산 및 데이터 대사
Q. 정산 데이터 구조
데이터 분리: 상품 정산 내역과 배송비 정산 내역은 별도의 Row로 나뉘어 들어옵니다.
배송비 매핑: 배송비 객체에도
orderId가 있어 원주문과 연결 가능합니다.상태값:
CONFIRMED_ORDER(구매확정),CANCELED_PAYMENT(결제취소/반품).
Q. 정산 지급 일정 (D+2 영업일)
지급일(payoutDate) 당일, 배치 작업 완료 후 API 조회가 가능합니다.
구매확정 요일
정산 지급(조회) 요일
월요일
수요일
화요일
목요일
수요일
금요일
목요일
월요일
금/토/일요일
화요일
Q. 세금계산서 품목 및 결제수단 매핑
API에서 제공하는 정보를 통해 아래와 같이 4개 품목으로 매핑합니다.
세금계산서 품목 (Group)
매핑할 실제 결제수단 (API 값)
카드
신용카드, 체크카드
토스머니
토스머니, 토스페이머니, 계좌이체
5. 정산 산식 모음
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-tossPayPointsettlementAmount=feeBaseAmount- (수수료 합계)
2. REFUND (환불 건)
orderProductPaidAmount=orderProductPrice+shoppingDiscount+tossPayDiscount+tossPayPointsettlementAmount=feeBaseAmount+ (수수료 환급)
마지막 업데이트
도움이 되었나요?