주문

주문 내역 조회

get

커서 기반 페이지네이션을 사용하여 주문 내역을 조회합니다.

조회 조건

• 조회 범위는 최대 31일까지 조회 가능합니다

• status 파라미터를 생략하면 전체 주문 상태를 조회합니다

• limit은 최소 1, 최대 50까지 설정 가능하며, 범위를 벗어나면 자동으로 50으로 조정됩니다

페이지네이션

• 첫 페이지 조회 시 nextCursor를 생략합니다

• 다음 페이지 조회 시 응답으로 받은 nextCursor 값을 그대로 전달합니다

• 응답의 nextCursor가 null이면 마지막 페이지입니다

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

statusstring · enumOptional

조회용 주문 상품 상태 (생략 시 전체 조회)

Example: PAIDPossible values:

startDatestring · dateRequired

조회 시작일자 (yyyy-MM-dd)

Example: 2025-09-01

endDatestring · dateRequired

조회 종료일자 (yyyy-MM-dd). 조회 범위는 최대 31일

Example: 2025-09-30

nextCursorstringOptional

다음 페이지를 위한 커서 (직전 호출에서 받은 nextCursor를 그대로 전달)

Example: eyJvcmRlclByb2R1Y3RJZCI6MTIzNDV9

limitinteger · int32Optional

페이지 사이즈 (기본값: 20, 최대 50)

Default: 20Example: 20

partnerNamestringOptional

연동 프로그램명 또는 자사 서비스명

Example: 토스쇼핑

Responses

200

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

application/json

resultTypestring · enumOptional

응답 결과 타입

Possible values:

get

/api/v3/shopping-fep/orders/v2

HTTPcURLJavaScriptPython

GET /api/v3/shopping-fep/orders/v2?startDate=2026-02-24&endDate=2026-02-24 HTTP/1.1
Host: shopping-fep.toss.im
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

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

{
  "resultType": "SUCCESS",
  "error": {
    "errorCode": "INVALID_REQUEST",
    "reason": "text"
  },
  "success": {
    "results": [
      {
        "orderedAt": "2026-02-24T21:20:52.728Z",
        "canceledAt": "2026-02-24T21:20:52.728Z",
        "confirmedAt": "2026-02-24T21:20:52.728Z",
        "shippingDeadlineAt": "2024-01-10",
        "orderId": 10001,
        "orderProductId": 20001,
        "productId": 30001,
        "stockId": 40001,
        "ordererName": "홍길동",
        "ordererPhone": "01012345678",
        "ordererRealPhone": "01012345678",
        "receiverName": "김철수",
        "receiverPhone": "01087654321",
        "receiverRealPhone": "01087654321",
        "address": "서울특별시 강남구 테헤란로 123",
        "detailAddress": "토스타워 10층",
        "zipCode": "06234",
        "shippingNote": "문 앞에 놔주세요",
        "productName": "리클라이너",
        "optionName": "색상: 블랙, 사이즈: L",
        "quantity": 2,
        "price": 100000,
        "originPrice": 120000,
        "totalDiscountPrice": 20000,
        "tossShoppingDiscount": 15000,
        "tossPayDiscount": 5000,
        "tossPayPoint": 3000,
        "orderProductStatus": "PAID",
        "deliveryCompanyCode": "CJ대한통운",
        "shippingTrackingNumber": "123456789012",
        "deliveryFeeGroupId": 50001,
        "deliveryFee": 3000,
        "deliveryLocationType": "NORMAL",
        "normalDeliveryFee": 3000,
        "jejuDeliveryFee": 5000,
        "mountainDeliveryFee": 5000,
        "productManagementCode": "PROD-001",
        "productItemManagementCode": "OPT-001"
      }
    ],
    "nextCursor": "eyJvcmRlclByb2R1Y3RJZCI6MTIzNDV9"
  }
}

주문 상품 단건 조회

get

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

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

orderProductIdinteger · int64Required

주문 상품 ID

Example: 12345

Query parameters

partnerNamestringOptional

연동 프로그램명 또는 자사 서비스명

Example: 토스쇼핑

Responses

200

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

application/json

resultTypestring · enumOptional

응답 결과 타입

Possible values:

get

/api/v3/shopping-fep/orders/products/{orderProductId}

HTTPcURLJavaScriptPython

GET /api/v3/shopping-fep/orders/products/{orderProductId} HTTP/1.1
Host: shopping-fep.toss.im
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

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

