Update Status

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

Endpoint


POST /vendor-api/orders/status

Description

주문 품목의 상태를 변경합니다. 배송완료(delivered) 처리 시 공급가를 함께 입력할 수 있습니다. 한 번에 최대 100건까지 일괄 처리할 수 있으며, 인증된 입점사의 품목만 상태 변경이 가능합니다.

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
`updates`	array	O	상태변경 항목 배열 (최대 100건)
`updates[].ord_prd_no`	string	O	주문품목번호 (세트 구성품은 `{주문품목번호}^s{n}` — 같은 품목 구성품은 `status` 가 같아야 함)
`updates[].status`	string	O	변경할 상태 (`preparing`, `shipped`, `delivered`)
`updates[].memo`	string	-	메모
`updates[].supply_price`	object	-	공급가 정보

supply_price 객체

Field	Type	Required	Description
`unit_price`	number	O	몰 판매단위 1개당 공급가 (0 이상)
`quantity`	number	O	몰 주문 수량 (1 이상, 정수, 몰 판매단위)
`total_amount`	number	O	총 공급가 (`unit_price x quantity`)

Request Example


curl -X POST "https://staging-brightmall-backend.certi.life/vendor-api/orders/status" \
  -H "Content-Type: application/json" \
  -H "X-Vendor-Api-Key: <발급받은 API 키>" \
  -H "X-Vendor-Id: 01KC51ST1WSTAET481SHPH3PSY" \
  -d '{
    "updates": [
      {
        "ord_prd_no": "202601220157_000020196_[1]",
        "status": "delivered",
        "supply_price": {
          "unit_price": 75000,
          "quantity": 2,
          "total_amount": 150000
        }
      }
    ]
  }'

Response

Response Example


{
  "request_id": "req_mkp3sts_abc123",
  "timestamp": "2026-01-22T10:00:00.000Z",
  "success_count": 1,
  "failure_count": 0,
  "results": [
    {
      "ord_prd_no": "202601220157_000020196_[1]",
      "success": true,
      "previous_status": "shipped",
      "new_status": "delivered",
      "message": "Status updated to delivered",
      "supply_price": {
        "unit_price": 75000,
        "quantity": 2,
        "total_amount": 150000
      }
    }
  ]
}

Response Fields

최상위 필드

Field	Type	Description
`request_id`	string	요청 추적 ID
`timestamp`	string	응답 시간 (ISO 8601)
`success_count`	number	성공 건수
`failure_count`	number	실패 건수

results[] 항목

Field	Type	Description
`ord_prd_no`	string	주문품목번호
`success`	boolean	처리 성공 여부
`previous_status`	string	변경 전 상태
`new_status`	string	변경 후 상태
`message`	string	처리 결과 메시지
`supply_price`	object\|null	공급가 정보 (delivered 일 때 — 몰 주문 수량 x 단가 기준)
`base_ord_prd_no`	string	(v1.9.0) 세트 구성품 번호로 보낸 경우 몰 주문품목번호
`quantity_mismatch`	object	(v1.9.0) `supply_price.quantity` 가 몰 주문 수량과 다를 때 `{ expected, received }` — 거절 아님

supply_price 응답 필드

Field	Type	Description
`unit_price`	number	공급 단가
`quantity`	number	수량
`total_amount`	number	총 공급가

Status Values

변경 가능한 상태값과 의미는 다음과 같습니다.

Status	Description
`preparing`	배송 준비 중
`shipped`	배송 중 (발송 완료)
`delivered`	배송 완료

Notes

일괄 처리 시 일부 항목이 실패하면 HTTP 207 (Partial Success)이 반환됩니다. success_count와 failure_count를 확인하세요.
타 입점사 품목이나 자사제품의 상태를 변경하려고 하면 UNAUTHORIZED 에러가 반환됩니다.
supply_price는 delivered 상태 변경 시 함께 입력할 수 있습니다. 메타데이터만 갱신하며 정산은 배송 등록/수정 시점에 생성됩니다.
total_amount는 unit_price x quantity와 같아야 합니다(다르면 INVALID_SUPPLY_PRICE). quantity 가 몰 주문 수량과 다른 것은 거절하지 않고 기록합니다(quantity_mismatch).
(v1.9.0) 세트 구성품 번호로 보낸 supply_price 는 검토용 기록만 하고 품목 공급가는 바꾸지 않습니다.
공급가 변경 이력은 시스템에서 자동으로 추적됩니다 (최대 10건).

공급가 입력 가능 시점

상태 변경 API 외에도 다음 API에서 공급가를 입력할 수 있습니다.

API	Endpoint	Description
재고 확인	`POST /vendor-api/inventory/confirm`	사전 등록 (권장)
배송 등록	`POST /vendor-api/shipment`	송장과 동시 등록
배송 수정	`PUT /vendor-api/shipment`	나중에 입력/수정
상태 변경	`POST /vendor-api/orders/status`	배송완료 처리와 동시 등록