클레임 (취소/교환/반품)

클레임(취소, 반품, 교환) 목록 조회

get

가맹점의 클레임(취소, 반품, 교환) 목록을 조회합니다.

사용처

• 고객이 요청한 취소/반품/교환 클레임을 조회하고 관리할 수 있습니다

• 클레임 유형, 상태, 기간 등으로 필터링하여 조회할 수 있습니다

페이지네이션

• size: 페이지 크기 (기본값: 20, 최대: 100)

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

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

조회 기간

• fromRequestDate, toRequestDate: 클레임 요청일 기준 조회 (status가 REQUESTED일 때 사용)

• 기본값: toRequestDate는 오늘, fromRequestDate는 toRequestDate의 7일 전

• 조회 기간은 최대 7일까지 가능합니다

클레임 유형

• CANCEL: 취소 (결제 완료 상태에서 취소 요청)

• EXCHANGE: 교환 (상품 교환 요청)

• RETURN: 반품 (상품 반품 요청)

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

typestring · enumRequired

조회용 클레임 유형

Example: CANCELPossible values:

statusstring · enumRequired

조회용 클레임 상태

Example: REQUESTEDPossible values:

fromRequestDatestring · dateOptional

조회 시작일자 yyyy-MM-dd 형태 (기본값: 오늘)

Example: 2025-10-06

toRequestDatestring · dateOptional

조회 종료일자 yyyy-MM-dd 형태 (기본값: fromRequestDate의 7일 전)

Example: 2025-10-13

fromRequestRevokedDatestring · dateOptional

toRequestRevokedDatestring · dateOptional

orderIdinteger · int64Optional

주문 번호

Example: 123456

nextTokenstringOptional

다음 페이지를 위한 커서 정보 (직전 호출에서 받은 nextToken을 그대로 넘겨 호출)

Example: eyJpZCI6MTAwMX0=

sizeinteger · int32Optional

페이지 사이즈 (기본값: 20)

Default: 20Example: 20

Responses

200

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

application/json

get

/api/v3/shopping-fep/claims

HTTPcURLJavaScriptPython

GET /api/v3/shopping-fep/claims?type=CANCEL&status=REQUESTED 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": 12345,
        "requestedDt": "2025-12-11T08:38:48.118Z",
        "status": "REQUESTED",
        "requestReason": "단순 변심",
        "requestDetailReason": "사이즈가 맞지 않습니다",
        "requestImages": [
          "https://picsum.photos/600",
          "https://picsum.photos/600"
        ],
        "requestDeliveryPenaltyCharger": "MERCHANT",
        "refundOneWayDeliveryFee": 3000,
        "roundTripDeliveryFee": 6000,
        "returnAddress": "서울특별시 강남구 테헤란로 131",
        "order": {
          "id": 123456,
          "orderProductId": 654321,
          "ordererName": "홍*동",
          "ordererPhoneNumber": "010-****-5678",
          "receiverName": "김*수",
          "receiverPhoneNumber": "010-****-1234",
          "deliveryCompany": "CJ대한통운",
          "shippingTrackingNumber": "123456789012",
          "address": "서울특별시 강남구 테헤란로 131",
          "price": 50000,
          "createdDt": "2025-12-11T08:38:48.118Z"
        },
        "product": {
          "id": 111222,
          "name": "리클라이너",
          "optionName": "색상: 빨강, 사이즈: L",
          "quantity": 2
        },
        "claimDeliveryPaymentAmount": 3000
      }
    ],
    "nextToken": "eyJpZCI6MTAwMX0="
  }
}

판매자 주문 취소

post

결제 완료 상태의 주문 상품에 대해 판매자가 취소 처리합니다.

판매자 취소 처리 가능한 주문 상품 상태

• CANCELED_PAYMENT: 결제취소

• EXCHANGE: 결제완료

• RETURN: 상품준비중

• DELAY_SHIPPING: 발송지연

• DELIVERING: 배송중

