# 주문

## 주문 내역 조회

> 커서 기반 페이지네이션을 사용하여 주문 내역을 조회합니다.\
> \
> \## 조회 조건\
> \- 조회 범위는 최대 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 %}