상품 및 기능

판매할 항목을 정의하세요. 하나 이상의 **변형(variant)**이 있는 상품을 만들고, 권한 기반 접근 제어를 위한 재사용 가능한 **기능(feature)**을 연결하세요.

Proyecta Commerce는 세 가지 개념을 사용합니다: 상품(product), 변형(variant), 기능(feature).

상품(Product) — 판매하는 것 (예: “Pro 플랜”, “티셔츠”, “전략 상담”)
변형(Variant) — 상품의 가격 등급 또는 구성 (예: “Pro 월간 $29”, “Pro 연간 $290”, “티셔츠 – L”)
기능(Feature) — 앱이 런타임에 확인하는 재사용 가능한 권한 키 (예: pro_features, unlimited_projects, api_access)

상품은 여러 변형을 가질 수 있습니다. 또한 상품에는 하나 이상의 리소스가 연결되며, 보통 고객이 구독할 때 접근 권한을 부여하는 기능(feature)이 이에 해당합니다.

판매 항목을 모델링하는 두 가지 방법

Commerce는 플랫폼의 나머지 부분과 함께 구성되므로, “판매하는 것”에는 두 가지 형태가 있으며 Proyecta가 적합한 형태를 자동으로 선택합니다:

Commerce 네이티브 상품 — 구독, 플랜, 일회성 업그레이드, 기능/권한(entitlement). Admin > Commerce > Products에서 직접 정의합니다. 이 페이지의 나머지 내용에서 설명하는 모델입니다.
콘텐츠 기반 스토어 카탈로그 — 비즈니스 오너가 매일 편집하는 사진, 가격, 설명이 포함된 상품. 이는 CMS에서 **판매 가능한 컬렉션(sellable collection)**으로 관리되며, 각 항목 자체가 상품입니다. 항목이 게시되면 Proyecta가 자동으로 이를 Commerce에 실제 구매 가능한 상품으로 연결하여 상품과 가격이 설정된 변형을 생성하고, 콘텐츠 필드의 가격을 그대로 복사합니다. 스토어프론트는 콘텐츠 가격을 렌더링하고 결제 시 연결된 변형으로 청구하며, 단일 소스를 공유하므로 가격이 서로 달라질 수 없습니다. 이 항목들은 Commerce > Products가 아닌, 빌더 또는 게시된 사이트의 앱 Admin에서 콘텐츠로 관리합니다. 콘텐츠 관리를 참고하세요.

카드 결제를 받지 않는 일반 카탈로그 — 탐색 전용 메뉴나 “구매” 버튼이 WhatsApp 주문 링크로 연결되는 스토어 — 는 그냥 일반 콘텐츠, 즉 Commerce 연결이 없는 일반 카탈로그 컬렉션입니다. 카드 결제 기능이 있어야 컬렉션이 _판매 가능_해집니다.

상품 만들기

Admin > Commerce > Products에서 Create product를 클릭하거나 AI에게 요청하세요: "Create a Pro plan at $29/month and a Business plan at $99/month." 각 상품에는 다음이 필요합니다:

표시 이름 (예: “Pro”)
최소 하나의 변형(variant)

변형(Variants)

각 변형은 자체 가격 정보를 갖습니다:

필드	설명
`name`	변형의 표시 레이블 (“Monthly”, “Annual”, “Large”)
`currency`	세 자리 ISO 통화 코드 — USD, EUR, GBP, JPY, BRL, MXN, INR… (130개 이상 지원)
`unit_amount`	최소 통화 단위(센트)로 표시한 가격. `2900` = $29.00
`recurring`	선택 사항 — `{ interval: 'week' \| 'month' \| 'year' }`. 일회성 가격은 생략. 일별 청구는 현재 지원되지 않음.
`is_default`	허용되지만 아직 적용되지 않음 — 기본 변형 선택은 현재 구현되지 않음.
`media`	CDN 파일 ID로 이미지 또는 동영상 첨부 (파일 참고)

가격은 변경할 수 없습니다. 변형이 생성된 후에는 가격을 변경할 수 없으며, 대신 새 변형을 만들어야 합니다. 이는 기존 구독자가 실수로 가격이 변경되는 것을 방지합니다.

기능(Features, 권한)

기능(Feature)은 접근 제어의 기본 단위입니다. Admin > Commerce > Products에서 기능을 한 번 만든 다음 하나 이상의 상품에 연결하세요. 각 기능에는 이름, 선택적 설명, 그리고 앱이 확인하는 키(key) — 소문자, 숫자, 밑줄로 구성 (예: pro_features) — 가 있습니다.

상품을 만들 때 “리소스”를 통해 기능을 연결합니다. 상품을 구독한 고객은 해당 상품에 연결된 모든 기능에 접근할 수 있습니다.

그런 다음 앱에서 해당 키로 접근을 제어하세요:

const { hasAccess, isLoading } = useEntitlement('pro_features');

if (isLoading) return <Spinner />;
if (!hasAccess) return <UpgradePrompt />;
return <ProOnlyThing />;

이 확인은 로그인한 세션을 기반으로 서버 측에서 실행되므로 브라우저에서 위조할 수 없습니다. 전체 패턴은 앱에 Commerce 통합하기를 참고하세요.

참고: 항상 기능의 내부 ID가 아닌 기능 키(key) — 기능 이름에서 파생된 슬러그 (예: pro_features) — 를 기준으로 접근을 제어하세요.

이것이 앱 코드에서 Pro 전용 페이지, API endpoint, 또는 기능의 접근을 제어하는 방법입니다.

일반적인 상품 구성 예시

SaaS 구독

Create products: Free ($0/month), Pro ($29/month, $290/year), Business ($99/month, $990/year).
Attach a 'pro_features' feature to Pro and Business so I can gate access in my code.

실물 상품

Create a T-shirt product with three variants: Small, Medium, Large at $25 each.

디지털 상품

Create a course product with a single one-time variant at $149.

후원금(Donations)

Create a donation product with three variants: $25, $50, $100 — all one-time.

재고 관리

Proyecta Commerce는 현재 실물 상품의 재고를 추적하지 않습니다. 재고가 있는 항목을 판매하는 경우, 앱 데이터베이스에서 재고 수량을 관리하고 결제 흐름에서 이를 확인하세요.

출시 예정

결제 필드 커스터마이징 — 구매자로부터 추가 정보 수집
자율 가격 설정(Pay-what-you-want pricing)
실물 상품을 위한 내장 재고 추적