토스쇼핑 API 개발/연동에 대한 질문이 있다면 남겨주세요. 토스쇼핑 담당자와 질의응답할 수 있어요.
토스쇼핑 개발자센터
Ctrlk
API 개발/연동 문의하기
For the complete documentation index, see llms.txt. This page is also available as Markdown.

배송

주문 상품 배송정보 변경

put

주문 상품의 배송 회사와 송장번호를 변경합니다.

변경 가능 조건

주문 상품 상태가 다음 중 하나인 경우에만 배송정보를 변경할 수 있습니다

  • PREPARING_PRODUCT (상품준비중): 배송정보 등록 시 자동으로 DELIVERING (배송중) 상태로 변경됩니다

  • DELIVERING (배송중): 배송정보만 수정됩니다

변경 불가 조건

  • 진행 중인 취소 요청이 있는 주문 상품의 경우 DELIVERING(배송중) 상태로 변경할 수 없습니다 (취소 요청 미처리 상태로 배송이 진행되어 상태 불일치가 발생하는 것을 방지하기 위함)

  • 위 조건에 해당하지 않으면 API 요청이 실패합니다

  • 송장 등록/배송상태 업데이트 전 반드시 취소 요청 유무를 먼저 확인 부탁드립니다

송장번호 형식

  • 기본적으로 숫자로 된 문자열만 입력 가능합니다 (정규식: \\d+)

  • 일부 택배사(예: 팀프레시)의 경우에만 영문 입력이 가능합니다

  • 하이픈(-)은 입력하셔도 자동으로 제거되어 등록됩니다

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Body
orderProductIdinteger · int64Required

주문 상품 ID

Example: 12345
deliveryCompanystring · enumRequired

배송 회사 코드 (택배사 정보 조회 API에서 확인 가능)

Example: CJ대한통운Possible values:
trackingNumberstringRequired

송장번호. 하이픈(-)은 자동 제거됩니다

  • 직접전달인 경우 검증 생략
Example: 123456789012
partnerNamestringOptional

연동 프로그램명 또는 자사 서비스명

Example: 토스쇼핑
Responses
200

모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)

application/json
resultTypestring · enumOptional

응답 결과 타입

Possible values:
successobjectOptional

성공시 제공, 별도 내용이 없습니다. {}으로 반환

put/api/v3/shopping-fep/orders/products/delivery
PUT /api/v3/shopping-fep/orders/products/delivery HTTP/1.1
Host: shopping-fep.toss.im
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 120

{
  "orderProductId": 12345,
  "deliveryCompany": "CJ대한통운",
  "trackingNumber": "123456789012",
  "partnerName": "토스쇼핑"
}
200

모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)

{
  "resultType": "SUCCESS",
  "error": {
    "errorCode": "INVALID_REQUEST",
    "reason": "text"
  },
  "success": {}
}

택배사 정보 조회

get

배송정보 등록 시 사용 가능한 택배사 목록을 조회합니다.

사용처

  • 주문 상품 배송정보 변경 API의 deliveryCompany 파라미터에 사용할 택배사 코드를 확인할 수 있습니다

지원 택배사

CJ대한통운, 우체국택배, 한진택배, 로젠택배, 대신택배, 롯데택배, GS25편의점택배, CU편의점택배 등 대다수의 택배사가 지원됩니다.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Query parameters
partnerNamestringOptional

연동 프로그램명 또는 자사 서비스명

Example: 토스쇼핑
Responses
200

모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)

application/json
resultTypestring · enumOptional

응답 결과 타입

Possible values:
get/api/v3/shopping-fep/orders/delivery-companies
GET /api/v3/shopping-fep/orders/delivery-companies HTTP/1.1
Host: shopping-fep.toss.im
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
200

모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)

