주문
주문 상태 흐름 (orderProduct.status)
주문은 결제 완료(PAID)부터 구매 확정(CONFIRMED_ORDER)까지 단계적으로 전이돼요. 풀필먼트가 배송 상태를 Push할 때마다 토스쇼핑의 주문 상태가 함께 바뀌어요.
토스쇼핑에서 발생한 풀필먼트(도착보장) 상품 주문 목록을 조회합니다.
하나의 주문(orderId)에 여러 주문상품(orderProductId)이 포함될 수 있습니다
수집(발주확인)하지 않은 도착보장 주문상품 중, 결제완료 상태이며 진행중인 클레임이 없는 건만 조회됩니다
조회 시작일 (예: 2026-03-30T10:00:00)
2026-03-30T10:00:00조회 종료일 (예: 2026-03-30T10:10:00)
2026-03-30T10:10:00고객사 식별값 (미입력 시 전체 고객사)
다음 페이지 커서값 (최초 조회 시 미입력)
페이지 크기 (기본값: 50, 최대 100)
50토스쇼핑에서 발급한 연동 API Key
요청별 고유 거래 식별값 (ASCII, 최대 64 byte)
모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)
응답 결과 타입
GET /api/v3/shopping-fep/fulfillment/orders?startAt=2026-03-30T10%3A00%3A00&endAt=2026-03-30T10%3A10%3A00 HTTP/1.1
Host: shopping-fep.toss.im
X-Toss-Shopping-Connect-Api-Key: text
X-Toss-Shopping-Connect-Tx-Id: text
Accept: */*
모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)
{
"resultType": "SUCCESS",
"error": {
"errorCode": "INVALID_REQUEST",
"reason": "text"
},
"success": {
"content": [
{
"orderId": 1,
"paidAt": "2026-04-01T10:00:00",
"orderProducts": [
{
"orderProductId": 1,
"status": "PAID",
"fulfillmentAccountKey": "text",
"clientId": "text"
}
]
}
],
"nextCursor": "text",
"hasNext": true
}
}응답 예시
주문 ID(orderId)로 풀필먼트(도착보장) 상품 주문을 단건 조회합니다.
하나의 주문(orderId)에 여러 주문상품(orderProductId)이 포함될 수 있습니다
수집(발주확인)하지 않은 도착보장 주문상품 중, 결제완료 상태이며 진행중인 클레임이 없는 건만 조회됩니다
조회할 주문 ID
토스쇼핑에서 발급한 연동 API Key
요청별 고유 거래 식별값 (ASCII, 최대 64 byte)
모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)
응답 결과 타입
GET /api/v3/shopping-fep/fulfillment/orders/{orderId} HTTP/1.1
Host: shopping-fep.toss.im
X-Toss-Shopping-Connect-Api-Key: text
X-Toss-Shopping-Connect-Tx-Id: text
Accept: */*
모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)
{
"resultType": "SUCCESS",
"error": {
"errorCode": "INVALID_REQUEST",
"reason": "text"
},
"success": {
"orderId": 1,
"paidAt": "2026-04-01T10:00:00",
"orderProducts": [
{
"orderProductId": 1,
"status": "PAID",
"fulfillmentAccountKey": "text",
"clientId": "text"
}
]
}
}응답 예시
주문상품의 상세 정보를 조회합니다. 상품, 발주, 배송, 클레임 정보를 포함합니다.
한 번의 요청으로 최대 100건의 주문상품을 조회할 수 있습니다
hasOngoingClaim로 클레임 진행 여부를 확인할 수 있습니다 (구매자가 취소를 철회하면 클레임이 종료되어 false 로 내려가므로 취소 승인/거절 콜백 전 재확인에 활용할 수 있습니다)
토스쇼핑에서 발급한 연동 API Key
요청별 고유 거래 식별값 (ASCII, 최대 64 byte)
주문상품 ID 목록 (최대 100건)
모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)
응답 결과 타입
POST /api/v3/shopping-fep/fulfillment/orders/detail HTTP/1.1
Host: shopping-fep.toss.im
X-Toss-Shopping-Connect-Api-Key: text
X-Toss-Shopping-Connect-Tx-Id: text
Content-Type: application/json
Accept: */*
Content-Length: 23
{
"orderProductIds": [
1
]
}모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)
{
"resultType": "SUCCESS",
"error": {
"errorCode": "INVALID_REQUEST",
"reason": "text"
},
"success": {
"orders": [
{
"orderProductId": 1,
"orderId": 1,
"status": "PAID",
"hasOngoingClaim": true,
"paidAt": "2026-04-01T10:00:00",
"item": {
"itemId": 1,
"productId": 1,
"productName": "text",
"name": "text",
"skus": [
{
"skuKey": "text",
"quantity": 1
}
],
"fulfillmentAccountKey": "text",
"clientId": "text",
"fulfillmentCenterKey": "text",
"quantity": 1
},
"price": {
"totalPaymentAmount": 1,
"orderAmount": 1,
"discountAmount": 1
},
"orderConfirm": {
"confirmedAt": "2026-04-01T11:00:00",
"status": "UNCONFIRMED"
},
"shipping": {
"shippingDeadlineAt": "2026-04-02T12:00:00",
"arrivalGuaranteeAt": "2026-04-03T23:59:59",
"deliveryMemo": "text",
"deliveredAt": "2026-04-03T18:20:00",
"deliveryCompanyCode": "text",
"trackingNumber": "text",
"shippedAt": "2026-04-01T10:00:00"
},
"orderer": {
"name": "text",
"phone": "text"
},
"recipient": {
"name": "text",
"phone1": "text",
"zipCode": "text",
"address": "text",
"detailAddress": "text"
}
}
]
}
}취소·반품·교환 처리
취소 요청 목록은 풀필먼트가 폴링(Pull) 으로 가져가고, 검토 결과(승인/거절)는 풀필먼트가 Push해요.
취소 처리 흐름
고객/셀러/관리자의 취소 요청 목록을 조회합니다.
풀필먼트 시스템에서 주기적으로 폴링하여 신규 취소 요청을 확인하는 용도입니다.
조회 시작 일시
2026-03-30T10:00:00조회 종료 일시
2026-03-30T10:10:00이전 페이지의 커서 토큰 값
고객사 식별값 (미입력 시 전체 고객사)
페이지 크기 (기본 50, 최대 100)
50토스쇼핑에서 발급한 연동 API Key
요청별 고유 거래 식별값 (ASCII, 최대 64 byte)
모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)
응답 결과 타입
GET /api/v3/shopping-fep/fulfillment/cancel-requests?startAt=2026-03-30T10%3A00%3A00&endAt=2026-03-30T10%3A10%3A00 HTTP/1.1
Host: shopping-fep.toss.im
X-Toss-Shopping-Connect-Api-Key: text
X-Toss-Shopping-Connect-Tx-Id: text
Accept: */*
모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)
{
"resultType": "SUCCESS",
"error": {
"errorCode": "INVALID_REQUEST",
"reason": "text"
},
"success": {
"content": [
{
"orderProductId": 1,
"orderId": 1,
"cancelStatus": "CANCEL_REQUESTED",
"requestedAt": "2026-04-02T09:15:00",
"requestReason": "text",
"requestDetailReason": "text",
"requestedBy": "USER",
"item": {
"fulfillmentAccountKey": "text",
"productName": "text",
"name": "text",
"skus": [
{
"skuKey": "text",
"quantity": 1
}
],
"quantity": 1
}
}
],
"nextCursor": "text",
"hasNext": true
}
}취소가 완료된 주문상품 목록을 조회합니다.
풀필먼트 시스템에서 주기적으로 폴링하여 취소 완료 건을 확인하는 용도입니다.
조회 시작 일시
2026-03-30T10:00:00조회 종료 일시
2026-03-30T10:10:00이전 페이지의 커서 토큰 값
고객사 식별값 (미입력 시 전체 고객사)
페이지 크기 (기본 50, 최대 100)
50토스쇼핑에서 발급한 연동 API Key
요청별 고유 거래 식별값 (ASCII, 최대 64 byte)
모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)
응답 결과 타입
GET /api/v3/shopping-fep/fulfillment/cancel-completed?startAt=2026-03-30T10%3A00%3A00&endAt=2026-03-30T10%3A10%3A00 HTTP/1.1
Host: shopping-fep.toss.im
X-Toss-Shopping-Connect-Api-Key: text
X-Toss-Shopping-Connect-Tx-Id: text
Accept: */*
모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)
{
"resultType": "SUCCESS",
"error": {
"errorCode": "INVALID_REQUEST",
"reason": "text"
},
"success": {
"content": [
{
"orderProductId": 1,
"orderId": 1,
"cancelStatus": "CANCEL_REQUESTED",
"canceledAt": "2026-04-02T14:40:00",
"item": {
"fulfillmentAccountKey": "text",
"productName": "text",
"name": "text",
"skus": [
{
"skuKey": "text",
"quantity": 1
}
],
"quantity": 1
}
}
],
"nextCursor": "text",
"hasNext": true
}
}풀필먼트 시스템에서 취소 요청을 검토한 후 결과를 전달합니다.
APPROVED: 취소 요청 승인 → 토스쇼핑에서 결제취소를 진행하고 주문 상태가 '결제취소'로 변경됩니다
REJECTED: 취소 요청 거절 → 구매자에게 거절 사유가 안내됩니다 (rejectReason 필수)
토스쇼핑에서 발급한 연동 API Key
요청별 고유 거래 식별값 (ASCII, 최대 64 byte)
취소 요청 처리 결과
거절 사유 (REJECTED 시 필수, 최대 300자)
택배사 코드 (REJECTED + 송장 동봉 시, 최대 5자)
송장 번호 (REJECTED + 송장 동봉 시, 최대 50자)
발송 일시 (REJECTED + 송장 동봉 시)
2026-04-01T10:00:00모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)
응답 결과 타입
POST /api/v3/shopping-fep/fulfillment/orders/{orderProductId}/cancel-result HTTP/1.1
Host: shopping-fep.toss.im
X-Toss-Shopping-Connect-Api-Key: text
X-Toss-Shopping-Connect-Tx-Id: text
Content-Type: application/json
Accept: */*
Content-Length: 130
{
"result": "APPROVED",
"rejectReason": "text",
"deliveryCompanyCode": "text",
"trackingNumber": "text",
"shippedAt": "2026-04-01T10:00:00"
}모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)
{
"resultType": "SUCCESS",
"error": {
"errorCode": "INVALID_REQUEST",
"reason": "text"
},
"success": {
"success": true
}
}출고·배송상태 Push (송장 등록)
배송 단계가 바뀔 때마다 풀필먼트가 토스쇼핑에 Push해요. 배송 상태가 토스쇼핑 주문 상태를 전이시키므로, 단계 순서를 지켜 보내야 해요.
배송 상태 전이 흐름
CONFIRMED
발주 확인
→ PREPARING_PRODUCT
PICKING
상품 픽업
(내부 상태, 주문 상태 변경 없음)
PACKED
상품 포장
(내부 상태)
SHIPPED
송장 등록(발송) — 송장 필수
→ DELIVERING
IN_TRANSIT
배송중
(내부 상태)
DELIVERED
배송 완료
→ DELIVERED
풀필먼트 시스템에서 배송 상태가 변경될 때 호출합니다.
PICKING, PACKED는 물류 진행 상황 파악을 위한 참고용으로만 수집되며, 주문 상태는 변경되지 않습니다
SHIPPED 시 택배사 코드(deliveryCompanyCode)와 송장 번호(trackingNumber)는 필수입니다
진행 중인 취소 요청이 있는 주문 상품의 경우 SHIPPED 상태로 변경할 수 없습니다 (취소 요청 미처리 상태로 배송이 진행되어 상태 불일치가 발생하는 것을 방지하기 위함)
송장 등록 전 반드시 취소 요청 유무를 먼저 확인 부탁드립니다
토스쇼핑에서 발급한 연동 API Key
요청별 고유 거래 식별값 (ASCII, 최대 64 byte)
배송상태
택배사 코드 (SHIPPED 시 필수, 최대 5자)
송장 번호 (SHIPPED 시 필수, 최대 50자)
발송 일시
2026-04-01T10:00:00모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)
응답 결과 타입
POST /api/v3/shopping-fep/fulfillment/orders/{orderProductId}/delivery-status HTTP/1.1
Host: shopping-fep.toss.im
X-Toss-Shopping-Connect-Api-Key: text
X-Toss-Shopping-Connect-Tx-Id: text
Content-Type: application/json
Accept: */*
Content-Length: 109
{
"status": "CONFIRMED",
"deliveryCompanyCode": "text",
"trackingNumber": "text",
"shippedAt": "2026-04-01T10:00:00"
}모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)
{
"resultType": "SUCCESS",
"error": {
"errorCode": "INVALID_REQUEST",
"reason": "text"
},
"success": {
"success": true
}
}택배사 코드 (deliveryCompanyCode) — 주요 택배사
우체국택배
01
CJ대한통운
04
한진택배
05
로젠택배
06
롯데택배
08
일양로지스
11
GS25편의점택배
24
CU편의점택배
46
ARGO
148
전체 택배사 코드(70개 이상)는 토스쇼핑 공식 코드 테이블을 참고해주세요.
Last updated
Was this helpful?