Return Orders

반품 처리된 품목 목록을 조회합니다.

Endpoint


POST /vendor-api/orders/return

Description

반품 처리된 주문 품목 목록을 날짜 범위로 조회합니다. 인증된 입점사에 해당하는 품목만 반환되며, 브라이트몰 자사제품은 자동으로 제외됩니다. 응답에는 주문 조회 API와 동일한 필드에 반품 관련 추가 필드가 포함됩니다.

Request

Headers

Header	Required	Description
`Content-Type`	O	`application/json`
`X-Vendor-Api-Key`	O	발급받은 API Key
`X-Vendor-Id`	O	입점사 고유 ID

Body Parameters

Field	Type	Required	Description
`start_date`	string	O	조회 시작일 (`YYYY-MM-DD`)
`end_date`	string	O	조회 종료일 (`YYYY-MM-DD`)
`page`	number	-	페이지 번호 (기본값: 1)
`limit`	number	-	페이지당 항목 수 (기본값: 100, 최대: 100)

Request Example


curl -X POST "https://staging-brightmall-backend.certi.life/vendor-api/orders/return" \
  -H "Content-Type: application/json" \
  -H "X-Vendor-Api-Key: bm_xOpGAqgHbJQBXxBBbUIZ_bAGZk4wK2FdLgF50277PU8" \
  -H "X-Vendor-Id: 01KC51ST1WSTAET481SHPH3PSY" \
  -d '{
    "start_date": "2026-01-01",
    "end_date": "2026-01-31"
  }'

Response

Response Example


{
  "request_id": "req_mkp3ret_abc123",
  "timestamp": "2026-01-22T06:50:00.000Z",
  "return_list": [
    {
      "ord_no": "202601220157_000020196",
      "ord_prd_no": "202601220157_000020196_[1]",
      "return_date": "2026-01-25",
      "return_reason": "상품 불량",
 
      "ord_date": "2026-01-22",
      "pay_date": "2026-01-22",
      "hope_deli_sdate": null,
      "item_status": "pending",
 
      "order_tel": "02-1234-5678",
      "order_hp": "010-1234-5678",
      "order_id": "customer@example.com",
      "ord_name": "홍길동",
 
      "recv_name": "김도희",
      "recv_zipcode": "06234",
      "recv_addr1": "서울특별시 강남구 테헤란로 123",
      "recv_addr2": "4층",
      "recv_tel": "02-1234-5678",
      "recv_hp": "010-1234-5678",
 
      "paymethod": "카드",
      "ord_memo": null,
      "ord_price": 150000,
      "in_price": 150000,
      "ship_fee": 3000,
      "afterdeli": false,
 
      "ord_company": "치과의원",
      "ord_company_num": "123-45-67890",
      "ord_taxorgnum": "1234567890",
 
      "partner_code": "SEIL",
      "user_hname": "김영수",
      "user_phone": "010-9876-5432",
      "real_customer_info": null,
 
      "prd_name": "델리킷 Impre Kicker",
      "prd_match": null,
      "prd_code": "SEIL-001",
      "uitem_code": "variant-123",
      "item_name": "델리킷 Impre Kicker / M사이즈",
      "item_cnt": 2,
      "item_price": 75000,
 
      "trade_num": null,
      "trade_date": null
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 100,
    "total": 1,
    "has_more": false
  }
}

Response Fields

주문 조회 API의 응답 필드에 아래 반품 관련 필드가 추가됩니다. 주문 기본 필드에 대한 설명은 List Orders를 참조하세요.

반품 추가 필드

Field	Type	Description
`return_date`	string	반품일 (`YYYY-MM-DD`)
`return_reason`	string	반품 사유

Pagination

Field	Type	Description
`page`	number	현재 페이지 번호
`limit`	number	페이지당 항목 수
`total`	number	전체 항목 수
`has_more`	boolean	다음 페이지 존재 여부

Notes

응답의 목록 키는 return_list입니다 (주문 조회의 order_list와 다름).
반품된 주문에 대한 거래명세서는 settlement_type: "cancellation"으로 조회할 수 있습니다.
조회 결과가 없으면 빈 배열(return_list: [])이 반환됩니다.