{
  "resultType": "SUCCESS",
  "error": {
    "errorCode": "COMMON_ERROR",
    "reason": "text"
  },
  "success": {
    "deliveryCompanies": [
      "CJ대한통운",
      "우체국택배",
      "한진택배",
      "로젠택배",
      "대신택배",
      "롯데택배"
    ]
  }
}

배송 위치 (배송비 묶음 그룹) 등록

post

가맹점의 배송 그룹을 등록합니다.

사용처

  • 상품 등록 시 배송비 정책을 묶어서 관리하는 배송 그룹을 등록합니다

  • 셀러 어드민 대신 API를 통해 배송 그룹을 등록할 수 있습니다

주의사항

  • 배송 그룹 이름은 필수이며 빈 값일 수 없습니다

  • 대표 배송 그룹(isMain = true)은 하나만 존재할 수 있습니다

  • 등록 후 반환되는 id는 상품 등록 시 deliveryLocationId로 사용됩니다

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Body

배송 그룹 등록 요청

namestringRequired

배송 그룹 이름 (필수, 최대 100자)

Example: 일반 배송
isMainbooleanRequired

대표 배송 그룹 여부

true로 설정 시 기존 대표 배송 그룹이 자동으로 해제됩니다

Example: true
partnerNamestringOptional

연동 프로그램명 또는 자사 서비스명

Example: 토스쇼핑
Responses
200

모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)

application/json
resultTypestring · enumOptional

응답 결과 타입

Possible values:
post/api/v3/shopping-fep/merchants/group-delivery/delivery-location
POST /api/v3/shopping-fep/merchants/group-delivery/delivery-location HTTP/1.1
Host: shopping-fep.toss.im
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 67

{
  "name": "일반 배송",
  "isMain": true,
  "partnerName": "토스쇼핑"
}
200

모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)

{
  "resultType": "SUCCESS",
  "error": {
    "errorCode": "INVALID_REQUEST",
    "reason": "text"
  },
  "success": {
    "id": 67890
  }
}

배송 위치 (배송비 묶음 그룹) 수정

put

가맹점의 배송 그룹을 수정합니다.

사용처

  • 이미 등록된 배송 그룹의 정보를 변경할 수 있습니다

  • 배송 그룹 이름 변경이나 대표 그룹 설정 변경 시 사용됩니다

주의사항

  • id는 배송 위치 등록 API 또는 조회 API에서 반환된 값을 사용해야 합니다

  • 배송 그룹 이름은 필수이며 빈 값일 수 없습니다

  • 대표 배송 그룹(isMain = true)은 하나만 존재할 수 있습니다

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Body

배송 그룹 수정 요청

idinteger · int64Required

배송 그룹 ID

Example: 67890
namestringRequired

배송 그룹 이름 (필수, 최대 100자)

Example: 일반 배송
isMainbooleanRequired

대표 배송 그룹 여부

true로 설정 시 기존 대표 배송 그룹이 자동으로 해제됩니다

Example: true
partnerNamestringOptional

연동 프로그램명 또는 자사 서비스명

Example: 토스쇼핑
Responses
200

모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)

application/json
resultTypestring · enumOptional

응답 결과 타입

Possible values:
put/api/v3/shopping-fep/merchants/group-delivery/delivery-location
PUT /api/v3/shopping-fep/merchants/group-delivery/delivery-location HTTP/1.1
Host: shopping-fep.toss.im
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 78

{
  "id": 67890,
  "name": "일반 배송",
  "isMain": true,
  "partnerName": "토스쇼핑"
}
200

모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)

{
  "resultType": "SUCCESS",
  "error": {
    "errorCode": "INVALID_REQUEST",
    "reason": "text"
  },
  "success": {
    "id": 67890
  }
}

배송 위치 (배송비 묶음 그룹) 조회

get

가맹점이 설정한 배송 그룹 목록을 조회합니다.

사용처

  • 상품 등록 시 해당 API를 통해 배송 그룹을 조회한 후, 해당 ID를 deliveryLocationId로 지정해야 합니다

