> For the complete documentation index, see [llms.txt](https://shopping-docs.toss.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://shopping-docs.toss.im/connect/fulfillment-api/undefined-2.md). # 클레임(취소, 교환, 반품) ## 취소·반품·교환 처리 취소 요청 목록은 풀필먼트가 **폴링(Pull)** 으로 가져가고, 검토 결과(승인/거절)는 풀필먼트가 **Push**해요. ### 취소 처리 흐름 ```mermaid flowchart TD REQ[취소 요청 발생] --> POLL[풀필먼트: GET /cancel-requests 폴링] POLL --> REVIEW{풀필먼트 검토} REVIEW -->|승인| APPROVED[POST cancel-result APPROVED] REVIEW -->|거절| REJECTED[POST cancel-result REJECTED] APPROVED --> COMPLETED[취소완료 → 결제취소] REJECTED --> KEEP[기존 상태 유지] REJECTED -->|송장 동봉| DELIVERING[즉시 배송중 전환] COMPLETED --> CONFIRM[풀필먼트: GET /cancel-completed 확인] ``` ## 취소 요청 목록 조회 > 고객/셀러/관리자의 취소 요청 목록을 조회합니다.\ > \ > 풀필먼트 시스템에서 주기적으로 폴링하여 신규 취소 요청을 확인하는 용도입니다. ```json {"openapi":"3.0.1","info":{"title":"ShoppingFep API","version":"snapshot"},"servers":[{"url":"https://shopping-fep.toss.im"}],"security":[],"paths":{"/api/v3/shopping-fep/fulfillment/cancel-requests":{"get":{"tags":["풀필먼트 주문 관리"],"summary":"취소 요청 목록 조회","description":"고객/셀러/관리자의 취소 요청 목록을 조회합니다.\n\n풀필먼트 시스템에서 주기적으로 폴링하여 신규 취소 요청을 확인하는 용도입니다.","operationId":"getCancelRequests","parameters":[{"name":"startAt","in":"query","description":"조회 시작 일시","required":true,"schema":{"type":"string"}},{"name":"endAt","in":"query","description":"조회 종료 일시","required":true,"schema":{"type":"string"}},{"name":"cursor","in":"query","description":"이전 페이지의 커서 토큰 값","required":false,"schema":{"maxLength":1024,"minLength":0,"type":"string"}},{"name":"fulfillmentAccountKey","in":"query","description":"고객사 식별값 (미입력 시 전체 고객사)","required":false,"schema":{"maxLength":64,"minLength":0,"type":"string"}},{"name":"size","in":"query","description":"페이지 크기 (기본 50, 최대 100)","required":false,"schema":{"type":"integer","format":"int32","default":50}},{"name":"X-Toss-Shopping-Connect-Api-Key","in":"header","description":"토스쇼핑에서 발급한 연동 API Key","required":true,"schema":{"type":"string"}},{"name":"X-Toss-Shopping-Connect-Tx-Id","in":"header","description":"요청별 고유 거래 식별값 (ASCII, 최대 64 byte)","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)","content":{"application/json":{"schema":{"type":"object","properties":{"resultType":{"type":"string","description":"응답 결과 타입","enum":["SUCCESS","FAIL"]},"error":{"type":"object","properties":{"errorCode":{"type":"string","description":"에러 코드","enum":["INVALID_REQUEST","BAD_REQUEST","INVALID_IP","SERVICE_ERROR","INTERNAL_SERVER_ERROR"]},"reason":{"type":"string","description":"에러 사유"}},"description":"에러 응답, resultType FAIL 시 제공"},"success":{"required":["content","hasNext"],"type":"object","properties":{"content":{"type":"array","description":"취소 요청 목록","items":{"required":["cancelStatus","item","orderId","orderProductId","requestedBy"],"type":"object","properties":{"orderProductId":{"type":"integer","description":"주문상품 ID","format":"int64"},"orderId":{"type":"integer","description":"주문 ID","format":"int64"},"cancelStatus":{"type":"string","description":"취소 상태","enum":["CANCEL_REQUESTED","CANCEL_COMPLETED"]},"requestedAt":{"type":"string","description":"취소 요청 일시"},"requestReason":{"type":"string","description":"취소 요청 사유"},"requestDetailReason":{"type":"string","description":"취소 요청 상세 사유"},"requestedBy":{"type":"string","description":"요청자","enum":["USER","MERCHANT","SYSTEM","FEP","TOSS_ONE","TOSS_ADMIN"]},"item":{"required":["name","productName","quantity"],"type":"object","properties":{"fulfillmentAccountKey":{"type":"string","description":"계정(고객사) 식별값"},"productName":{"type":"string","description":"상품명"},"name":{"type":"string","description":"옵션명"},"skus":{"type":"array","description":"SKU 목록","items":{"required":["quantity","skuKey"],"type":"object","properties":{"skuKey":{"type":"string","description":"고객사 상품코드 (SKU 식별자)"},"quantity":{"type":"integer","description":"SKU별 수량","format":"int32"}},"description":"SKU 목록"}},"quantity":{"type":"integer","description":"주문수량 (재고차감 수량)","format":"int32"}},"description":"상품 정보"}},"description":"취소 요청 목록"}},"nextCursor":{"type":"string","description":"다음 페이지 커서"},"hasNext":{"type":"boolean","description":"다음 페이지 존재 여부"}}}}}}}}}}}}} ``` ## 취소 완료 목록 조회 > 취소가 완료된 주문상품 목록을 조회합니다.\ > \ > 풀필먼트 시스템에서 주기적으로 폴링하여 취소 완료 건을 확인하는 용도입니다. ```json {"openapi":"3.0.1","info":{"title":"ShoppingFep API","version":"snapshot"},"servers":[{"url":"https://shopping-fep.toss.im"}],"security":[],"paths":{"/api/v3/shopping-fep/fulfillment/cancel-completed":{"get":{"tags":["풀필먼트 주문 관리"],"summary":"취소 완료 목록 조회","description":"취소가 완료된 주문상품 목록을 조회합니다.\n\n풀필먼트 시스템에서 주기적으로 폴링하여 취소 완료 건을 확인하는 용도입니다.","operationId":"getCancelCompleted","parameters":[{"name":"startAt","in":"query","description":"조회 시작 일시","required":true,"schema":{"type":"string"}},{"name":"endAt","in":"query","description":"조회 종료 일시","required":true,"schema":{"type":"string"}},{"name":"cursor","in":"query","description":"이전 페이지의 커서 토큰 값","required":false,"schema":{"maxLength":1024,"minLength":0,"type":"string"}},{"name":"fulfillmentAccountKey","in":"query","description":"고객사 식별값 (미입력 시 전체 고객사)","required":false,"schema":{"maxLength":64,"minLength":0,"type":"string"}},{"name":"size","in":"query","description":"페이지 크기 (기본 50, 최대 100)","required":false,"schema":{"type":"integer","format":"int32","default":50}},{"name":"X-Toss-Shopping-Connect-Api-Key","in":"header","description":"토스쇼핑에서 발급한 연동 API Key","required":true,"schema":{"type":"string"}},{"name":"X-Toss-Shopping-Connect-Tx-Id","in":"header","description":"요청별 고유 거래 식별값 (ASCII, 최대 64 byte)","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)","content":{"application/json":{"schema":{"type":"object","properties":{"resultType":{"type":"string","description":"응답 결과 타입","enum":["SUCCESS","FAIL"]},"error":{"type":"object","properties":{"errorCode":{"type":"string","description":"에러 코드","enum":["INVALID_REQUEST","BAD_REQUEST","INVALID_IP","SERVICE_ERROR","INTERNAL_SERVER_ERROR"]},"reason":{"type":"string","description":"에러 사유"}},"description":"에러 응답, resultType FAIL 시 제공"},"success":{"required":["content","hasNext"],"type":"object","properties":{"content":{"type":"array","description":"취소 완료 목록","items":{"required":["cancelStatus","item","orderId","orderProductId"],"type":"object","properties":{"orderProductId":{"type":"integer","description":"주문상품 ID","format":"int64"},"orderId":{"type":"integer","description":"주문 ID","format":"int64"},"cancelStatus":{"type":"string","description":"취소 상태","enum":["CANCEL_REQUESTED","CANCEL_COMPLETED"]},"canceledAt":{"type":"string","description":"취소 완료 일시"},"item":{"required":["name","productName","quantity"],"type":"object","properties":{"fulfillmentAccountKey":{"type":"string","description":"계정(고객사) 식별값"},"productName":{"type":"string","description":"상품명"},"name":{"type":"string","description":"옵션명"},"skus":{"type":"array","description":"SKU 목록","items":{"required":["quantity","skuKey"],"type":"object","properties":{"skuKey":{"type":"string","description":"고객사 상품코드 (SKU 식별자)"},"quantity":{"type":"integer","description":"SKU별 수량","format":"int32"}},"description":"SKU 목록"}},"quantity":{"type":"integer","description":"주문수량 (재고차감 수량)","format":"int32"}},"description":"상품 정보"}},"description":"취소 완료 목록"}},"nextCursor":{"type":"string","description":"다음 페이지 커서"},"hasNext":{"type":"boolean","description":"다음 페이지 존재 여부"}}}}}}}}}}}}} ``` ## 취소 요청에 대한 승인/거절 > 풀필먼트 시스템에서 취소 요청을 검토한 후 결과를 전달합니다.\ > \ > \- APPROVED: 취소 요청 승인 → 토스쇼핑에서 결제취소를 진행하고 주문 상태가 '결제취소'로 변경됩니다\ > \ > \- REJECTED: 취소 요청 거절 → 구매자에게 거절 사유가 안내됩니다 (rejectReason 필수) ```json {"openapi":"3.0.1","info":{"title":"ShoppingFep API","version":"snapshot"},"servers":[{"url":"https://shopping-fep.toss.im"}],"security":[],"paths":{"/api/v3/shopping-fep/fulfillment/orders/{orderProductId}/cancel-result":{"post":{"tags":["풀필먼트 주문 관리"],"summary":"취소 요청에 대한 승인/거절","description":"풀필먼트 시스템에서 취소 요청을 검토한 후 결과를 전달합니다.\n\n- APPROVED: 취소 요청 승인 → 토스쇼핑에서 결제취소를 진행하고 주문 상태가 '결제취소'로 변경됩니다\n\n- REJECTED: 취소 요청 거절 → 구매자에게 거절 사유가 안내됩니다 (rejectReason 필수)","operationId":"cancelResult","parameters":[{"name":"orderProductId","in":"path","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"X-Toss-Shopping-Connect-Api-Key","in":"header","description":"토스쇼핑에서 발급한 연동 API Key","required":true,"schema":{"type":"string"}},{"name":"X-Toss-Shopping-Connect-Tx-Id","in":"header","description":"요청별 고유 거래 식별값 (ASCII, 최대 64 byte)","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"required":["result"],"type":"object","properties":{"result":{"type":"string","description":"취소 요청 처리 결과","enum":["APPROVED","REJECTED"]},"rejectReason":{"maxLength":300,"minLength":0,"type":"string","description":"거절 사유 (REJECTED 시 필수, 최대 300자)"},"deliveryCompanyCode":{"maxLength":5,"minLength":0,"type":"string","description":"택배사 코드 (REJECTED + 송장 동봉 시, 최대 5자)"},"trackingNumber":{"maxLength":50,"minLength":0,"type":"string","description":"송장 번호 (REJECTED + 송장 동봉 시, 최대 50자)"},"shippedAt":{"type":"string","description":"발송 일시 (REJECTED + 송장 동봉 시)"}}}}},"required":true},"responses":{"200":{"description":"모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)","content":{"application/json":{"schema":{"type":"object","properties":{"resultType":{"type":"string","description":"응답 결과 타입","enum":["SUCCESS","FAIL"]},"error":{"type":"object","properties":{"errorCode":{"type":"string","description":"에러 코드","enum":["INVALID_REQUEST","INVALID_IP","SERVICE_ERROR","INTERNAL_SERVER_ERROR"]},"reason":{"type":"string","description":"에러 사유"}},"description":"에러 응답, resultType FAIL 시 제공"},"success":{"required":["success"],"type":"object","properties":{"success":{"type":"boolean","description":"성공 여부"}}}}}}}}}}}}} ``` {% hint style="info" %} 배송중/배송완료 주문에 반품 요청이 들어오면, 현재는 취소 요청과 동일하게 `cancel-requests` 폴링으로 수신해요. 단, 실제 처리(회수·재입고)는 출고 전 순수 취소와 흐름이 달라요. 배송 단계별 반품 처리 절차는 연동 시작 전에 담당자와 사전에 합의해주세요. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://shopping-docs.toss.im/connect/fulfillment-api/undefined-2.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.