공통 규약

응답 형식, 오류 코드, 재시도, 호출 제한, 일 사용 상한, 페이징 등 모든 API 호출에 공통으로 적용되는 규칙입니다.

인증·환경 설정은 연동 시작하기를 먼저 보세요.

공통 응답 형식

쇼핑 서버의 응답은 아래 공통 형식을 사용합니다. OAuth 토큰 발급 응답과 API 게이트웨이에서 먼저 거절한 응답은 형식이 다를 수 있습니다.

성공

{
  "resultType": "SUCCESS",
  "success": {
    // 각 API별 응답 본문
  }
}

실패

{
  "resultType": "FAIL",
  "error": {
    "errorType": 400,
    "errorCode": "INVALID_ARGUMENT",
    "reason": "오류 내용"
  }
}

HTTP 상태 코드와 응답 본문을 함께 확인해 주세요. HTTP 200이어도 resultType: "FAIL"이면 실패입니다. 공통 응답 형식일 때는 resultType으로 성공 여부를 판단하고, 실패 원인은 error.errorCode와 error.reason에서 확인합니다. errorType: 400은 본문의 오류 분류이며 HTTP 400을 뜻하지 않습니다.

HTTP 상태와 본문은 이렇게 구분해요

입력값 검증 항목은 인증·권한 등 앞선 검사를 통과한 요청을 기준으로 설명합니다. 앞선 검사에서 거절되면 그 실패가 먼저 응답됩니다.

상황

HTTP 상태

resultType

error.errorCode

요청 성공

200

SUCCESS

해당 없음

상품 상세 ID 누락·숫자 형식 오류·중복 제거 후 30건 초과, 조회 기간·페이지 크기 등 값 검증 실패

200

FAIL

INVALID_ARGUMENT

필수 요청 파라미터 누락, 날짜·숫자·열거형 변환 실패, 잘못된 JSON 등 요청을 읽는 단계의 오류

400

FAIL

고정된 값이 있다고 가정하지 마세요

등록되지 않은 출발지 IP 등 쉐어링크 접근 인가 실패

200

FAIL

SHARELINK_OPENAPI_ACCESS_DENIED

일 사용 상한 초과

200

FAIL

SHARELINK_OPENAPI_QUOTA_EXCEEDED

링크 발급 대상 ID가 모두 없는 경우

200

FAIL

고정된 코드가 없으므로 error.reason도 확인하세요

쇼핑 서버의 예기치 못한 오류

200

FAIL

500

게이트웨이·인증·통신 단계에서 거절되거나 실패

4xx·5xx 등

공통 형식이 아닐 수 있음

HTTP 상태·헤더·본문을 함께 기록하세요

예를 들어 상품 상세의 tacaItemIds는 문자열로 받은 뒤 값을 검사하므로 숫자가 아닌 값도 HTTP 200 + INVALID_ARGUMENT로 응답합니다. 반면 실적 조회의 fromDate는 날짜로 읽어야 하므로, 날짜 형식 자체가 잘못되면 HTTP 400으로 거절됩니다. 같은 "입력 오류"라도 발생 단계가 다릅니다.

실제 데이터는 success 안에서 읽으시면 됩니다.

오류 코드

알려진 실패 원인은 error.errorCode 로 판별해 주세요. 모든 오류에 고정 코드가 있는 것은 아닙니다. 코드가 없거나 모르는 값이면 HTTP 상태와 error.reason을 함께 기록하세요.

errorCode

의미

조치

INVALID_ARGUMENT

요청을 읽은 뒤의 값 검증 실패입니다. 상품 상세 ID 오류, 조회 기간·페이지 크기 오류, 존재하지 않는 categoryId 등이 해당합니다

요청 형식을 고쳐 주세요. 재시도해도 결과가 같습니다

SHARELINK_OPENAPI_ACCESS_DENIED

인증 정보 무효·폐기, 등록되지 않은 출발지 IP, 비활성 거래처, 등록되지 않았거나 다른 거래처의 subTagId·publisherId 중 하나입니다

