배송

주문 상품 배송정보 변경

put

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

변경 가능 조건

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

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

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

변경 불가 조건

• 취소 요청이 들어온 주문 상품의 경우 DELIVERING(배송중) 상태로 변경할 수 없습니다

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

송장번호 형식

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

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

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

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

orderProductIdinteger · int64Required

주문 상품 ID

Example: 12345

deliveryCompanystring · enumRequired

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

Example: CJ대한통운Possible values:

trackingNumberstringRequired

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

• 직접전달인 경우 검증 생략

Example: 123456789012

partnerNamestringOptional

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

Example: 토스쇼핑

Responses

200

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

application/json

put

/api/v3/shopping-fep/orders/products/delivery

HTTPcURLJavaScriptPython

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

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

partnerNamestringOptional

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

Example: 토스쇼핑

Responses

200

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

application/json

get

/api/v3/shopping-fep/orders/delivery-companies

HTTPcURLJavaScriptPython

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

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

배송 그룹 등록 요청

namestringRequired

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

Example: 일반 배송

isMainbooleanRequired

대표 배송 그룹 여부

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

Example: true

partnerNamestringOptional

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

Example: 토스쇼핑

Responses

200

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

application/json

post

/api/v3/shopping-fep/merchants/group-delivery/delivery-location

HTTPcURLJavaScriptPython

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

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

배송 그룹 수정 요청

idinteger · int64Required

배송 그룹 ID

Example: 67890

namestringRequired

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

Example: 일반 배송

isMainbooleanRequired

대표 배송 그룹 여부

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

Example: true

partnerNamestringOptional

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

Example: 토스쇼핑

Responses

200

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

application/json

put

/api/v3/shopping-fep/merchants/group-delivery/delivery-location

HTTPcURLJavaScriptPython

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

bearerAuth

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

get

/api/v3/shopping-fep/merchants/group-delivery/delivery-location/v2

HTTPcURLJavaScriptPython

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

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

교환 반품지 등록 요청

zipCodestringRequired

우편번호

Example: 06236

addressstringRequired

주소 (필수)

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

detailAddressstringRequired

상세 주소

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

isMainbooleanRequired

대표 교환 반품지 여부

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

Example: true

partnerNamestringOptional

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

Example: 토스쇼핑

Responses

200

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

application/json

post

/api/v3/shopping-fep/merchants/group-delivery/exchange-refund-location

HTTPcURLJavaScriptPython

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

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

교환 반품지 수정 요청

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

put

/api/v3/shopping-fep/merchants/group-delivery/exchange-refund-location

HTTPcURLJavaScriptPython

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

bearerAuth

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

get

/api/v3/shopping-fep/merchants/group-delivery/exchange-refund-location/v2

HTTPcURLJavaScriptPython

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