페이지네이션

  • size는 1 ~ 20 사이의 값이어야 합니다

  • 첫 페이지 조회 시 nextToken을 생략합니다

  • 다음 페이지 조회 시 응답으로 받은 nextToken 값을 그대로 전달합니다

  • 응답의 hasNext가 false이면 마지막 페이지입니다

배송 그룹 등록 방법

  • 셀러 어드민에서 등록 가능

  • API를 통해 등록 가능 (배송 위치 등록 API 사용)

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Query parameters
nextTokenstringOptional

다음 페이지를 위한 토큰 (직전 호출에서 받은 nextToken을 그대로 전달)

Example: eyJpZCI6MTAwMX0=
sizeinteger · int32Optional

페이지 사이즈 (1 ~ 20)

Default: 20Example: 20
partnerNamestringOptional

연동 프로그램명 또는 자사 서비스명

Example: 토스쇼핑
Responses
200

모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)

application/json
resultTypestring · enumOptional

응답 결과 타입

Possible values:
get/api/v3/shopping-fep/merchants/group-delivery/delivery-location/v2
GET /api/v3/shopping-fep/merchants/group-delivery/delivery-location/v2 HTTP/1.1
Host: shopping-fep.toss.im
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
200

모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)

{
  "resultType": "SUCCESS",
  "error": {
    "errorCode": "INVALID_REQUEST",
    "reason": "text"
  },
  "success": {
    "items": [
      {
        "id": 1001,
        "name": "기본 배송 그룹",
        "isMain": true
      }
    ],
    "nextToken": "eyJpZCI6MTAwMX0=",
    "hasNext": true
  }
}

교환 반품지 등록

post

가맹점의 교환 반품지를 등록합니다.

사용처

  • 고객이 교환/반품 신청 시 반송할 주소 정보로 사용됩니다

  • 셀러 어드민 대신 API를 통해 교환 반품지를 등록할 수 있습니다

주의사항

  • 대표 교환 반품지(isMain = true)는 하나만 존재할 수 있습니다

  • 등록 후 반환되는 id는 교환 반품지 수정 시 사용됩니다

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Body

교환 반품지 등록 요청

zipCodestringRequired

우편번호

Example: 06236
addressstringRequired

주소 (필수)

Example: 서울특별시 강남구 테헤란로 131
detailAddressstringRequired

상세 주소

Example: 한국지식재산센터 15층
isMainbooleanRequired

대표 교환 반품지 여부

true로 설정 시 기존 대표 교환 반품지가 자동으로 해제됩니다

Example: true
partnerNamestringOptional

연동 프로그램명 또는 자사 서비스명

Example: 토스쇼핑
Responses
200

모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)

application/json
resultTypestring · enumOptional

응답 결과 타입

Possible values:
post/api/v3/shopping-fep/merchants/group-delivery/exchange-refund-location
POST /api/v3/shopping-fep/merchants/group-delivery/exchange-refund-location HTTP/1.1
Host: shopping-fep.toss.im
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 166

{
  "zipCode": "06236",
  "address": "서울특별시 강남구 테헤란로 131",
  "detailAddress": "한국지식재산센터 15층",
  "isMain": true,
  "partnerName": "토스쇼핑"
}
200

모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)

{
  "resultType": "SUCCESS",
  "error": {
    "errorCode": "INVALID_REQUEST",
    "reason": "text"
  },
  "success": {
    "id": 12345
  }
}

교환 반품지 수정

put

가맹점의 교환 반품지를 수정합니다.

사용처

  • 이미 등록된 교환 반품지의 정보를 변경할 수 있습니다

  • 교환/반품 주소지 정보 업데이트 시 사용됩니다

주의사항

  • id는 교환 반품지 등록 API 또는 조회 API에서 반환된 값을 사용해야 합니다

  • 대표 교환 반품지(isMain = true)는 하나만 존재할 수 있습니다

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Body