인증 정보 상태, 어드민에 등록하신 호출 서버 IP를 확인해 주세요. 링크 발급만 실패하면 요청에 넣은 publisherId·subTagId도 확인하세요

SHARELINK_OPENAPI_QUOTA_EXCEEDED

오늘 쓰실 수 있는 일 사용 상한을 모두 사용하셨습니다

이 페이지의 일 사용 상한 을 참고해 주세요. 자정(KST)에 리셋됩니다

500

서버 오류. HTTP 200 + errorCode: "500"(문자열)로 내려갑니다

잠시 후 재시도해 주세요

OPENAPI_SUB_TAG_*

subTag 관리 전용 오류입니다

subTag 관리의 오류 코드 를 봐 주세요

INVALID_CURSOR

주문 이벤트 조회 전용 오류입니다. 커서가 손상됐습니다

주문 이벤트 조회의 오류 처리 를 봐 주세요. 재시도해도 결과가 같습니다

HTTP 401을 받으면 토큰 누락·만료·유효성을, HTTP 403을 받으면 응답 사유와 필요한 스코프를 확인하세요. HTTP 403만 보고 출발지 IP 오류라고 단정하지 마세요. 쇼핑 서버의 출발지 IP 인가 실패는 위 표의 HTTP 200 + SHARELINK_OPENAPI_ACCESS_DENIED로 구분합니다. HTTP 429는 호출 속도 제한 안내에 따라 처리하세요. 게이트웨이 응답의 오류 코드·본문은 공통 응답과 다를 수 있습니다. 파라미터 값 오류의 처리는 각 API 문서의 표를 따르세요.

쉐어링크 발급에는 errorCode 없이 reason만 오는 실패(ID 누락, 발급 제한 상품·판매자)가 있습니다. 그 페이지의 안내를 따라 주세요.

errorCode 는 추가될 수 있습니다. 목록에 없는 값이 오더라도 동작이 멈추지 않도록, 알 수 없는 errorCode 는 재시도하지 않는 실패로 처리하시고 로그에 남겨 주시길 권장드립니다.

문제가 계속된다면 발생 시각, 엔드포인트, 요청 파라미터, HTTP 상태 코드, 응답 헤더와 본문을 함께 전달해 주세요.

재시도

상황

처리

500 · HTTP 5xx · HTTP 429

지수 백오프로 재시도해 주세요. 429는 Retry-After 헤더를 우선 따릅니다

SHARELINK_OPENAPI_QUOTA_EXCEEDED

재시도하지 마세요. 자정(KST) 리셋 전까지는 결과가 같습니다

INVALID_ARGUMENT · INVALID_CURSOR · SHARELINK_OPENAPI_ACCESS_DENIED · HTTP 400·401·403

재시도하지 마세요. 요청이나 자격의 문제라 그대로 다시 보내도 결과가 같습니다. 원인을 고쳐야 합니다

조회 API(GET)는 멱등하므로 안전하게 재시도하실 수 있습니다.

호출 제한 (Rate Limit)

항목

기준

지속 한도

거래처 단위 10 rps (전 엔드포인트 합산)

순간 버스트

최대 30

초과 시

HTTP 429 + Retry-After 헤더

