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

셀러

셀러 페널티 요약 조회

get

셀러의 페널티 현황을 요약하여 조회합니다.

응답 필드

  • score: 현재 누적된 페널티 점수입니다.

  • count: 페널티가 부과된 건수입니다.

  • isPenalized: 현재 페널티가 적용 중인지 여부입니다.

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/merchants/penalty/summary
GET /api/v3/shopping-fep/merchants/penalty/summary HTTP/1.1
Host: shopping-fep.toss.im
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
200

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

{
  "resultType": "SUCCESS",
  "error": {
    "errorCode": "REQUEST_FAILED",
    "reason": "text"
  },
  "success": {
    "score": 3,
    "count": 2,
    "isPenalized": false
  }
}

셀러 페널티 부과 목록 조회

get

셀러에게 부과된 페널티 목록을 커서 기반으로 조회합니다.

페이징

  • 커서 기반 페이징을 사용합니다.

  • cursorId를 지정하지 않으면 최신 데이터부터 조회합니다.

  • 응답의 nextCursorId를 다음 요청의 cursorId로 전달하면 다음 페이지를 조회할 수 있습니다.

  • isLast가 true이면 더 이상 조회할 데이터가 없습니다.

  • size는 최대 100까지 지정할 수 있습니다. (기본값: 20)

응답 필드

  • content: 페널티 부과 상세 목록입니다.

  • nextCursorId: 다음 페이지 조회를 위한 커서 ID입니다.

  • isLast: 마지막 페이지 여부입니다.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Query parameters
cursorIdinteger · int64Optional

커서 ID (지정하지 않으면 최신 데이터부터 조회)

sizeinteger · int32Optional

조회 건수

Default: 20Example: 20
partnerNamestringOptional

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

Example: 토스쇼핑
Responses
200

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

application/json
resultTypestring · enumOptional

응답 결과 타입

Possible values:
get/api/v3/shopping-fep/merchants/penalty/impositions
GET /api/v3/shopping-fep/merchants/penalty/impositions 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": {
    "content": [
      {
        "id": 1,
        "productItemId": 100,
        "productItemName": "블랙 M",
        "productItemThumbnailUrl": "text",
        "productId": 50,
        "productName": "반팔 티셔츠",
        "orderProductId": 200,
        "reason": "배송 지연",
        "description": "text",
        "score": 3,
        "status": "PENALIZED",
        "expiredTs": "2026-01-01T00:00:00.000Z",
        "releasedTs": "2026-01-01T00:00:00.000Z",
        "regTs": "2026-01-01T00:00:00.000Z",
        "appeals": [
          {
            "id": 1,
            "description": "text",
            "status": "REQUESTED",
            "inspectedBy": "text",
            "inspectionTs": "2026-01-01T00:00:00.000Z",
            "rejectReason": "text",
            "regTs": "2026-01-01T00:00:00.000Z",
            "attachments": [
              {
                "id": 1,
                "originFileName": "증빙자료.pdf",
                "contentType": "image/png",
                "fileSize": 37257
              }
            ]
          }
        ]
      }
    ],
    "nextCursorId": 10,
    "isLast": false
  }
}

셀러 페널티 소명 자료 제출

post

페널티에 대한 소명 자료를 제출합니다.

요청 방식

  • multipart/form-data 형식으로 요청합니다.

  • penaltyImpositionId: 소명할 페널티 부과 ID입니다.

  • description: 소명 내용입니다.

  • attachments: 첨부파일 목록입니다. (선택)

첨부파일 제약 조건

  • 최대 3개까지 첨부할 수 있습니다.

  • 허용 확장자: png, jpg, jpeg, pdf, hwp

  • 개별 파일 최대 크기: 10MB

  • 요청 전체 최대 크기: 10MB

응답 필드

  • appealId: 생성된 소명 ID입니다.

  • status: 소명 상태입니다.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Query parameters
penaltyImpositionIdinteger · int64Required

페널티 부과 ID

Example: 1
descriptionstringRequired

소명 내용

partnerNamestringOptional

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

Example: 토스쇼핑
Body
attachmentsstring · binary[]Optional
Responses
200

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

application/json
resultTypestring · enumOptional

응답 결과 타입

Possible values:
post/api/v3/shopping-fep/merchants/penalty/appeals
POST /api/v3/shopping-fep/merchants/penalty/appeals?penaltyImpositionId=1&description=text HTTP/1.1
Host: shopping-fep.toss.im
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 26

{
  "attachments": [
    "binary"
  ]
}
200

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

{
  "resultType": "SUCCESS",
  "error": {
    "errorCode": "INVALID_REQUEST",
    "reason": "text"
  },
  "success": {
    "appealId": 1,
    "status": "REQUESTED"
  }
}

셀러 휴무일 목록 조회

get

셀러의 휴무일 목록을 기간별로 조회합니다.

조회 조건

  • startDate와 endDate를 기준으로 해당 기간에 포함된 휴무일을 반환합니다.

  • 날짜 형식은 yyyy-MM-dd입니다.

