배송

출고·배송상태 Push (송장 등록)

배송 단계가 바뀔 때마다 풀필먼트가 토스쇼핑에 Push해요. 배송 상태가 토스쇼핑 주문 상태를 전이시키므로, 단계 순서를 지켜 보내야 해요.

6.1 배송 상태 전이 흐름

delivery-status	의미	토스쇼핑 주문 상태 전이
CONFIRMED	발주 확인	→ PREPARING_PRODUCT
PICKING	상품 픽업	(내부 상태, 주문 상태 변경 없음)
PACKED	상품 포장	(내부 상태)
SHIPPED	송장 등록(발송) — 송장 필수	→ DELIVERING
IN_TRANSIT	배송중	(내부 상태)
DELIVERED	배송 완료	→ DELIVERED

배송 상태 업데이트

post

풀필먼트 시스템에서 배송 상태가 변경될 때 호출합니다.

• PICKING, PACKED는 물류 진행 상황 파악을 위한 참고용으로만 수집되며, 주문 상태는 변경되지 않습니다
• SHIPPED 시 택배사 코드(deliveryCompanyCode)와 송장 번호(trackingNumber)는 필수입니다
• 진행 중인 취소 요청이 있는 주문 상품의 경우 SHIPPED 상태로 변경할 수 없습니다 (취소 요청 미처리 상태로 배송이 진행되어 상태 불일치가 발생하는 것을 방지하기 위함)
• 송장 등록 전 반드시 취소 요청 유무를 먼저 확인 부탁드립니다

Path parameters

orderProductIdinteger · int64Required

Header parameters

X-Toss-Shopping-Connect-Api-KeystringRequired

토스쇼핑에서 발급한 연동 API Key

X-Toss-Shopping-Connect-Tx-IdstringRequired

요청별 고유 거래 식별값 (ASCII, 최대 64 byte)

Body

statusstring · enumRequired

배송상태

Possible values:

deliveryCompanyCodestring · max: 5Optional

택배사 코드 (SHIPPED 시 필수, 최대 5자)

trackingNumberstring · max: 50Optional

송장 번호 (SHIPPED 시 필수, 최대 50자)

shippedAtstringOptional

발송 일시

Example: 2026-04-01T10:00:00

Responses

200

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

application/json

resultTypestring · enumOptional

응답 결과 타입

Possible values:

post/api/v3/shopping-fep/fulfillment/orders/{orderProductId}/delivery-status

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

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

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

PICKING·PACKED·IN_TRANSIT는 풀필먼트 내부 진행 상태예요. 보내도 되지만 토스쇼핑 주문 상태는 바뀌지 않아요. 토스쇼핑 주문 상태를 실제로 움직이는 신호는 CONFIRMED(→상품준비중), SHIPPED(→배송중), DELIVERED(→배송완료) 세 가지예요.

6.3 택배사 코드 (deliveryCompanyCode) — 주요 택배사

택배사명	코드
우체국택배	01
CJ대한통운	04
한진택배	05
로젠택배	06
롯데택배	08
일양로지스	11
GS25편의점택배	24
CU편의점택배	46
ARGO	148

전체 택배사 코드(70개 이상)는 토스쇼핑 공식 코드 테이블을 참고해주세요.

계약 서브택배사와 실제 출고 택배사가 다를 수 있어요. 예를 들어 아르고는 계약상 서브택배사가 CJ로 명시되어 있어도 실제 출고는 한진(100%)으로 처리한 사례가 있었어요. deliveryCompanyCode에는 계약서가 아니라 실제 송장이 발행된 택배사 코드를 넣어주세요.