캐시·재사용 안내는 승인받은 제휴 목적 안에서 호출량을 줄이는 기술적 기준입니다. 캐시 기간을 짧게 유지하거나 소수 상품만 노출한다는 조건만으로 추천 페이지·외부 서비스의 운영이나 이미지 사용이 승인되는 것은 아닙니다. 서비스 사용 승인과 상품 이미지 사용 범위는 별도로 확인해 주세요. 사용 범위가 불분명하면 서비스 URL·노출 화면·저장 기간·이미지 사용 방식을 준비해 토스쇼핑 고객센터(https://toss-business.channel.io)에 문의해 주세요.

응답을 저장해서 재사용하시는 것을 전제로 설계해 주세요. 랭킹은 실시간이 아닙니다. 베스트 상품은 1시간 단위, 카테고리 베스트는 매일 09:00(KST)에 갱신되므로 그보다 자주 호출할 이유가 없습니다. 발급받은 쉐어링크도 저장해 두고 재사용하시면 됩니다.

일 사용 상한

바로 위 호출 제한이 순간 호출 속도를 제한한다면, 일 사용 상한은 하루에 가져가실 수 있는 총량을 제한합니다. 적용 지점과 초과 시 응답이 서로 다르므로 하나의 카운터로 합쳐 관리하지 마세요.

항목

기준

조회로 받은 상품

하루 10,000개

새로 발급한 링크

하루 10,000개

적용 단위

거래처(인증 정보 1벌) 단위

리셋

매일 자정(KST)

초과 시

HTTP 200 + errorCode: "SHARELINK_OPENAPI_QUOTA_EXCEEDED"

두 한도는 서로 독립적입니다. 합산되지 않으며, 한쪽을 다 쓰셔도 다른 쪽은 그대로 사용하실 수 있습니다.

한도를 모두 쓰신 뒤의 응답입니다. 호출 속도 제한(HTTP 429)과 달리 HTTP 200으로 내려가므로 errorCode 로 구분해 주세요.

{
  "resultType": "FAIL",
  "error": {
    "errorCode": "SHARELINK_OPENAPI_QUOTA_EXCEEDED",
    "reason": "오늘 사용할 수 있는 요청 한도를 모두 사용했어요."
  }
}

두 축 중 어느 쪽이 소진됐는지는 응답에 담기지 않습니다. 상품 조회와 링크 발급 중 어느 호출에서 받으셨는지로 판단해 주세요.

세는 방식

대상

세는 기준

상품 목록·상세 조회

응답에 담겨 나간 상품 수를 그대로 누적합니다. 같은 상품을 다시 조회하시면 그때마다 다시 차감됩니다

쉐어링크 발급

새로 발급된 링크만 셉니다. 같은 tacaItemId·publisherId·subTagId로 다시 요청하시면 기존 링크가 반환되므로 차감되지 않습니다. subTagId가 다르면 새 링크가 발급되어 1건 차감됩니다

연결성 확인·카테고리 조회 · subTag 관리 · 실적/정산 실적 조회 · 주문 이벤트 조회

상품을 반환하지 않으므로 차감되지 않습니다

한도는 요청을 받기 전에 확인하므로 응답이 도중에 잘리는 일은 없습니다. 남은 한도가 있으면 그 요청은 그대로 처리됩니다.

정상적인 연동에서는 한도에 닿지 않는 수준입니다.

자주 묻는 호출 한도 질문

한도 상향이 필요하면 어떻게 하나요?

한도 상향은 자동으로 제공되지 않으며, 사용 목적과 서비스 구조를 바탕으로 내부 검토가 필요합니다. 상향이 필요하시다면 아래 정보를 함께 전달해 주세요.

운영 중인 서비스 또는 사이트 URL
API를 사용하는 목적
예상 일 조회 상품 수
예상 일 링크 발급 수
캐시 주기와 재사용 방식
호출량이 늘어나는 시간대

전체 카테고리를 짧은 주기로 반복 조회하기보다는 필요한 범위만 조회하고, 이전 결과와 비교하는 방식을 권장합니다.

커서 페이징

상품 목록 API 3종(카테고리 베스트·베스트·하루특가)과 subTag 목록 조회·실적 조회·정산 실적 조회는 커서 방식으로 페이징합니다.

파라미터

설명

cursor

다음 페이지 조회 위치. 첫 요청에는 넣지 않습니다

size

한 번에 받을 개수

응답

필드

설명

nextCursor

다음 페이지 조회에 사용할 커서. 다음 페이지가 없으면 null

hasNext

다음 페이지 존재 여부

사용법

첫 요청은 cursor 없이 호출합니다.
응답의 hasNext가 true이면, nextCursor 값을 그대로 cursor에 담아 다시 호출합니다.
hasNext가 false가 될 때까지 반복합니다.

cursor 값은 내부 형식이 정해져 있지 않은 문자열입니다. 값을 해석하거나 직접 만들어 넣지 마시고, 직전 응답이 준 값을 그대로 전달해 주세요.

size 허용 범위와 범위를 벗어났을 때의 처리(자동 보정 또는 INVALID_ARGUMENT 거절)는 엔드포인트마다 다르니 각 문서를 확인해 주세요.

주문 이벤트 조회는 페이징 규약이 다릅니다. 다음 페이지 여부 필드가 hasNext가 아니라 hasMore 이고, nextCursor는 마지막 페이지에서도 null이 되지 않으며, 최신순(기록 ID 내림차순)으로 과거 방향으로만 넘어갑니다. 새 이벤트를 다시 보려면 커서 없이 새로 시작해야 합니다. 손상된 커서는 errorCode: "INVALID_CURSOR" 로 거절됩니다.

상품 카드 공통 필드

상품 목록 API 3종은 아래 필드를 공통으로 내려줍니다.

필드

타입

설명

tacaItemId

number

상품 옵션 ID. 상세 조회·링크 발급에 사용하는 식별자입니다

displayName

string

상품명

thumbnailUrl

string

썸네일 이미지 주소

productUrl

string

상품 페이지 주소. 추적이 없는 일반 링크입니다 (아래 주의사항 참고)

displayPrice

number

판매가 (원). 배송비가 포함된 금액입니다 (아래 주의사항 참고)

originalPrice

number

정가 (원)

discountRate

number

할인율 (%)

isSoldOut

boolean

품절 여부

reviewScore

number

리뷰 평점

reviewCount

number

리뷰 수

rank

number

목록 내 순위. 1부터 시작하며 페이지 경계를 넘어 연속됩니다

categoryIds

array

상품이 속한 카테고리 ID 경로. 상위에서 하위 순서이며 마지막 값이 가장 구체적인 카테고리입니다. 비어 있을 수 있습니다

categoryIds는 이름 없이 ID만 담깁니다. 이름이 필요하시면 카테고리 조회로 트리를 한 번 받아 두고 ID로 찾아 쓰시면 됩니다. 경로에 담기는 ID는 모두 그 트리에 존재하는 값이라 이름을 찾지 못하는 경우는 없습니다.

"categoryIds": [100, 101, 10125]

위 예시는 패션 > 여성의류 > 원피스 처럼 상위에서 하위로 이어지는 경로입니다.

경로 길이는 상품마다 다르고, 빈 배열로 내려오는 상품도 있습니다. 상품이 속한 카테고리가 공개 트리에서 대분류부터 이어서 확인되지 않으면(트리에 아직 반영되지 않았거나, 트리가 공개하는 5단계보다 깊은 곳에만 속한 경우) 확인되는 데까지만 담고 그 아래는 생략합니다.

응답

의미

처리 방법

[100, 101, 10125]

3단계까지 확인된 상품

첫 번째는 가장 큰 분류, 마지막은 가장 구체적인 분류로 쓰시면 됩니다

[100]

대분류까지만 확인된 상품

하위 분류 없이 대분류로만 분류해 주세요

[]

공개 트리에서 확인되는 카테고리가 없는 상품

카테고리 미분류로 처리해 주세요 (분류 목록에서 제외하거나 '기타'로 묶으시면 됩니다)

categoryIds[0]이나 마지막 값에 바로 접근하면 빈 배열에서 오류가 납니다. 값을 꺼내기 전에 배열이 비어 있는지 먼저 확인해 주세요.

공통 주의사항

게시글 링크는 반드시 발급 API로 만들어 주세요

조회 API 응답의 productUrl은 추적이 되지 않는 일반 상품 링크입니다. 이 링크로 발생한 구매는 수익으로 집계되지 않습니다.

게시글에 넣으실 링크는 쉐어링크 발급으로 발급받은 shortUrl 또는 originUrl을 사용해 주세요.

상품 이미지는 가공하지 말고 원본 그대로 사용해 주세요

썸네일과 상세 페이지 이미지는 쉐어링크 상품을 소개하는 목적으로 표시하실 수 있지만, 가공은 할 수 없습니다. 크롭·합성·편집·번역 없이 원본 그대로 노출해 주세요. 가급적 썸네일 이미지 사용을 권장드립니다.

셀러가 요청하면 해당 이미지를 바로 내려야 할 수 있습니다. 상품 단위로 이미지 노출을 중단할 수 있게 구현해 주세요.
상세 페이지에 이미지 사용 금지가 표시된 상품은 썸네일을 포함해 이미지를 사용하지 마세요.

자세한 기준은 크리에이터 가이드 운영 정책의 상품 이미지 사용을 확인해 주세요.

배송비는 `displayPrice`에 이미 포함돼 있습니다

displayPrice는 이 상품 하나를 살 때 실제로 결제하게 되는 금액이며, 배송비가 이미 더해진 값입니다. 배송비를 따로 더해서 노출하시면 실제 결제 금액보다 비싸게 표시됩니다.

무료배송이면 더해지는 금액이 없고, 조건부 무료배송이면 해당 상품 하나 기준으로 조건 충족 여부를 계산한 결과가 반영됩니다. 여러 상품을 함께 담아 주문할 때의 배송비는 토스쇼핑 주문 단계에서 다시 계산되므로, 응답 값과 다를 수 있습니다.

개인화 정보는 제공되지 않습니다

서버 간 호출이라 특정 사용자 정보가 없습니다. 쿠폰·배송지·적립 등 사용자별로 달라지는 정보는 응답에 포함되지 않으며, 상품 자체 정보만 제공됩니다.

가격·품절 상태는 실시간으로 변합니다

응답을 저장해서 사용하시는 경우, 게시 시점의 가격·품절 상태가 실제와 달라질 수 있습니다. 상품 상세 조회로 최신 상태를 확인하실 수 있습니다.

성인 상품은 제공되지 않습니다

Open API 조회 기능은 성인 상품을 제공하지 않습니다.

버전·변경 정책

외부 경로는 /openapi 하위로 제공합니다.

필드 추가처럼 하위호환을 지키는 변경은 기존 경로에 그대로 반영됩니다. 그래서 모르는 필드를 무시하도록 구현해 주시길 권장드립니다.
하위호환을 깨는 변경은 별도 경로로 제공합니다 (예: /openapi/v2). 쓰시던 경로가 갑자기 달라지지 않습니다.
기존 기능을 걷어내는 경우 사전에 공지드립니다.

이용 조건

제공되는 데이터는 제휴 목적 범위 내에서만 사용해 주세요.
가격 크롤링, 무단 재판매, 비정상적 대량 수집 등은 이용이 제한되거나 차단될 수 있습니다.

자세한 약관과 정산 조건은 토스쇼핑 고객센터로 문의해 주세요.

Previous빠른 시작

Next용어

Last updated 5 days ago

Was this helpful?

공통 응답 형식

HTTP 상태와 본문은 이렇게 구분해요

오류 코드

재시도

호출 제한 (Rate Limit)

일 사용 상한

세는 방식

자주 묻는 호출 한도 질문

한도 상향이 필요하면 어떻게 하나요?

커서 페이징

상품 카드 공통 필드

공통 주의사항

게시글 링크는 반드시 발급 API로 만들어 주세요

상품 이미지는 가공하지 말고 원본 그대로 사용해 주세요

배송비는 displayPrice에 이미 포함돼 있습니다

개인화 정보는 제공되지 않습니다

가격·품절 상태는 실시간으로 변합니다

성인 상품은 제공되지 않습니다

버전·변경 정책

이용 조건

배송비는 `displayPrice`에 이미 포함돼 있습니다