커머스 운영

워크스페이스가 상품을 판매하거나, 고객을 관리하거나, 출시 후 주문을 지원해야 할 때 이 페이지를 사용합니다.

커머스 설정

운영 소유권

상품 편집 권한

tenant-admin과 tenant-editor는 활성 워크스페이스의 상품을 생성하고 문구·가격·옵션·품목을 수정할 수 있습니다. tenant-viewer는 변경 내용을 저장할 수 없으며, 상품 삭제에는 tenant-admin 또는 플랫폼 super-admin이 필요합니다. 상품 편집 권한은 해당 워크스페이스에만 적용됩니다.

읽기 전용 품목 상세 화면에서는 기존 옵션값을 확인할 수 있지만 선택하거나 해제할 수 없습니다.

Admin Panel에서 상품의 일부 변경 사항을 저장할 때 저장 요청은 선택한 워크스페이스에서 상품을 찾을 수 없으면 404 not_found를 반환합니다. 해당 상품에 속하지 않는 품목 ID로 수정하거나 삭제하면 400 bad_request를 반환합니다. 일시적인 서버 오류가 아니므로 워크스페이스·상품·품목 ID를 확인한 뒤 다시 요청하세요.

고객 그룹별 구매 자격

Customers 기능을 켠 워크스페이스에서는 상품의 조직 및 판매 설정 → 구매 가능 고객 그룹을 지정할 수 있습니다. 비워두면 누구나 구매할 수 있고, 설정하면 현재 그룹 중 하나에 속한 로그인 고객만 상품을 장바구니에 추가하거나 수량을 늘리고 Checkout을 만들 수 있습니다. 수량 감소와 삭제는 가능합니다. 그룹 할인과 별개이며 목록·상세 노출을 바꾸지 않습니다. unlisted만으로 구매가 제한되지는 않습니다.

Checkout 생성 때 자격을 최종 확인합니다. 그 전에 멤버십이 만료되거나 그룹 자격이 철회되면 구매를 거부합니다. 이미 생성한 Checkout은 이후 변경에도 결제를 진행할 수 있습니다. 회원 선공개 판매를 전체 공개로 전환하려면 그룹 설정을 비우세요.

서버 대리 구매도 고객에게 연결된 Cart가 필요하며, Secret Key와 그 고객의 customerToken 위임을 함께 전달해야 합니다. 서버 키나 body의 고객 ID만으로는 자격이 증명되지 않습니다. 거부 reason은 product_not_eligible입니다. 이 설정은 구매자 Cart/Checkout 경로에 적용되며, 운영자의 직접 주문·DraftOrder 확정·주문 수정은 기존 운영 권한을 따릅니다.

고객별 누적 구매 한도

상품의 조직 및 판매 설정 → 고객별 누적 구매 한도(maxQuantityPerCustomer)에 양의 정수를 설정합니다. Customers 기능과 검증된 로그인 고객이 필요하며, 미설정은 기존 동작을 유지합니다. 모든 옵션의 확정 주문 수량과 진행 중 Checkout 수량을 합산하고 Checkout 생성 시 동시 구매까지 최종 판정합니다. 초과는 409 purchase_limit_exceeded이며 details에 productId, maxQuantityPerCustomer, remainingQuantity가 포함됩니다. 게스트는 403 product_not_eligible입니다.

취소·미결제 만료는 전체 수량을, 완료된 반환은 반환 수량만 복구합니다. 금액만 환불하거나 반환이 미완료이면 복구하지 않습니다. 결제 결과가 미확정이면 TTL이 지나도 계속 집계합니다. 운영자의 직접 주문·DraftOrder 확정·수량 증가는 감사 기록을 남기는 예외이며 이후 집계에는 포함됩니다. 늦은 결제 성공이나 동시 운영자 예외 주문으로 한도가 초과될 수 있습니다.

입장권도 상품 기준으로 합산하므로 같은 상품의 옵션을 공유하는 모든 회차·입장 유형에 걸립니다. 회차별 1인 N매 제한은 아닙니다. 서버 대리 구매는 Secret Key와 같은 고객의 customerToken 위임이 필요합니다.

회차 취소 환불만으로는 구매 한도가 복구되지 않습니다. 전체 환불 주문과 반환 시점에 배송 완료도 구매확정도 되지 않은 부분 환불 주문에는 취소·반환으로 한도를 해제하는 경로가 없습니다. 반환 시점에 배송 완료나 구매확정된 부분 환불 주문은 남은 환불 가능 금액 안에서 양수 환불을 동반해 반환을 완료하면 반환 수량만 복구됩니다. 0원 환불로 반환을 완료할 수는 없습니다. 한도 복구가 필요하면 운영자는 한도를 상향하거나 별도 상품을 사용할 수 있습니다. 전용 한도 해제 기능은 후속 작업입니다.

