상품 및 기능

판매할 항목을 정의하세요. 하나 이상의 **변형(variant)**이 포함된 상품을 만들고, 재사용 가능한 **기능(feature)**을 연결하여 자격 기반 접근 제어를 구현하세요.

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

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

하나의 상품에는 여러 변형이 있을 수 있습니다. 또한 상품에는 하나 이상의 **리소스(resource)**가 연결되며, 일반적으로 기능(feature)이 연결되어 고객이 구독할 때 접근 권한을 부여합니다.

상품 만들기

Dashboard > 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… (SDK는 130개 이상 지원)
unit_amount	가장 작은 통화 단위(센트)의 가격. 2900 = $29.00
recurring	선택 사항 — { interval: 'week' | 'month' | 'year' }. 일회성 가격의 경우 생략. 일별 청구는 현재 지원되지 않습니다.
is_default	허용되지만 아직 적용되지 않음 — 기본 변형 선택은 현재 구현되지 않았습니다.
media	CDN 파일 ID로 이미지 또는 동영상 첨부 (Files 참조)

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

기능(Features, 자격)

기능은 접근 제어의 기본 단위입니다. 기능을 한 번 만들고 하나 이상의 상품에 연결하세요.

// Create a feature
const pro = await proyecta.commerce.features.create({
    name: 'Pro features',
    description: 'Unlocks the Pro tier capabilities',
    // optional custom id — lowercase alphanumeric and underscores only (e.g. 'pro_features')
});

상품을 만들 때 “resources”를 통해 기능을 연결합니다. 상품을 구독한 고객은 해당 상품에 연결된 모든 기능에 접근 권한을 얻습니다.

그런 다음 앱에서 고객의 접근 권한 여부를 확인합니다:

const { has_access } = await proyecta.commerce.check({
    customer_id: 'cus_123',
    resource_id: 'pro_features',
});

참고: resource_id는 기능 키 — 즉 기능 이름에서 파생된 슬러그여야 합니다 (예: pro_features). features.create()가 반환하는 기능 객체의 .id 속성이 아닙니다.

이를 통해 앱 코드에서 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.

후원(Donation)

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

재고 관리

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

출시 예정

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