> 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-1.md). # 주문 ## 주문 상태 흐름 (orderProduct.status) 주문은 결제 완료(`PAID`)부터 구매 확정(`CONFIRMED_ORDER`)까지 단계적으로 전이돼요. 풀필먼트가 배송 상태를 Push할 때마다 토스쇼핑의 주문 상태가 함께 바뀌어요. ```mermaid stateDiagram-v2 [*] --> PAID: 결제 완료(주문 수집 대상) PAID --> PREPARING_PRODUCT: delivery-status=CONFIRMED(발주확인) PREPARING_PRODUCT --> DELAY_SHIPPING: 발송 지연 발생 DELAY_SHIPPING --> DELIVERING: delivery-status=SHIPPED(송장 등록) PREPARING_PRODUCT --> DELIVERING: delivery-status=SHIPPED(송장 등록) DELIVERING --> DELIVERED: delivery-status=DELIVERED(배송 완료) DELIVERED --> CONFIRMED_ORDER: 구매 확정 PAID --> CANCELED_PAYMENT: 취소 승인(APPROVED) PREPARING_PRODUCT --> CANCELED_PAYMENT: 취소 승인(APPROVED) CONFIRMED_ORDER --> [*] CANCELED_PAYMENT --> [*] ``` ## 주문 목록 조회 > 토스쇼핑에서 발생한 풀필먼트(도착보장) 상품 주문 목록을 조회합니다.\ > \ > \- 하나의 주문(orderId)에 여러 주문상품(orderProductId)이 포함될 수 있습니다\ > \ > \- 수집(발주확인)하지 않은 도착보장 주문상품 중, 결제완료 상태이며 진행중인 클레임이 없는 건만 조회됩니다 ```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":{"get":{"tags":["풀필먼트 주문 관리"],"summary":"주문 목록 조회","description":"토스쇼핑에서 발생한 풀필먼트(도착보장) 상품 주문 목록을 조회합니다.\n\n- 하나의 주문(orderId)에 여러 주문상품(orderProductId)이 포함될 수 있습니다\n\n- 수집(발주확인)하지 않은 도착보장 주문상품 중, 결제완료 상태이며 진행중인 클레임이 없는 건만 조회됩니다","operationId":"getOrders","parameters":[{"name":"startAt","in":"query","description":"조회 시작일 (예: 2026-03-30T10:00:00)","required":true,"schema":{"type":"string"}},{"name":"endAt","in":"query","description":"조회 종료일 (예: 2026-03-30T10:10:00)","required":true,"schema":{"type":"string"}},{"name":"fulfillmentAccountKey","in":"query","description":"고객사 식별값 (미입력 시 전체 고객사)","required":false,"schema":{"maxLength":64,"minLength":0,"type":"string"}},{"name":"cursor","in":"query","description":"다음 페이지 커서값 (최초 조회 시 미입력)","required":false,"schema":{"maxLength":1024,"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":["orderId","orderProducts"],"type":"object","properties":{"orderId":{"type":"integer","description":"주문 ID","format":"int64"},"paidAt":{"type":"string","description":"결제 일시 (미결제 OP 인 경우 null)"},"orderProducts":{"type":"array","description":"주문 상품 목록","items":{"required":["orderProductId","status"],"type":"object","properties":{"orderProductId":{"type":"integer","description":"주문 상품 ID","format":"int64"},"status":{"type":"string","description":"상품 주문 상태","enum":["PAID","PREPARING_PRODUCT","DELAY_SHIPPING","DELIVERING","DELIVERED","CONFIRMED_ORDER","CANCELED_PAYMENT"]},"fulfillmentAccountKey":{"type":"string","description":"풀필먼트 계정(고객사) 식별값"},"clientId":{"type":"string","description":"토스쇼핑 셀러 식별값 (OAuth clientId)"}},"description":"주문 상품 목록"}}},"description":"주문 목록"}},"nextCursor":{"type":"string","description":"다음 페이지 커서값 (null이면 마지막 페이지) orderId"},"hasNext":{"type":"boolean","description":"다음 페이지 존재 여부"}}}}}}}}}}}}} ``` **응답 예시** {% code title="Response" %} ```json { "content": [ { "orderProductId": 12345, "orderId": 67890, "clientId": "seller_client_id", "status": "PAID", "paidAt": "2026-03-30T10:00:00", "item": { "fulfillmentAccountKey": "3239", "productName": "반팔 티셔츠", "name": "색상: 블랙, 사이즈: L", "skus": [ { "skuKey": "SKU-001", "quantity": 1 }, { "skuKey": "SKU-002", "quantity": 1 } ], "quantity": 1 }, "orderConfirm": { "confirmedAt": null, "status": "UNCONFIRMED" }, "shipping": { "shippingDeadlineAt": "2026-04-01T23:59:59", "arrivalGuaranteeAt": "2026-04-03T23:59:59", "deliveryMemo": "부재 시 문 앞에 놓아주세요", "deliveredAt": null, "deliveryCompanyCode": null, "trackingNumber": null, "shippedAt": null } } ], "nextCursor": "eyJpZCI6MzE3OTQzfQ", "hasNext": true } ``` {% endcode %} {% hint style="info" %} 이 API로 조회되는 주문은 모두 도착보장 상품 대상이에요 {% endhint %} {% hint style="info" %} **폴링 시간 범위는 여유 있게**: 폴링 주기(예: 1분)보다 넓은 범위(예: 최근 5분)로 `startAt`/`endAt`을 잡아 경계 시점 주문 누락을 막아주세요. 중복 수집된 주문은 `orderProductId` 기준으로 멱등 처리하면 돼요. {% endhint %} ## 주문 단건 조회 > 주문 ID(orderId)로 풀필먼트(도착보장) 상품 주문을 단건 조회합니다.\ > \ > \- 하나의 주문(orderId)에 여러 주문상품(orderProductId)이 포함될 수 있습니다\ > \ > \- 수집(발주확인)하지 않은 도착보장 주문상품 중, 결제완료 상태이며 진행중인 클레임이 없는 건만 조회됩니다 ```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/{orderId}":{"get":{"tags":["풀필먼트 주문 관리"],"summary":"주문 단건 조회","description":"주문 ID(orderId)로 풀필먼트(도착보장) 상품 주문을 단건 조회합니다.\n\n- 하나의 주문(orderId)에 여러 주문상품(orderProductId)이 포함될 수 있습니다\n\n- 수집(발주확인)하지 않은 도착보장 주문상품 중, 결제완료 상태이며 진행중인 클레임이 없는 건만 조회됩니다","operationId":"getOrder","parameters":[{"name":"orderId","in":"path","description":"조회할 주문 ID","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"}}],"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":["orderId","orderProducts"],"type":"object","properties":{"orderId":{"type":"integer","description":"주문 ID","format":"int64"},"paidAt":{"type":"string","description":"결제 일시 (미결제 OP 인 경우 null)"},"orderProducts":{"type":"array","description":"주문 상품 목록","items":{"required":["orderProductId","status"],"type":"object","properties":{"orderProductId":{"type":"integer","description":"주문 상품 ID","format":"int64"},"status":{"type":"string","description":"상품 주문 상태","enum":["PAID","PREPARING_PRODUCT","DELAY_SHIPPING","DELIVERING","DELIVERED","CONFIRMED_ORDER","CANCELED_PAYMENT"]},"fulfillmentAccountKey":{"type":"string","description":"풀필먼트 계정(고객사) 식별값"},"clientId":{"type":"string","description":"토스쇼핑 셀러 식별값 (OAuth clientId)"}},"description":"주문 상품 목록"}}},"description":"주문 목록"}}}}}}}}}}} ``` **응답 예시** {% code title="Response" %} ```json { "content": [ { "orderProductId": 12345, "orderId": 67890, "clientId": "seller_client_id", "status": "PAID", "paidAt": "2026-03-30T10:00:00", "item": { "fulfillmentAccountKey": "3239", "productName": "반팔 티셔츠", "name": "색상: 블랙, 사이즈: L", "skus": [ { "skuKey": "SKU-001", "quantity": 1 } ], "quantity": 1 }, "price": { "totalPaymentAmount": 35000, "orderAmount": 38000, "discountAmount": 3000 }, "orderConfirm": { "confirmedAt": "2026-03-30T11:00:00", "status": "CONFIRMED" }, "shipping": { "shippingDeadlineAt": "2026-04-01T23:59:59", "arrivalGuaranteeAt": "2026-04-03T23:59:59", "deliveryMemo": "부재 시 문 앞에 놓아주세요", "deliveredAt": null, "deliveryCompanyCode": "08", "trackingNumber": null, "shippedAt": null }, "orderer": { "name": "김토스", "phone": "010-9876-5432" }, "recipient": { "name": "홍길동", "phone1": "010-1234-5678", "zipCode": "06234", "address": "서울시 강남구 테헤란로 123", "detailAddress": "101동 202호" } } ] } ``` {% endcode %} {% hint style="info" %} 수취인 개인정보(`recipient`)는 출고에 필요한 시점에만 조회하고, 보관·전송 시 개인정보 보호 정책을 지켜주세요. {% endhint %} ## 주문상품 상세 조회 > 주문상품의 상세 정보를 조회합니다. 상품, 발주, 배송, 클레임 정보를 포함합니다.\ > \ > \- 한 번의 요청으로 최대 100건의 주문상품을 조회할 수 있습니다\ > \- hasOngoingClaim로 클레임 진행 여부를 확인할 수 있습니다 (구매자가 취소를 철회하면 클레임이 종료되어 false 로 내려가므로 취소 승인/거절 콜백 전 재확인에 활용할 수 있습니다) ```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/detail":{"post":{"tags":["풀필먼트 주문 관리"],"summary":"주문상품 상세 조회","description":"주문상품의 상세 정보를 조회합니다. 상품, 발주, 배송, 클레임 정보를 포함합니다.\n\n- 한 번의 요청으로 최대 100건의 주문상품을 조회할 수 있습니다\n- hasOngoingClaim로 클레임 진행 여부를 확인할 수 있습니다 (구매자가 취소를 철회하면 클레임이 종료되어 false 로 내려가므로 취소 승인/거절 콜백 전 재확인에 활용할 수 있습니다)","operationId":"getOrderDetail","parameters":[{"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":["orderProductIds"],"type":"object","properties":{"orderProductIds":{"maxItems":100,"minItems":0,"type":"array","description":"주문상품 ID 목록 (최대 100건)","items":{"type":"integer","description":"주문상품 ID 목록 (최대 100건)","format":"int64"}}}}}},"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":["orders"],"type":"object","properties":{"orders":{"type":"array","description":"주문 상세 목록","items":{"required":["hasOngoingClaim","item","orderId","orderProductId","orderer","price","recipient","shipping","status"],"type":"object","properties":{"orderProductId":{"type":"integer","description":"주문상품 ID","format":"int64"},"orderId":{"type":"integer","description":"주문 ID","format":"int64"},"status":{"type":"string","description":"상품 주문 상태","enum":["PAID","PREPARING_PRODUCT","DELAY_SHIPPING","DELIVERING","DELIVERED","CONFIRMED_ORDER","CANCELED_PAYMENT"]},"hasOngoingClaim":{"type":"boolean","description":"진행중인 클레임 존재 여부 (구매자가 취소를 철회하면 클레임이 종료되어 false)"},"paidAt":{"type":"string","description":"결제 일시 (미결제 OP 인 경우 null)"},"item":{"required":["name","productId","productName","quantity","skus"],"type":"object","properties":{"itemId":{"type":"integer","description":"옵션 ID (상품 정보 미확인 시 null)","format":"int64"},"productId":{"type":"integer","description":"상품 ID","format":"int64"},"productName":{"type":"string","description":"상품명"},"name":{"type":"string","description":"옵션명"},"skus":{"type":"array","description":"SKU 목록 (1개 이상)","items":{"required":["quantity","skuKey"],"type":"object","properties":{"skuKey":{"type":"string","description":"고객사 상품코드 (SKU 식별자)"},"quantity":{"type":"integer","description":"SKU별 수량","format":"int32"}},"description":"SKU 목록 (1개 이상)"}},"fulfillmentAccountKey":{"type":"string","description":"계정(고객사) 식별값 (미연결 OP 인 경우 null)"},"clientId":{"type":"string","description":"토스쇼핑 셀러 식별값 (OAuth clientId, 미연결 OP 인 경우 null)"},"fulfillmentCenterKey":{"type":"string","description":"물류센터 식별값 (미연결 OP 인 경우 null)"},"quantity":{"type":"integer","description":"주문수량 (재고차감 수량)","format":"int32"}},"description":"상품 정보"},"price":{"required":["discountAmount","orderAmount","totalPaymentAmount"],"type":"object","properties":{"totalPaymentAmount":{"type":"integer","description":"총 결제 금액","format":"int64"},"orderAmount":{"type":"integer","description":"상품 주문 금액","format":"int64"},"discountAmount":{"type":"integer","description":"상품별 할인액","format":"int64"}},"description":"가격 정보"},"orderConfirm":{"required":["status"],"type":"object","properties":{"confirmedAt":{"type":"string","description":"발주 확인일 (null이면 미확인)"},"status":{"type":"string","description":"발주 상태","enum":["UNCONFIRMED","CONFIRMED","CANCELLED"]}},"description":"발주 확인 정보"},"shipping":{"type":"object","properties":{"shippingDeadlineAt":{"type":"string","description":"발송 기한 (미설정 OP 인 경우 null)"},"arrivalGuaranteeAt":{"type":"string","description":"배송 도착 보장 일시 (도착 보장 미적용 OP는 null)"},"deliveryMemo":{"type":"string","description":"배송 메모"},"deliveredAt":{"type":"string","description":"배송 완료 일시"},"deliveryCompanyCode":{"type":"string","description":"택배사 코드"},"trackingNumber":{"type":"string","description":"송장 번호"},"shippedAt":{"type":"string","description":"발송 일시"}},"description":"배송정보"},"orderer":{"required":["name","phone"],"type":"object","properties":{"name":{"type":"string","description":"주문자 이름"},"phone":{"type":"string","description":"주문자 연락처"}},"description":"주문자 정보"},"recipient":{"type":"object","properties":{"name":{"type":"string","description":"수령인 이름 (배송지 미설정 시 null)"},"phone1":{"type":"string","description":"수령인 연락처1 (배송지 미설정 시 null)"},"zipCode":{"type":"string","description":"우편번호 (배송지 미설정 시 null)"},"address":{"type":"string","description":"기본 주소 (배송지 미설정 시 null)"},"detailAddress":{"type":"string","description":"상세 주소 (배송지 미설정 시 null)"}},"description":"수령인 & 배송지 주소"}},"description":"주문 상세 목록"}}}}}}}}}}}}}} ``` ## 취소·반품·교환 처리 취소 요청 목록은 풀필먼트가 **폴링(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 %} ## 출고·배송상태 Push (송장 등록) 배송 단계가 바뀔 때마다 풀필먼트가 토스쇼핑에 **Push**해요. 배송 상태가 토스쇼핑 주문 상태를 전이시키므로, 단계 순서를 지켜 보내야 해요. #### 배송 상태 전이 흐름 ```mermaid flowchart LR CONFIRMED[CONFIRMED 발주확인] --> PICKING[PICKING 픽업] PICKING --> PACKED[PACKED 포장] PACKED --> SHIPPED[SHIPPED 송장등록·발송] SHIPPED --> IN_TRANSIT[IN_TRANSIT 배송중] IN_TRANSIT --> DELIVERED[DELIVERED 배송완료] ```
delivery-status의미토스쇼핑 주문 상태 전이
CONFIRMED발주 확인→ PREPARING_PRODUCT
PICKING상품 픽업(내부 상태, 주문 상태 변경 없음)
PACKED상품 포장(내부 상태)
SHIPPED송장 등록(발송) — 송장 필수→ DELIVERING
IN_TRANSIT배송중(내부 상태)
DELIVERED배송 완료→ DELIVERED
## 배송 상태 업데이트 > 풀필먼트 시스템에서 배송 상태가 변경될 때 호출합니다.\ > \ > \- PICKING, PACKED는 물류 진행 상황 파악을 위한 참고용으로만 수집되며, 주문 상태는 변경되지 않습니다\ > \- SHIPPED 시 택배사 코드(deliveryCompanyCode)와 송장 번호(trackingNumber)는 필수입니다\ > \- 진행 중인 취소 요청이 있는 주문 상품의 경우 SHIPPED 상태로 변경할 수 없습니다 (취소 요청 미처리 상태로 배송이 진행되어 상태 불일치가 발생하는 것을 방지하기 위함)\ > \- 송장 등록 전 반드시 취소 요청 유무를 먼저 확인 부탁드립니다 ```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}/delivery-status":{"post":{"tags":["풀필먼트 주문 관리"],"summary":"배송 상태 업데이트","description":"풀필먼트 시스템에서 배송 상태가 변경될 때 호출합니다.\n\n- PICKING, PACKED는 물류 진행 상황 파악을 위한 참고용으로만 수집되며, 주문 상태는 변경되지 않습니다\n- SHIPPED 시 택배사 코드(deliveryCompanyCode)와 송장 번호(trackingNumber)는 필수입니다\n- 진행 중인 취소 요청이 있는 주문 상품의 경우 SHIPPED 상태로 변경할 수 없습니다 (취소 요청 미처리 상태로 배송이 진행되어 상태 불일치가 발생하는 것을 방지하기 위함)\n- 송장 등록 전 반드시 취소 요청 유무를 먼저 확인 부탁드립니다","operationId":"updateDeliveryStatus","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":["status"],"type":"object","properties":{"status":{"type":"string","description":"배송상태","enum":["CONFIRMED","PICKING","PACKED","SHIPPED","SHIPPING_INFO_CHANGED"]},"deliveryCompanyCode":{"maxLength":5,"minLength":0,"type":"string","description":"택배사 코드 (SHIPPED 시 필수, 최대 5자)"},"trackingNumber":{"maxLength":50,"minLength":0,"type":"string","description":"송장 번호 (SHIPPED 시 필수, 최대 50자)"},"shippedAt":{"type":"string","description":"발송 일시"}}}}},"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" %} `PICKING`·`PACKED`·`IN_TRANSIT`는 풀필먼트 내부 진행 상태예요. 보내도 되지만 토스쇼핑 주문 상태는 바뀌지 않아요. 토스쇼핑 주문 상태를 실제로 움직이는 신호는 `CONFIRMED`(→상품준비중), `SHIPPED`(→배송중), `DELIVERED`(→배송완료) 세 가지예요. {% endhint %} #### 택배사 코드 (deliveryCompanyCode) — 주요 택배사 | 택배사명 | 코드 | | --------- | ----- | | 우체국택배 | `01` | | CJ대한통운 | `04` | | 한진택배 | `05` | | 로젠택배 | `06` | | 롯데택배 | `08` | | 일양로지스 | `11` | | GS25편의점택배 | `24` | | CU편의점택배 | `46` | | ARGO | `148` | > 전체 택배사 코드(70개 이상)는 토스쇼핑 공식 코드 테이블을 참고해주세요. {% hint style="info" %} **계약 서브택배사와 실제 출고 택배사가 다를 수 있어요.** 예를 들어 아르고는 계약상 서브택배사가 CJ로 명시되어 있어도 실제 출고는 한진(100%)으로 처리한 사례가 있었어요. `deliveryCompanyCode`에는 계약서가 아니라 **실제 송장이 발행된 택배사 코드**를 넣어주세요. {% 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-1.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.