상품 저장 중 추가 편집

상품을 저장하는 동안 옵션이나 품목을 다시 편집하면 추가 변경 내용은 화면에 미저장 상태로 남습니다. 저장된 상품 열기를 누르기 전에 변경 내용을 기록한 뒤, 저장된 상품을 확인하고 다시 적용하세요. 최신 상품 확인이 필요한 동안에는 저장이 차단됩니다. 저장 중 추가 편집이 없으면 정상적으로 저장을 완료합니다.

상품 목록 갱신 경고

상품은 저장되었지만 목록 갱신을 확인하지 못했다는 경고가 표시되면 상품 변경 내용은 저장된 상태입니다. 상품 목록의 가격이나 판매 가능 여부에는 이전 값이 남아 있을 수 있습니다. 저장된 상품을 확인하고 목록이 계속 잘못 표시되면 카탈로그 담당자에게 문의하세요. 상품을 다시 만들 필요는 없습니다. 편집기를 새로 불러오는 것만으로 목록 갱신이 확인되지는 않습니다.

주문 일괄 취소

일괄 취소 요청이 실패하거나 취소에 성공한 주문 없이 실패 결과가 반환되면 확인 창에서 입력한 사유와 오류를 유지합니다. 오류를 확인한 뒤 직접 재시도하세요. 한 건 이상 취소에 성공하면 일부 실패가 포함돼도 확인 창을 닫고 목록을 갱신합니다. 성공·건너뜀·실패 요약을 확인한 뒤 남은 주문을 다시 선택하세요.

상품별 주문 내역

Admin Panel에서 저장된 상품 또는 variant 상세의 주문 내역을 열면 현재 워크스페이스의 주문 항목을 조회할 수 있습니다. tenant-admin, tenant-editor, tenant-viewer가 사용할 수 있으며, 상품 화면은 해당 상품의 모든 variant를, variant 화면은 해당 품목만 조회합니다. 주문 번호를 누르면 주문 상세로 이동합니다.

기본 기간은 워크스페이스 시간대의 오늘을 포함한 최근 30일입니다. 시작일과 종료일을 정해 조회하면 주문 배치일(placedAt)이 시작일 0시 이상, 종료일 다음 날 0시 미만인 항목을 표시합니다. 지원 연도는 0101–9998년이며 화면과 서버에서 같은 범위를 검증합니다. 주문 생성일은 별도 열입니다. 테스트·삭제·미배치 주문과 삭제된 주문 항목은 제외하며, 취소·환불된 주문의 원래 구매 스냅샷은 포함합니다.

주문 시 고객명, 품목·SKU·옵션, 구매 수량, 할인 전·후 라인 금액을 확인할 수 있습니다. 주문 상태에는 배송 여부를 단정하지 않는 공통 처리 문구를 사용하며, 조회된 상품 일부 행으로 혼합 주문 전체의 배송 여부를 추정하지 않습니다. 금액은 저장된 totalPrice와 discountedTotalPrice 그대로이며, 레거시 할인 후 스냅샷의 기본값 0도 재계산하지 않습니다. 통화는 항목 스냅샷을 사용하고 누락 시 부모 주문 통화를 사용합니다. 확인되지 않거나 서로 모순되는 통화는 ?로 표시하고 금액 합계에서 제외합니다. 누락된 금액은 —로 표시하며 해당 통화의 금액 합계도 제공하지 않습니다.

최근 생성된 일치 항목 최대 500개를 25개씩 표시합니다. 주문 수·구매 수량·통화별 금액 요약은 불러온 항목만 대상으로 하며, 500개를 넘으면 부분 결과 안내가 표시됩니다. 기간을 좁혀 조회하세요. 통화 환산·혼합 통화 합계는 제공하지 않으며, 할인 후 금액은 환불·반품·주문 수정·배송비를 반영한 순매출이나 회계 지표가 아닙니다.

배송 상품과 비배송 상품

실물 variant는 requiresShipping을 켜 두어 결제 완료 주문에서 택배 fulfillment 작업이 생성되도록 합니다. 디지털 상품, 원격 클래스, 서비스처럼 배송이 없는 variant는 shipping을 끌 수 있습니다. 이런 라인은 배송 주소나 배송비가 필요 없고, 택배사 파일 내보내기·가져오기와 송장 등록 상품 선택에서 제외됩니다.

스토어프론트 cart 응답은 각 라인의 배송 필요 여부를 포함하므로 checkout이 cart 내용에 맞게 동작합니다. 비배송 상품만 담긴 cart는 배송 주소 단계와 배송 요약 라인을 건너뛰고, 혼합 cart는 실물 라인 배송을 위해 계속 배송 주소를 수집합니다.