교환 반품지 수정 요청

idinteger · int64Required

교환 반품지 ID

Example: 12345
zipCodestringRequired

우편번호

Example: 06236
addressstringRequired

주소 (필수)

Example: 서울특별시 강남구 테헤란로 131
detailAddressstringRequired

상세 주소

Example: 한국지식재산센터 15층
isMainbooleanRequired

대표 교환 반품지 여부

true로 설정 시 기존 대표 교환 반품지가 자동으로 해제됩니다

Example: true
partnerNamestringOptional

연동 프로그램명 또는 자사 서비스명

Example: 토스쇼핑
Responses
200

모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)

application/json
resultTypestring · enumOptional

응답 결과 타입

Possible values:
put/api/v3/shopping-fep/merchants/group-delivery/exchange-refund-location
PUT /api/v3/shopping-fep/merchants/group-delivery/exchange-refund-location HTTP/1.1
Host: shopping-fep.toss.im
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 177

{
  "id": 12345,
  "zipCode": "06236",
  "address": "서울특별시 강남구 테헤란로 131",
  "detailAddress": "한국지식재산센터 15층",
  "isMain": true,
  "partnerName": "토스쇼핑"
}
200

모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)

{
  "resultType": "SUCCESS",
  "error": {
    "errorCode": "INVALID_REQUEST",
    "reason": "text"
  },
  "success": {
    "id": 12345
  }
}

교환 반품지 조회

get

가맹점이 설정한 교환 반품지 목록을 조회합니다.

사용처

  • 상품 등록 시 교환/반품 배송지 정보로 사용됩니다

  • 고객이 교환/반품 신청 시 반송할 주소 정보를 제공합니다

페이지네이션

  • size는 1 ~ 20 사이의 값이어야 합니다

  • 첫 페이지 조회 시 nextToken을 생략합니다

  • 다음 페이지 조회 시 응답으로 받은 nextToken 값을 그대로 전달합니다

  • 응답의 hasNext가 false이면 마지막 페이지입니다

교환 반품지 등록 방법

  • 셀러 어드민에서 등록 가능

  • API를 통해 등록 가능 (교환 반품지 등록 API 사용)

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Query parameters
nextTokenstringOptional

다음 페이지를 위한 토큰 (직전 호출에서 받은 nextToken을 그대로 전달)

Example: eyJpZCI6MjAwMX0=
sizeinteger · int32Optional

페이지 사이즈 (1 ~ 20)

Default: 20Example: 20
partnerNamestringOptional

연동 프로그램명 또는 자사 서비스명

Example: 토스쇼핑
Responses
200

모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)

application/json
resultTypestring · enumOptional

응답 결과 타입

Possible values:
get/api/v3/shopping-fep/merchants/group-delivery/exchange-refund-location/v2
GET /api/v3/shopping-fep/merchants/group-delivery/exchange-refund-location/v2 HTTP/1.1
Host: shopping-fep.toss.im
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
200

모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)

{
  "resultType": "SUCCESS",
  "error": {
    "errorCode": "INVALID_REQUEST",
    "reason": "text"
  },
  "success": {
    "items": [
      {
        "id": 2001,
        "zipCode": "06234",
        "address": "서울특별시 강남구 테헤란로 123",
        "detailAddress": "토스타워 10층",
        "isMain": true
      }
    ],
    "nextToken": "eyJpZCI6MjAwMX0=",
    "hasNext": true
  }
}

API 연동 중 문의사항이나 개선 제안이 있으신가요?

토스쇼핑 API 연동에 대한 질문이나, 건의사항이 있다면 연동/개발 문의에 남겨주세요. 다른 유저의 문의를 참고하거나, 토스쇼핑 담당자와 질의를 주고 받을 수 있어요.

이전주문
다음클레임 (취소/교환/반품)

마지막 업데이트

도움이 되었나요?