활용 예시

  • 배송 예정일 계산 시 셀러 휴무일을 제외하여 정확한 배송일을 안내할 수 있습니다.

  • 셀러 운영 캘린더에 휴무일을 표시할 수 있습니다.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Query parameters
startDatestring · dateRequired

조회 시작일 (yyyy-MM-dd)

Example: 2026-01-01
endDatestring · dateRequired

조회 종료일 (yyyy-MM-dd)

Example: 2026-12-31
partnerNamestringOptional

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

Example: 토스쇼핑
Responses
200

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

application/json
resultTypestring · enumOptional

응답 결과 타입

Possible values:
get/api/v3/shopping-fep/merchants/holidays
GET /api/v3/shopping-fep/merchants/holidays?startDate=2026-01-01&endDate=2026-01-01 HTTP/1.1
Host: shopping-fep.toss.im
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
200

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

{
  "resultType": "SUCCESS",
  "error": {
    "errorCode": "REQUEST_FAILED",
    "reason": "text"
  },
  "success": {
    "items": [
      {
        "id": 1,
        "name": "설날 연휴",
        "holiday": "2026-01-29",
        "regTs": "2026-01-01T00:00:00.000Z",
        "updTs": "2026-01-01T00:00:00.000Z"
      }
    ]
  }
}

셀러 휴무일 등록

post

셀러의 휴무일을 등록합니다. (upsert 방식)

등록 방식

  • startDate부터 endDate까지의 기간에 해당하는 휴무일을 일괄 등록합니다.

  • 동일한 날짜에 이미 휴무일이 등록되어 있는 경우 휴무명이 갱신됩니다. (upsert)

  • 날짜 형식은 yyyy-MM-dd입니다.

활용 예시

  • 설날, 추석 등 연휴 기간의 휴무일을 한 번에 등록할 수 있습니다.

  • 특정 날짜의 임시 휴무를 등록할 수 있습니다.

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

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

Example: 토스쇼핑
Body

셀러 휴무일 등록 요청

namestring · max: 100Required

휴무명

Example: 설날 연휴
startDatestring · dateRequired

시작일 (yyyy-MM-dd)

Example: 2026-01-28
endDatestring · dateRequired

종료일 (yyyy-MM-dd)

Example: 2026-01-30
Responses
200

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

application/json
resultTypestring · enumOptional

응답 결과 타입

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

{
  "name": "설날 연휴",
  "startDate": "2026-01-28",
  "endDate": "2026-01-30"
}
200

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

{
  "resultType": "SUCCESS",
  "error": {
    "errorCode": "INVALID_REQUEST",
    "reason": "text"
  },
  "success": {
    "items": [
      {
        "id": 1,
        "name": "설날 연휴",
        "holiday": "2026-01-29",
        "regTs": "2026-01-01T00:00:00.000Z",
        "updTs": "2026-01-01T00:00:00.000Z"
      }
    ]
  }
}

셀러 휴무일 수정

put

등록된 셀러 휴무일의 휴무명을 수정합니다.

수정 대상

  • 휴무일 ID(holidayId)에 해당하는 휴무일의 휴무명을 변경합니다.

  • 휴무명은 최대 100자까지 입력할 수 있습니다.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
holidayIdinteger · int64Required

휴무일 ID

Example: 1
Query parameters
partnerNamestringOptional

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

Example: 토스쇼핑
Body

셀러 휴무일 수정 요청

namestring · max: 100Required

휴무명

Example: 설날 연휴
Responses
200

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

application/json
resultTypestring · enumOptional

응답 결과 타입

Possible values:
put/api/v3/shopping-fep/merchants/holidays/{holidayId}
PUT /api/v3/shopping-fep/merchants/holidays/{holidayId} HTTP/1.1
Host: shopping-fep.toss.im
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 24

{
  "name": "설날 연휴"
}
200

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

{
  "resultType": "SUCCESS",
  "error": {
    "errorCode": "REQUEST_FAILED",
    "reason": "text"
  },
  "success": {
    "id": 1,
    "name": "설날 연휴",
    "holiday": "2026-01-29",
    "regTs": "2026-01-01T00:00:00.000Z",
    "updTs": "2026-01-01T00:00:00.000Z"
  }
}

셀러 휴무일 삭제

delete

등록된 셀러 휴무일을 삭제합니다.

삭제 대상

  • 휴무일 ID(holidayId)에 해당하는 휴무일을 삭제합니다.

  • 삭제된 휴무일은 복구할 수 없습니다.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
holidayIdinteger · int64Required

휴무일 ID

Example: 1
Query parameters
partnerNamestringOptional

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

Example: 토스쇼핑
Responses
200

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

application/json
resultTypestring · enumOptional

응답 결과 타입

Possible values:
successobjectOptional

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

delete/api/v3/shopping-fep/merchants/holidays/{holidayId}
DELETE /api/v3/shopping-fep/merchants/holidays/{holidayId} HTTP/1.1
Host: shopping-fep.toss.im
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
200

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

{
  "resultType": "SUCCESS",
  "error": {
    "errorCode": "REQUEST_FAILED",
    "reason": "text"
  },
  "success": {}
}
이전상품
다음주문

마지막 업데이트

도움이 되었나요?