혼합 주문은 두 경로를 분리합니다. 실물 라인은 fulfillment order와 운송장 흐름으로 처리하고, 비배송 접근 권한이나 서비스 라인은 수동 완료 흐름으로 정리합니다. 환불과 반품 처리에서는 실물 배송과 디지털/서비스 제공을 구분해, 최초 배송비 환불이나 반품 배송비가 실제 배송이 있는 경우에만 적용되도록 합니다.

부분 배송 후에도 진행 중인 출고 작업에 남은 실물 수량이 있으면 주문 상세의 남은 수량 배송에서 이어서 출고할 수 있습니다. 주문 목록의 내보내기도 해당 잔량만 포함합니다. 여러 출고 작업에 같은 상품이 나뉘어 파일 가져오기로 잔량을 안전하게 지정할 수 없으면 해당 행에 상세 화면에서 처리하라는 안내가 표시됩니다. 이미 완료·보류·취소된 출고 작업은 다시 열지 않으며, 추가 출고 전 현재 주문 상태와 남은 수량을 확인하세요.

반품 요청

커머스 설정의 반품 정책 탭에서 주문 배송비 환불 방식을 전체 주문 반품 시로 선택하면 대상 사유가 표시됩니다. 수동 조정 메모 필수는 수동 조정 허용을 켰을 때 표시됩니다. 환불 방식을 선택 해제하면 기본값인 전체 주문 반품 시로 처리되므로 대상 사유가 계속 표시됩니다. 상위 설정을 바꿔 숨긴 값은 저장 후에도 보존되며, 다시 켜면 이전 값이 나타납니다.

콘솔에서는 배송 완료 또는 구매 확정 주문에서 반품 요청을 생성합니다. 운영자는 반품할 라인을 명시적으로 선택하고, 주문 수량, 이미 반품된 수량, 남은 반품 가능 수량을 확인한 뒤 라인별 재입고 수수료와 반품 배송비를 입력하고 환불 금액 breakdown을 확인합니다.

반품 요청에는 선택한 라인 수량, returnShippingFee, restockingFee, initialShippingRefundAmount, refundAmount가 저장됩니다. initialShippingRefundAmount는 고객에게 환불하는 최초 주문 배송비입니다. returnShippingFee는 고객에게 차감 청구하는 반품 배송비입니다. 순 환불액은 다음과 같습니다.

refundAmount = sum(lineRefund) + initialShippingRefundAmount - sum(restockingFee) - returnShippingFee

최초 배송비 환불 제안은 주문 생성 시점에 저장된 반품 배송비 환불 정책 스냅샷을 사용합니다. 거절되지 않은 반품들의 누적 initialShippingRefundAmount는 주문의 배송비 금액을 넘을 수 없습니다. 해당 스냅샷이 없는 레거시 주문은 주문 배송비를 수동 상한으로만 사용하며, 양수의 최초 배송비 환불에는 감사 노트가 필요합니다.

수동 주문 (주문 초안)

전화 주문, B2B·수동 판매, 고객 지원 재주문, 견적-후-확정처럼 스토어프론트 체크아웃을 거치지 않는 판매는 주문 초안으로 처리합니다. 운영자는 콘솔에서 초안을 만들어 라인 상품, 고객 또는 고객 스냅샷, 배송지, 할인 코드, 배송비, 운영자·고객 메모를 담고, 확정 전까지 자유롭게 수정하거나 폐기할 수 있습니다.

컴포저의 고객 이메일 필드에서 초안의 이메일을 직접 저장할 수 있습니다. 이메일만 갱신하므로 서버의 최신 고객명과 전화번호를 보존하며, 이메일이 비어 있거나 유효하지 않거나 저장되지 않은 변경이 있거나 저장 중이면 주문 완료 버튼이 비활성화됩니다. 저장 응답에서 이메일을 확인한 뒤에만 다시 활성화됩니다. 저장에 실패하면 입력값과 포커스를 유지한 채 재시도할 수 있고, 완료 시 이메일 관련 거절은 표시된 합계를 무효화하지 않고 이메일 필드에서 안내합니다. 완료 미리보기와 확인 중에는 이메일 입력과 저장이 잠기며, 완료·확정·폐기된 초안의 이메일은 포커스와 선택·복사가 가능한 읽기 전용으로 표시됩니다.

초안은 재고를 예약하지 않으며, 확정 전에는 어떤 주문 원장 행(주문, 결제, 재고 예약, fulfillment)도 만들지 않습니다. POST /api/draft-orders/:id/calculate는 부수효과 없이 서버가 산출한 합계(소계·할인·배송비·총액)를 미리보기로 돌려주고, 품절·판매 불가 variant나 무효 할인 코드를 확정 전에 알려줍니다.