• DELIVERED: 배송완료

• CONFIRMED_ORDER: 구매확정

• REQUESTED_EXCHANGE: 교환접수

• ONGOING_EXCHANGE: 교환처리중

• COMPLETED_EXCHANGE: 교환완료

• REQUESTED_RETURN: 반품접수

• ONGOING_RETURN: 반품처리중

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

orderProductIdinteger · int64Required

주문 상품 ID

Example: 12345

Body

application/json

판매자 주문 취소 요청

deliveryPenaltyChargerstring · enumRequired

배송비 부과 책임자

Example: MERCHANTPossible values:

reasonstringOptional

주문 취소 사유 (100자 이내)

Example: 재고 부족

detailReasonstringOptional

주문 취소 상세 사유 (250자 이내)

Example: 상품 재고가 일시적으로 부족하여 주문을 취소합니다.

Responses

200

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

application/json

post

/api/v3/shopping-fep/order-products/{orderProductId}/seller-cancel

HTTPcURLJavaScriptPython

POST /api/v3/shopping-fep/order-products/{orderProductId}/seller-cancel HTTP/1.1
Host: shopping-fep.toss.im
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 152

{
  "deliveryPenaltyCharger": "MERCHANT",
  "reason": "재고 부족",
  "detailReason": "상품 재고가 일시적으로 부족하여 주문을 취소합니다."
}

200

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

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

취소 요청 승인

post

고객의 취소 요청을 승인하여 환불 처리를 진행합니다.

처리 흐름

1. 고객이 취소 요청 (status: REQUESTED)

2. 판매자가 취소 요청 승인 (이 API 호출)

3. 환불 처리 완료

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

claimIdinteger · int64Required

클레임 ID

Example: 12345

Responses

200

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

application/json

post

/api/v3/shopping-fep/claims/{claimId}/cancel/approval

HTTPcURLJavaScriptPython

POST /api/v3/shopping-fep/claims/{claimId}/cancel/approval 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": {}
}

취소 요청 거절

post

고객의 취소 요청을 거절하고 배송을 진행합니다.

처리 흐름

1. 고객이 취소 요청 (status: REQUESTED)

2. 판매자가 취소 요청 거절 (이 API 호출)

3. 배송 회사와 송장번호를 등록하여 배송 진행

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

claimIdinteger · int64Required

클레임 ID

Example: 12345

Body

application/json

취소 요청 거절 요청

deliveryCompanystring · enumRequired

배송 회사

Example: CJ대한통운Possible values:

shippingTrackingNumberstringOptional

송장번호

Example: 1234567890

Responses

200

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

application/json

post

/api/v3/shopping-fep/claims/{claimId}/cancel/rejection

HTTPcURLJavaScriptPython

POST /api/v3/shopping-fep/claims/{claimId}/cancel/rejection HTTP/1.1
Host: shopping-fep.toss.im
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 74

{
  "deliveryCompany": "CJ대한통운",
  "shippingTrackingNumber": "1234567890"
}

200

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

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

교환 요청 승인

post

고객의 교환 요청을 승인하여 상품 수거를 시작합니다.

처리 흐름

1. 고객이 교환 요청 (status: REQUESTED)

2. 판매자가 교환 요청 승인 (이 API 호출)

3. 수거 진행 (status: 수거중)

4. 수거 완료 후 상품 입고 확인

5. 교환 재배송

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

claimIdinteger · int64Required

클레임 ID

Example: 12345

Responses

200

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

application/json

post

/api/v3/shopping-fep/claims/{claimId}/exchange/approval

HTTPcURLJavaScriptPython

POST /api/v3/shopping-fep/claims/{claimId}/exchange/approval 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": {}
}

교환 요청 거절

post

고객의 교환 요청을 거절합니다.

처리 흐름

1. 고객이 교환 요청 (status: REQUESTED)

2. 판매자가 교환 요청 거절 (이 API 호출)

