# 주문

## 주문 내역 조회

> 커서 기반 페이지네이션을 사용하여 주문 내역을 조회합니다.\
> \
> \## 조회 조건\
> \- 조회 범위는 최대 31일까지 조회 가능합니다\
> \- \`status\` 파라미터를 생략하면 전체 주문 상태를 조회합니다\
> \- \`limit\`은 최소 1, 최대 50까지 설정 가능하며, 범위를 벗어나면 자동으로 50으로 조정됩니다\
> \
> \## 페이지네이션\
> \- 첫 페이지 조회 시 \`nextCursor\`를 생략합니다\
> \- 다음 페이지 조회 시 응답으로 받은 \`nextCursor\` 값을 그대로 전달합니다\
> \- 응답의 \`nextCursor\`가 null이면 마지막 페이지입니다

```json
{"openapi":"3.0.1","info":{"title":"ShoppingFep API","version":"snapshot"},"servers":[{"url":"https://shopping-fep.toss.im"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"OrderCursorFepResponse":{"required":["results"],"type":"object","properties":{"results":{"type":"array","description":"주문 내역 목록","items":{"$ref":"#/components/schemas/GetOrderHistoriesCursorResponse"}},"nextCursor":{"type":"string","description":"다음 페이지 커서 정보. 마지막 페이지면 null"}},"description":"주문 응답 객체"},"GetOrderHistoriesCursorResponse":{"required":["address","detailAddress","optionName","orderId","orderProductId","orderProductStatus","orderedAt","ordererName","ordererPhone","originPrice","price","productId","productName","quantity","receiverName","receiverPhone","stockId","tossPayDiscount","tossPayPoint","tossShoppingDiscount","totalDiscountPrice","zipCode"],"type":"object","properties":{"orderedAt":{"type":"string","description":"주문 시각","format":"date-time"},"canceledAt":{"type":"string","description":"주문 취소 시각","format":"date-time"},"confirmedAt":{"type":"string","description":"구매확정 일시","format":"date-time"},"shippingDeadlineAt":{"type":"string","description":"배송 마감 기한","format":"date"},"orderId":{"type":"integer","description":"주문 ID, 주문건별 ID이므로 하나의 주문에 여러 상품이 포함될 수 있음","format":"int64"},"orderProductId":{"type":"integer","description":"주문 상품 ID, 주문에 포함된 주문상품별 ID","format":"int64"},"productId":{"type":"integer","description":"상품 ID","format":"int64"},"stockId":{"type":"integer","description":"재고 ID","format":"int64"},"ordererName":{"type":"string","description":"주문자 이름"},"ordererPhone":{"type":"string","description":"주문자 휴대전화번호"},"ordererRealPhone":{"type":"string","description":"주문자 실제 휴대전화번호"},"receiverName":{"type":"string","description":"수령인 이름"},"receiverPhone":{"type":"string","description":"수령인 휴대전화번호"},"receiverRealPhone":{"type":"string","description":"수령인 실제 휴대전화번호"},"address":{"type":"string","description":"배송지"},"detailAddress":{"type":"string","description":"배송지 상세"},"zipCode":{"type":"string","description":"우편번호"},"shippingNote":{"type":"string","description":"주문요청사항"},"productName":{"type":"string","description":"상품명"},"optionName":{"type":"string","description":"옵션명"},"quantity":{"type":"integer","description":"주문 수량","format":"int32"},"price":{"type":"integer","description":"판매가 주문 총금액 (판매가 * 주문 수량)","format":"int64"},"originPrice":{"type":"integer","description":"정상가 주문 총금액 (정상가 * 주문 수량)","format":"int64"},"totalDiscountPrice":{"type":"integer","description":"총 할인금액 (토스쇼핑 자체 할인금액 + 토스페이 할인금액). 추후 할인정책이 추가될 경우, 총 할인금액에 추가 항목이 포함될 수 있습니다","format":"int64"},"tossShoppingDiscount":{"type":"integer","description":"토스쇼핑 자체 할인금액","format":"int64"},"tossPayDiscount":{"type":"integer","description":"토스페이 할인금액","format":"int64"},"tossPayPoint":{"type":"integer","description":"토스포인트 사용 금액","format":"int64"},"orderProductStatus":{"type":"string","description":"주문 상품 상태","enum":["BEFORE_PAYMENT","PAID","PREPARING_PRODUCT","DELIVERING","DELIVERED","CONFIRMED_ORDER","CLAIM_REQUESTED_CANCEL","CANCELED_PAYMENT","CLAIM_REJECTED_CANCEL","REQUESTED_EXCHANGE","ONGOING_EXCHANGE","COMPLETED_EXCHANGE","CLAIM_REJECTED_EXCHANGE","REQUESTED_RETURN","ONGOING_RETURN","COMPLETED_RETURN","CLAIM_REJECTED_RETURN","CLAIM_COLLECTING","CLAIM_COLLECTED","CLAIM_DELIVERING"]},"deliveryCompanyCode":{"type":"string","description":"배송 회사 코드 (CJ대한통운, 우체국택배, 한진택배, 로젠택배 등)"},"shippingTrackingNumber":{"type":"string","description":"송장번호"},"deliveryFeeGroupId":{"type":"integer","description":"묶음그룹 ID, 하나의 묶음 단위 ID","format":"int64"},"deliveryFee":{"type":"integer","description":"총 배송비 (일반 배송비 + 제주/도서산간배송비)","format":"int64"},"deliveryLocationType":{"type":"string","description":"배송지 유형","enum":["JEJU","MOUNTAIN","NORMAL"]},"normalDeliveryFee":{"type":"integer","description":"일반 배송비","format":"int64"},"jejuDeliveryFee":{"type":"integer","description":"제주 배송비","format":"int64"},"mountainDeliveryFee":{"type":"integer","description":"도서산간 배송비","format":"int64"},"productManagementCode":{"type":"string","description":"상품 관리 코드"},"productItemManagementCode":{"type":"string","description":"옵션 관리 코드"}},"description":"주문 내역 목록"}}},"paths":{"/api/v3/shopping-fep/orders/v2":{"get":{"tags":["주문"],"summary":"주문 내역 조회","description":"커서 기반 페이지네이션을 사용하여 주문 내역을 조회합니다.\n\n## 조회 조건\n- 조회 범위는 최대 31일까지 조회 가능합니다\n- `status` 파라미터를 생략하면 전체 주문 상태를 조회합니다\n- `limit`은 최소 1, 최대 50까지 설정 가능하며, 범위를 벗어나면 자동으로 50으로 조정됩니다\n\n## 페이지네이션\n- 첫 페이지 조회 시 `nextCursor`를 생략합니다\n- 다음 페이지 조회 시 응답으로 받은 `nextCursor` 값을 그대로 전달합니다\n- 응답의 `nextCursor`가 null이면 마지막 페이지입니다","operationId":"listOrdersV2_1","parameters":[{"name":"status","in":"query","description":"조회용 주문 상품 상태 (생략 시 전체 조회)","required":false,"schema":{"type":"string","enum":["PAID","CANCELED_PAYMENT","PREPARING_PRODUCT","DELIVERING","DELIVERED","CONFIRMED_ORDER"]}},{"name":"startDate","in":"query","description":"조회 시작일자 (yyyy-MM-dd)","required":true,"schema":{"type":"string","format":"date"}},{"name":"endDate","in":"query","description":"조회 종료일자 (yyyy-MM-dd). 조회 범위는 최대 31일","required":true,"schema":{"type":"string","format":"date"}},{"name":"nextCursor","in":"query","description":"다음 페이지를 위한 커서 (직전 호출에서 받은 nextCursor를 그대로 전달)","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"페이지 사이즈 (기본값: 20, 최대 50)","required":false,"schema":{"type":"integer","format":"int32","default":20}},{"name":"partnerName","in":"query","description":"연동 프로그램명 또는 자사 서비스명","required":false,"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_DATE_RANGE","COMMON_ERROR"]},"reason":{"type":"string","description":"에러 사유"}},"description":"에러 응답, resultType FAIL 시 제공"},"success":{"$ref":"#/components/schemas/OrderCursorFepResponse"}}}}}}}}}}}
```

## 주문 상품 단건 조회

> 주문 상품 ID로 특정 주문 상품의 상세 정보를 조회합니다.

```json
{"openapi":"3.0.1","info":{"title":"ShoppingFep API","version":"snapshot"},"servers":[{"url":"https://shopping-fep.toss.im"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"OrderProductFepResponse":{"required":["address","detailAddress","optionName","orderId","orderProductId","orderProductStatus","orderedAt","ordererName","ordererPhone","originPrice","price","productId","productName","quantity","receiverName","receiverPhone","stockId","tossPayDiscount","tossPayPoint","tossShoppingDiscount","totalDiscountPrice","zipCode"],"type":"object","properties":{"orderedAt":{"type":"string","description":"주문 시각","format":"date-time"},"canceledAt":{"type":"string","description":"주문 취소 시각","format":"date-time"},"confirmedAt":{"type":"string","description":"구매확정 일시","format":"date-time"},"shippingDeadlineAt":{"type":"string","description":"배송 마감 기한","format":"date"},"orderId":{"type":"integer","description":"주문 ID, 주문건별 ID이므로 하나의 주문에 여러 상품이 포함될 수 있음","format":"int64"},"orderProductId":{"type":"integer","description":"주문 상품 ID, 주문에 포함된 주문상품별 ID","format":"int64"},"productId":{"type":"integer","description":"상품 ID","format":"int64"},"stockId":{"type":"integer","description":"재고 ID","format":"int64"},"ordererName":{"type":"string","description":"주문자 이름"},"ordererPhone":{"type":"string","description":"주문자 휴대전화번호"},"ordererRealPhone":{"type":"string","description":"주문자 실제 휴대전화번호"},"receiverName":{"type":"string","description":"수령인 이름"},"receiverPhone":{"type":"string","description":"수령인 휴대전화번호"},"receiverRealPhone":{"type":"string","description":"수령인 실제 휴대전화번호"},"address":{"type":"string","description":"배송지"},"detailAddress":{"type":"string","description":"배송지 상세"},"zipCode":{"type":"string","description":"우편번호"},"shippingNote":{"type":"string","description":"주문요청사항"},"productName":{"type":"string","description":"상품명"},"optionName":{"type":"string","description":"옵션명"},"quantity":{"type":"integer","description":"주문 수량","format":"int32"},"price":{"type":"integer","description":"판매가 주문 총금액 (판매가 * 주문 수량)","format":"int64"},"originPrice":{"type":"integer","description":"정상가 주문 총금액 (정상가 * 주문 수량)","format":"int64"},"totalDiscountPrice":{"type":"integer","description":"총 할인금액 (토스쇼핑 자체 할인금액 + 토스페이 할인금액). 추후 할인정책이 추가될 경우, 총 할인금액에 추가 항목이 포함될 수 있습니다","format":"int64"},"tossShoppingDiscount":{"type":"integer","description":"토스쇼핑 자체 할인금액","format":"int64"},"tossPayDiscount":{"type":"integer","description":"토스페이 할인금액","format":"int64"},"tossPayPoint":{"type":"integer","description":"토스포인트 사용 금액","format":"int64"},"orderProductStatus":{"type":"string","description":"주문 상품 상태","enum":["BEFORE_PAYMENT","PAID","PREPARING_PRODUCT","DELIVERING","DELIVERED","CONFIRMED_ORDER","CLAIM_REQUESTED_CANCEL","CANCELED_PAYMENT","CLAIM_REJECTED_CANCEL","REQUESTED_EXCHANGE","ONGOING_EXCHANGE","COMPLETED_EXCHANGE","CLAIM_REJECTED_EXCHANGE","REQUESTED_RETURN","ONGOING_RETURN","COMPLETED_RETURN","CLAIM_REJECTED_RETURN","CLAIM_COLLECTING","CLAIM_COLLECTED","CLAIM_DELIVERING"]},"deliveryCompanyCode":{"type":"string","description":"배송 회사 코드 (CJ대한통운, 우체국택배, 한진택배, 로젠택배 등)"},"shippingTrackingNumber":{"type":"string","description":"송장번호"},"deliveryFeeGroupId":{"type":"integer","description":"묶음그룹 ID, 하나의 묶음 단위 ID","format":"int64"},"deliveryFee":{"type":"integer","description":"총 배송비 (일반 배송비 + 제주/도서산간배송비)","format":"int64"},"deliveryLocationType":{"type":"string","description":"배송지 유형","enum":["JEJU","MOUNTAIN","NORMAL"]},"normalDeliveryFee":{"type":"integer","description":"일반 배송비","format":"int64"},"jejuDeliveryFee":{"type":"integer","description":"제주 배송비","format":"int64"},"mountainDeliveryFee":{"type":"integer","description":"도서산간 배송비","format":"int64"},"productManagementCode":{"type":"string","description":"상품 관리 코드"},"productItemManagementCode":{"type":"string","description":"옵션 관리 코드"}}}}},"paths":{"/api/v3/shopping-fep/orders/products/{orderProductId}":{"get":{"tags":["주문"],"summary":"주문 상품 단건 조회","description":"주문 상품 ID로 특정 주문 상품의 상세 정보를 조회합니다.","operationId":"getOrderProduct","parameters":[{"name":"orderProductId","in":"path","description":"주문 상품 ID","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"partnerName","in":"query","description":"연동 프로그램명 또는 자사 서비스명","required":false,"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","COMMON_ERROR"]},"reason":{"type":"string","description":"에러 사유"}},"description":"에러 응답, resultType FAIL 시 제공"},"success":{"$ref":"#/components/schemas/OrderProductFepResponse"}}}}}}}}}}}
```

## 주문 상품 상태 변경

> 주문 상품의 상태를 일괄 변경합니다.\
> \
> \## 요청 제한\
> \- 한 번에 최대 100개의 주문 상품을 변경할 수 있습니다\
> \
> \## 발송지연 상태 변경 시 필수 항목\
> \`status\`가 \`DELAY\_SHIPPING\`인 경우 다음 필드가 필수입니다:\
> \- \`shippingDeadlineAt\`: 발송 예정 일시 (yyyy-MM-ddTHH:mm:ss 형식)\
>   \- 오늘 기준 1일 이상 32일 이하로 설정 가능합니다\
> \- \`delayReasonType\`: 발송지연 사유\
>   \- \*\*READY\_PRODUCT\*\*: 상품준비중\
>   \- \*\*CUSTOM\_INFO\_NOT\_ENTER\*\*: 주문제작 정보 미입력\
> \
> \## 응답\
> \- 일부 상품의 상태 변경이 실패하더라도 성공한 상품은 상태가 변경됩니다\
> \- \`failedCount\`가 0보다 크면 \`failedReasons\`에서 실패 사유를 확인할 수 있습니다

```json
{"openapi":"3.0.1","info":{"title":"ShoppingFep API","version":"snapshot"},"servers":[{"url":"https://shopping-fep.toss.im"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ChangeOrderProductStatusBody":{"required":["orderProductIds","status"],"type":"object","properties":{"orderProductIds":{"type":"array","description":"주문 상품 ID 목록 (최대 100개)","items":{"type":"integer","description":"주문 상품 ID 목록 (최대 100개)","format":"int64"}},"status":{"type":"string","description":"주문 상품 상태\n\n## 허용 상태 전이\n\n- 결제완료 → 상품준비중, 발송지연, 결제취소\n- 상품준비중 → 발송지연, 결제취소\n- 발송지연 → 결제취소\n- 배송완료 → 결제취소\n\n## 주의사항\n\n- 배송중(DELIVERING) 상태로 변경하려면 별도의 배송정보 변경 API를 사용해야 합니다\n- 발송지연은 주문 상품당 1회만 설정 가능합니다\n- 결제취소, 결제대기, 결제만료 상태의 주문 상품은 상태 변경이 불가능하며 건너뛰어 처리됩니다","enum":["PREPARING_PRODUCT","DELAY_SHIPPING","DELIVERED","CANCELED_PAYMENT"]},"shippingDeadlineAt":{"type":"string","description":"발송지연 시각 (yyyy-MM-ddTHH:mm:ss). 발송지연 상태 변경 시 필수","format":"date-time"},"delayReasonType":{"type":"string","description":"발송지연 사유. 발송지연 상태 변경 시 필수","enum":["READY_PRODUCT","CUSTOM_INFO_NOT_ENTER"]},"partnerName":{"type":"string","description":"연동 프로그램명 또는 자사 서비스명"}}},"ChangeOrderProductStatusFepResponse":{"required":["failedCount","failedReasons","totalCount"],"type":"object","properties":{"totalCount":{"type":"integer","description":"전체 건수","format":"int32"},"failedCount":{"type":"integer","description":"실패 건수","format":"int32"},"failedReasons":{"type":"array","description":"실패 사유","items":{"type":"string","description":"실패 사유"}}}}}},"paths":{"/api/v3/shopping-fep/orders/products/status":{"put":{"tags":["주문"],"summary":"주문 상품 상태 변경","description":"주문 상품의 상태를 일괄 변경합니다.\n\n## 요청 제한\n- 한 번에 최대 100개의 주문 상품을 변경할 수 있습니다\n\n## 발송지연 상태 변경 시 필수 항목\n`status`가 `DELAY_SHIPPING`인 경우 다음 필드가 필수입니다:\n- `shippingDeadlineAt`: 발송 예정 일시 (yyyy-MM-ddTHH:mm:ss 형식)\n  - 오늘 기준 1일 이상 32일 이하로 설정 가능합니다\n- `delayReasonType`: 발송지연 사유\n  - **READY_PRODUCT**: 상품준비중\n  - **CUSTOM_INFO_NOT_ENTER**: 주문제작 정보 미입력\n\n## 응답\n- 일부 상품의 상태 변경이 실패하더라도 성공한 상품은 상태가 변경됩니다\n- `failedCount`가 0보다 크면 `failedReasons`에서 실패 사유를 확인할 수 있습니다","operationId":"changeOrderProductStatus","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeOrderProductStatusBody"}}},"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","COMMON_ERROR"]},"reason":{"type":"string","description":"에러 사유"}},"description":"에러 응답, resultType FAIL 시 제공"},"success":{"$ref":"#/components/schemas/ChangeOrderProductStatusFepResponse"}}}}}}}}}}}
```

> ### API 연동 중 문의사항이나 개선 제안이 있으신가요?

{% hint style="info" %}
토스쇼핑 API 연동에 대한 질문이나, 건의사항이 있다면 [연동/개발 문의](https://discord.gg/xPz6H9NZ3P)에 남겨주세요. 다른 유저의 문의를 참고하거나, 토스쇼핑 담당자와 질의를 주고 받을 수 있어요.
{% endhint %}


---

# Agent Instructions: 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:

```
GET https://shopping-docs.toss.im/dev/api-2/order.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.