POST /api/draft-orders/:id/finalize는 초안을 실제 주문으로 전환합니다. 이때 가격, 할인, 워크스페이스 검증, 멱등성, 라이프사이클 기본값은 스토어프론트 주문과 동일한 서버 주문 생성 경로를 그대로 사용하며, 생성된 주문은 source = manual로 기록됩니다. 0원 초안은 기존 무료 주문 자동 결제완료 경로를 따르고, 그 외에는 후속 처리를 위한 수동 대기(pending) 주문이 만들어집니다. 고객 이메일이 없거나 유효하지 않으면 확정이 명확한 오류로 거절되고 초안은 계속 편집할 수 있습니다.

v1 범위는 서버 가격이 적용된 카탈로그 상품과 기존 할인 코드까지입니다. 수동·커스텀 라인 단가는 없고, 통화는 KRW로 고정이며, 확정 시 결제·인보이스 링크 발송은 포함하지 않습니다(후속 단계). 초안 상태는 draft → finalized(생성된 주문과 연결) 또는 discarded이며, 확정·폐기된 초안은 더 이상 수정할 수 없습니다.

내 주문 보기

Admin Panel 주문 목록의 내 주문 보기에서 현재 필터와 컬럼 순서·표시 여부를 이름으로 저장합니다. 보기는 선택한 워크스페이스에서 본인 계정만 사용할 수 있습니다. 저장된 보기를 선택하고 적용을 누르세요. 재접속하거나 워크스페이스를 바꿔도 보기가 자동 적용되지는 않습니다.

목록은 워크스페이스별 본인 보기 중 이름·ID 순서의 첫 1,000개까지 표시합니다. 생성 개수 제한은 없으며, 1,000개를 넘겨 저장한 보기는 해당 정렬 순서에서 첫 1,000개에 포함되지 않으면 목록에 표시되지 않습니다.

이름은 앞뒤 공백을 제외한 1–80자이며 대소문자를 구분합니다. 같은 이름은 중복 저장할 수 없습니다. tenant-admin과 tenant-editor는 본인의 보기를 저장·이름 변경·삭제할 수 있습니다. tenant-viewer는 주문 읽기 권한이 있는 동안 기존 본인 보기를 적용할 수 있습니다.

적용하면 1페이지로 이동하며 현재 정렬·검색어·페이지 크기는 유지합니다. 컬럼은 기존의 계정별 목록 환경설정을 계속 사용합니다. 적용 후 필터·컬럼을 바꿔도 저장된 보기는 수정되지 않으므로 새 보기로 명시적으로 저장하세요. 보기를 삭제해도 현재 목록은 바뀌지 않습니다. 더 이상 적용할 수 없는 보기는 삭제하고 현재 조건을 다시 저장하세요. 워크스페이스 접근 권한이나 이커머스 사용 권한이 회수되면 보기를 사용할 수 없습니다.

출시 체크리스트

• ecommerce가 현재 플랜에서 유효합니다
• 판매 준비가 된 상품이 하나 이상 있습니다
• 배송과 할인 소유권이 명확합니다
• 고객 지원팀이 계정과 주문 질문을 소유합니다
• 고객 공개 전에 결제와 웹훅 책임이 배정되었습니다

커머스 헬퍼 (SDK)

이 절은 기술 담당자에게 구현을 인계하는 입구입니다. 일상 카탈로그·주문·배송·반품·주문 초안 절차는 위에서 확인합니다. Ecommerce P0 작업 가이드는 앱의 대표 구매 흐름을 구현하며, 완료한 뒤에도 운영·출시 체크리스트를 별도로 확인해야 합니다.

SDK README에서 Cart·Checkout·PaymentSession·상품·할인/배송·React 헬퍼의 상세 사용법을 찾을 수 있습니다. 구현 호출을 복사하기 전에 설치한 패키지 버전을 확인합니다. 아래 참조는 작업별 맥락을 보완합니다.

상품 미디어는 순서가 있습니다. 첫 번째 상품 이미지가 목록 카드와 상품 상세 기본 상태의 대표 이미지로 사용됩니다.

기술 담당자는 서버 자격 증명과 결제사 검증을 신뢰된 서버에 둡니다. 공개 카탈로그 응답은 원시 재고 수량을 제외하며, 서버 상품 상세는 신뢰 경계가 다릅니다. 브라우저 redirect나 SDK 결제 결과는 권위 있는 검증을 시작하는 신호이며 결제 확정 증거가 아닙니다. 결과가 불명확한 결제·환불은 재시도 전에 대조·확인이 필요합니다. 구현을 인계하기 전에 전문 참조를 검토합니다.

다음 액션

• 연동과 키 관리에서 자격 증명과 웹훅을 점검합니다.
• 출시 준비 점검에서 커머스 blocker를 확인합니다.
• 고객 계정이나 커뮤니티 흐름을 추가하기 전에는 기능 계획으로 돌아갑니다.