{
  "resultType": "SUCCESS",
  "error": {
    "errorCode": "INVALID_REQUEST",
    "reason": "text"
  },
  "success": {
    "orderedAt": "2026-02-24T21:20:52.728Z",
    "canceledAt": "2026-02-24T21:20:52.728Z",
    "confirmedAt": "2026-02-24T21:20:52.728Z",
    "shippingDeadlineAt": "2024-01-10",
    "orderId": 10001,
    "orderProductId": 20001,
    "productId": 30001,
    "stockId": 40001,
    "ordererName": "홍길동",
    "ordererPhone": "01112345678",
    "ordererRealPhone": "01012345678",
    "receiverName": "김철수",
    "receiverPhone": "01187654321",
    "receiverRealPhone": "01087654321",
    "address": "서울특별시 강남구 테헤란로 123",
    "detailAddress": "토스타워 10층",
    "zipCode": "06234",
    "shippingNote": "문 앞에 놔주세요",
    "productName": "리클라이너",
    "optionName": "색상: 블랙, 사이즈: L",
    "quantity": 2,
    "price": 100000,
    "originPrice": 120000,
    "totalDiscountPrice": 20000,
    "tossShoppingDiscount": 15000,
    "tossPayDiscount": 5000,
    "tossPayPoint": 3000,
    "orderProductStatus": "PAID",
    "deliveryCompanyCode": "CJ대한통운",
    "shippingTrackingNumber": "123456789012",
    "deliveryFeeGroupId": 50001,
    "deliveryFee": 3000,
    "deliveryLocationType": "NORMAL",
    "normalDeliveryFee": 3000,
    "jejuDeliveryFee": 5000,
    "mountainDeliveryFee": 5000,
    "productManagementCode": "PROD-001",
    "productItemManagementCode": "OPT-001"
  }
}

주문 상품 상태 변경

put

주문 상품의 상태를 일괄 변경합니다.

요청 제한

• 한 번에 최대 100개의 주문 상품을 변경할 수 있습니다

발송지연 상태 변경 시 필수 항목

status가 DELAY_SHIPPING인 경우 다음 필드가 필수입니다:

• shippingDeadlineAt: 발송 예정 일시 (yyyy-MM-ddTHH:mm:ss 형식)

  • 오늘 기준 1일 이상 32일 이하로 설정 가능합니다

• delayReasonType: 발송지연 사유

  • READY_PRODUCT: 상품준비중

  • CUSTOM_INFO_NOT_ENTER: 주문제작 정보 미입력

응답

• 일부 상품의 상태 변경이 실패하더라도 성공한 상품은 상태가 변경됩니다

• failedCount가 0보다 크면 failedReasons에서 실패 사유를 확인할 수 있습니다

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

orderProductIdsinteger · int64[]Required

주문 상품 ID 목록 (최대 100개)

Example: [12345,12346,12347]

statusstring · enumRequired

주문 상품 상태

허용 상태 전이

• 결제완료 → 상품준비중, 발송지연, 결제취소
• 상품준비중 → 발송지연, 결제취소
• 발송지연 → 결제취소
• 배송완료 → 결제취소

주의사항

• 배송중(DELIVERING) 상태로 변경하려면 별도의 배송정보 변경 API를 사용해야 합니다
• 발송지연은 주문 상품당 1회만 설정 가능합니다
• 결제취소, 결제대기, 결제만료 상태의 주문 상품은 상태 변경이 불가능하며 건너뛰어 처리됩니다

Example: PREPARING_PRODUCTPossible values:

shippingDeadlineAtstring · date-timeOptional

발송지연 시각 (yyyy-MM-ddTHH:mm:ss). 발송지연 상태 변경 시 필수

delayReasonTypestring · enumOptional

발송지연 사유. 발송지연 상태 변경 시 필수

Example: READY_PRODUCTPossible values:

partnerNamestringOptional

연동 프로그램명 또는 자사 서비스명

Example: 토스쇼핑

Responses

200

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

application/json

resultTypestring · enumOptional

응답 결과 타입

Possible values:

put

/api/v3/shopping-fep/orders/products/status

HTTPcURLJavaScriptPython

PUT /api/v3/shopping-fep/orders/products/status HTTP/1.1
Host: shopping-fep.toss.im
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 179

{
  "orderProductIds": [
    12345,
    12346,
    12347
  ],
  "status": "PREPARING_PRODUCT",
  "shippingDeadlineAt": "2026-02-24T21:20:52.728Z",
  "delayReasonType": "READY_PRODUCT",
  "partnerName": "토스쇼핑"
}

200

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

{
  "resultType": "SUCCESS",
  "error": {
    "errorCode": "INVALID_REQUEST",
    "reason": "text"
  },
  "success": {
    "totalCount": 10,
    "failedCount": 2,
    "failedReasons": [
      "주문 상품을 찾을 수 없습니다: 12345",
      "허용되지 않은 상태 변경입니다: 12346"
    ]
  }
}

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

토스쇼핑 API 연동에 대한 질문이나, 건의사항이 있다면 연동/개발 문의에 남겨주세요. 다른 유저의 문의를 참고하거나, 토스쇼핑 담당자와 질의를 주고 받을 수 있어요.