3. 교환 요청이 반려되고 주문은 정상 진행

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

claimIdinteger · int64Required

클레임 ID

Example: 12345

Body

application/json

교환 요청 거절 요청

requestRejectReasonstringRequired

교환 요청 거절 사유

Example: 상품 재고 부족으로 교환이 불가능합니다

Responses

200

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

application/json

post

/api/v3/shopping-fep/claims/{claimId}/exchange/rejection

HTTPcURLJavaScriptPython

POST /api/v3/shopping-fep/claims/{claimId}/exchange/rejection HTTP/1.1
Host: shopping-fep.toss.im
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 81

{
  "requestRejectReason": "상품 재고 부족으로 교환이 불가능합니다"
}

200

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

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

교환 수거 완료

post

교환 상품의 수거를 완료하고 상품 입고를 확인합니다.

처리 흐름

1. 교환 요청 승인 후 수거 진행

2. 상품 수거 완료 (이 API 호출)

3. 상품 입고 확인 (status: 수거완료)

4. 교환 재배송 준비

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

claimIdinteger · int64Required

클레임 ID

Example: 12345

Responses

200

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

application/json

post

/api/v3/shopping-fep/claims/{claimId}/exchange/collection

HTTPcURLJavaScriptPython

POST /api/v3/shopping-fep/claims/{claimId}/exchange/collection 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": {}
}

교환 완료

post

교환 재배송이 완료되어 교환 프로세스를 종료합니다.

처리 흐름

1. 교환 재배송 진행

2. 고객이 상품 수령

3. 교환 완료 처리 (이 API 호출)

4. 교환 프로세스 종료

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

claimIdinteger · int64Required

클레임 ID

Example: 12345

Responses

200

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

application/json

post

/api/v3/shopping-fep/claims/{claimId}/exchange/completion

HTTPcURLJavaScriptPython

POST /api/v3/shopping-fep/claims/{claimId}/exchange/completion 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": {}
}

교환 반려

post

수거된 상품의 상태가 불량하여 교환을 반려합니다.

처리 흐름

1. 교환 요청 승인 후 수거 진행

2. 수거된 상품 확인

3. 상품 상태 불량으로 교환 반려 (이 API 호출)

4. 교환 거절 처리 완료

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

claimIdinteger · int64Required

클레임 ID

Example: 12345

Body

application/json

교환 반려 요청

rejectReasonstringRequired

교환 반려 사유

Example: 상품 훼손이 심하여 교환이 불가능합니다

Responses

200

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

application/json

post

/api/v3/shopping-fep/claims/{claimId}/exchange/collection-rejection

HTTPcURLJavaScriptPython

POST /api/v3/shopping-fep/claims/{claimId}/exchange/collection-rejection HTTP/1.1
Host: shopping-fep.toss.im
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 74

{
  "rejectReason": "상품 훼손이 심하여 교환이 불가능합니다"
}

200

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

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

교환 재배송

post

수거 완료된 교환 상품을 재배송합니다.

처리 흐름

1. 교환 수거 완료

2. 상품 입고 확인

3. 교환 재배송 시작 (이 API 호출)

4. 배송 회사와 송장번호 등록

5. 재배송 진행 (status: 재배송중)

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

claimIdinteger · int64Required

클레임 ID

Example: 12345

Body

application/json

교환 재배송 요청

deliveryCompanystring · enumRequired

배송 회사

Example: CJ대한통운Possible values:

shippingTrackingNumberstringRequired

송장번호

Example: 1234567890

Responses

200

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

application/json

post

/api/v3/shopping-fep/claims/{claimId}/exchange/delivery

HTTPcURLJavaScriptPython

POST /api/v3/shopping-fep/claims/{claimId}/exchange/delivery HTTP/1.1
Host: shopping-fep.toss.im
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 74

{
  "deliveryCompany": "CJ대한통운",
  "shippingTrackingNumber": "1234567890"
}

200

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

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

반품 요청 승인

