> 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-3.md).

# 배송

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

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

#### 6.1 배송 상태 전이 흐름

```mermaid
flowchart LR
    CONFIRMED[CONFIRMED 발주확인] --> PICKING[PICKING 픽업]
    PICKING --> PACKED[PACKED 포장]
    PACKED --> SHIPPED[SHIPPED 송장등록·발송]
    SHIPPED --> IN_TRANSIT[IN_TRANSIT 배송중]
    IN_TRANSIT --> DELIVERED[DELIVERED 배송완료]
```

<table><thead><tr><th width="158.40234375">delivery-status</th><th>의미</th><th>토스쇼핑 주문 상태 전이</th></tr></thead><tbody><tr><td><code>CONFIRMED</code></td><td>발주 확인</td><td>→ <code>PREPARING_PRODUCT</code></td></tr><tr><td><code>PICKING</code></td><td>상품 픽업</td><td>(내부 상태, 주문 상태 변경 없음)</td></tr><tr><td><code>PACKED</code></td><td>상품 포장</td><td>(내부 상태)</td></tr><tr><td><code>SHIPPED</code></td><td>송장 등록(발송) — <strong>송장 필수</strong></td><td>→ <code>DELIVERING</code></td></tr><tr><td><code>IN_TRANSIT</code></td><td>배송중</td><td>(내부 상태)</td></tr><tr><td><code>DELIVERED</code></td><td>배송 완료</td><td>→ <code>DELIVERED</code></td></tr></tbody></table>

## 배송 상태 업데이트

> 풀필먼트 시스템에서 배송 상태가 변경될 때 호출합니다.\
> \
> \- 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 %}

#### 6.3 택배사 코드 (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-3.md?ask=<question>&goal=<endgoal>
```

`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.