릴로
개발자 문서사용자 가이드
커스텀몰 API / 주문 쓰기 (v1.1)

커스텀몰 API  /  주문 쓰기

주문 쓰기 (v1.1)

LIA가 상담 중에 취소·반품·교환 접수, 배송지 변경, 주문 메모를 쇼핑몰에 바로 남겨요. capabilities에 켠 것만 호출해요.

승인 뒤에만 호출해요

취소·반품·교환·배송지 변경은 담당자가 승인한 뒤에만 호출해요. 자동 승인은 없고, 기한이 지나면 보류돼요. 주문 메모는 내부 기록이라 승인 없이 남겨요.

공통 규칙

  • 본문은 카페24처럼 { "request": {...} }, 응답은 { "data": {...} }예요. Content-Type: application/json을 써요.
  • 모든 쓰기에 Idempotency-Key 헤더가 붙어요. 같은 키로 다시 오면 다시 실행하지 말고 처음 응답을 그대로 돌려주세요.
  • 본문에 member_id·buyer_cellphone이 오면 그 소유자의 주문인지 확인하고, 아니면 404를 돌려주세요.
  • 본문 requested_by는 "lillo"예요. 쇼핑몰 관리자 화면에 ‘릴로 접수’로 보이게 해 주세요.
  • 8초 안에 응답해 주세요. 오래 걸리면 접수만 하고 202와 현재 상태를 돌려주세요.
  • 접수 알림 문자·메일은 쇼핑몰 정책대로 보내요. 릴로는 고객에게 따로 보내지 않고 상담에서 안내해요.

취소 접수

POST/v1/orders/{order_id}/cancellation

본문 (request)

claim_reason_typestring필수

카페24 코드 — A 고객 변심, B 배송 지연, J 상품 불량·오배송, K 기타. 모르면 A

requested_bystring필수

"lillo"

claim_reasonstring선택

사유 문장

itemsobject[]선택

order_item_code, quantity. 빼면 주문 전체

member_id / buyer_cellphonestring선택

소유자 확인용. 없으면 관리자 권한으로 처리해요

요청
curl -X POST "https://api.mall.example.com/v1/orders/20261110-0001234/cancellation" \
  -H "Authorization: Bearer $LILLO_API_KEY" \
  -H "X-Lillo-Api-Version: 2026-11-01" \
  -H "Idempotency-Key: 6f1c2a9e-4b7d-4f0e-9a51-3d2c8e7b1a04" \
  -H "Content-Type: application/json" \
  -d '{
    "request": {
      "member_id": "m_1001",
      "claim_reason_type": "A",
      "claim_reason": "Changed mind",
      "items": [{ "order_item_code": "20261110-0001234-01", "quantity": 1 }],
      "requested_by": "lillo"
    }
  }'
응답 — 201 Created
{
  "data": {
    "order_id": "20261110-0001234",
    "claim_type": "cancel",
    "claim_code": "C-20261112-0001",
    "items": [
      { "order_item_code": "20261110-0001234-01", "order_status": "C00" }
    ]
  }
}

응답 품목 order_status는 접수 뒤 상태예요(C00/C10, 바로 끝냈다면 C40). 출고 전이 아니면 409 not_allowed_in_state를 돌려주세요.

오류 응답 — 409
{
  "error": {
    "code": "not_allowed_in_state",
    "message": "Already shipped",
    "order_status": "N30"
  }
}

반품 접수

POST/v1/orders/{order_id}/return

본문은 취소와 같고, 아래 필드를 더할 수 있어요. 응답 품목 상태는 R00/R10이에요.

statusstring선택

accepted 또는 processing — 카페24와 같아요

pickupobject선택

수거지 name, cellphone, zipcode, address1, address2. 없으면 주문 배송지

교환 접수

POST/v1/orders/{order_id}/exchange

본문은 취소와 같고, 바꿀 옵션을 exchange_items로 보내요. 없으면 같은 옵션으로 교환(불량 교환)해요. 응답 품목 상태는 E00/E10, 옵션이 품절이면 409 out_of_stock이에요.

본문 — exchange_items
"exchange_items": [
  { "order_item_code": "20261110-0001234-01",
    "variant_code": "P000000X000B", "quantity": 1 }
]

배송지 변경

PUT/v1/orders/{order_id}/receivers

zipcodestring필수

우편번호

address1string필수

기본 주소

address2string선택

상세 주소

namestring선택

받는 분

cellphonestring선택

휴대폰 (숫자만)

shipping_messagestring선택

배송 메시지

member_idstring선택

소유자 확인용

바꿀 값만 보내요. 응답은 { "data": { "order_id", "receivers": [...] } }이고, 이름·연락처는 마스킹해 주세요.

요청
curl -X PUT "https://api.mall.example.com/v1/orders/20261110-0001234/receivers" \
  -H "Authorization: Bearer $LILLO_API_KEY" \
  -H "X-Lillo-Api-Version: 2026-11-01" \
  -H "Idempotency-Key: 6f1c2a9e-4b7d-4f0e-9a51-3d2c8e7b1a04" \
  -H "Content-Type: application/json" \
  -d '{
    "request": {
      "member_id": "m_1001",
      "zipcode": "06236",
      "address1": "123 Teheran-ro, Gangnam-gu, Seoul",
      "address2": "5F",
      "shipping_message": "Leave at the door"
    }
  }'

주문 메모

POST/v1/orders/{order_id}/memos

memostring필수

메모 내용. 최대 2000자

authorstring필수

작성자 (예: "LIA")

starred_memostring선택

"T"/"F"

fixedstring선택

"T"/"F"

메모는 쇼핑몰 관리자만 봐요. 응답은 { "data": { "memo_no", "order_id" } }예요.

요청
curl -X POST "https://api.mall.example.com/v1/orders/20261110-0001234/memos" \
  -H "Authorization: Bearer $LILLO_API_KEY" \
  -H "X-Lillo-Api-Version: 2026-11-01" \
  -H "Idempotency-Key: 6f1c2a9e-4b7d-4f0e-9a51-3d2c8e7b1a04" \
  -H "Content-Type: application/json" \
  -d '{
    "request": {
      "memo": "Customer asked for morning delivery on 11/14",
      "starred_memo": "F",
      "fixed": "F",
      "author": "LIA"
    }
  }'
이전상품·카탈로그다음쿠폰
주문 쓰기 (v1.1) · 개발자 문서 | 릴로