post

고객의 반품 요청을 승인하여 상품 수거를 시작합니다.

처리 흐름

1. 고객이 반품 요청 (status: REQUESTED)

2. 판매자가 반품 요청 승인 (이 API 호출)

3. 수거 진행 (status: 수거중)

4. 수거 완료 후 상품 입고 확인

5. 반품 완료 및 환불 처리

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

claimIdinteger · int64Required

클레임 ID

Example: 12345

Responses

200

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

application/json

post

/api/v3/shopping-fep/claims/{claimId}/return/approval

HTTPcURLJavaScriptPython

POST /api/v3/shopping-fep/claims/{claimId}/return/approval 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": {}
}

반품 요청 거절

post

고객의 반품 요청을 거절합니다.

처리 흐름

1. 고객이 반품 요청 (status: REQUESTED)

2. 판매자가 반품 요청 거절 (이 API 호출)

3. 반품 요청이 반려되고 주문은 정상 진행

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

claimIdinteger · int64Required

클레임 ID

Example: 12345

Body

application/json

반품 요청 거절 요청

requestRejectReasonstringRequired

반품 요청 거절 사유

Example: 고객 단순 변심으로 반품이 불가능합니다

Responses

200

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

application/json

post

/api/v3/shopping-fep/claims/{claimId}/return/rejection

HTTPcURLJavaScriptPython

POST /api/v3/shopping-fep/claims/{claimId}/return/rejection HTTP/1.1
Host: shopping-fep.toss.im
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 81

{
  "requestRejectReason": "고객 단순 변심으로 반품이 불가능합니다"
}

200

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

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

반품 수거 완료

post

반품 상품의 수거를 완료하고 상품 입고를 확인합니다.

처리 흐름

1. 반품 요청 승인 후 수거 진행

2. 상품 수거 완료 (이 API 호출)

3. 상품 입고 확인 (status: 수거완료)

4. 반품 완료 및 환불 준비

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

claimIdinteger · int64Required

클레임 ID

Example: 12345

Responses

200

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

application/json

post

/api/v3/shopping-fep/claims/{claimId}/return/collection

HTTPcURLJavaScriptPython

POST /api/v3/shopping-fep/claims/{claimId}/return/collection 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": {}
}

반품 반려

post

수거된 상품의 상태가 불량하여 반품을 반려합니다.

처리 흐름

1. 반품 요청 승인 후 수거 진행

2. 수거된 상품 확인

3. 상품 상태 불량으로 반품 반려 (이 API 호출)

4. 반품 거절 처리 완료

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

claimIdinteger · int64Required

클레임 ID

Example: 12345

Body

application/json

반품 반려 요청

rejectReasonstringRequired

반품 반려 사유

Example: 상품 훼손이 심하여 반품이 불가능합니다

Responses

200

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

application/json

post

/api/v3/shopping-fep/claims/{claimId}/return/collection-rejection

HTTPcURLJavaScriptPython

POST /api/v3/shopping-fep/claims/{claimId}/return/collection-rejection HTTP/1.1
Host: shopping-fep.toss.im
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 74

{
  "rejectReason": "상품 훼손이 심하여 반품이 불가능합니다"
}

200

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

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

반품 완료

post

반품 수거가 완료되어 환불 처리를 진행하고 반품 프로세스를 종료합니다.

처리 흐름

1. 반품 수거 완료

2. 상품 입고 확인

3. 반품 완료 처리 (이 API 호출)

4. 환불 처리 및 반품 프로세스 종료

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

claimIdinteger · int64Required

클레임 ID

Example: 12345

Responses

200

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

application/json

post

/api/v3/shopping-fep/claims/{claimId}/return/completion

HTTPcURLJavaScriptPython

POST /api/v3/shopping-fep/claims/{claimId}/return/completion 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": {}
}

질문은 여기에 남겨주세요. 토스쇼핑 담당자가 확인하고 이메일로 답변드려요.