商品と機能

販売するものを定義します。バリアントを1つ以上持つ商品を作成し、エンタイトルメントベースのアクセス制御のために再利用可能なフィーチャーを紐付けます。

Proyecta Commerceは3つのコンセプトを使用します：商品（product）、バリアント（variant）、フィーチャー（feature）。

商品（Product） — 販売するもの（例：「Pro プラン」「Tシャツ」「戦略コール」）
バリアント（Variant） — 商品の価格帯または構成（例：「Pro 月額 $29」「Pro 年額 $290」「Tシャツ – L サイズ」）
フィーチャー（Feature） — アプリが実行時にチェックする再利用可能なエンタイトルメントキー（例：pro_features、unlimited_projects、api_access）

1つの商品は複数のバリアントを持てます。また、商品には1つ以上のリソース（通常はフィーチャー）が紐付けられており、顧客がサブスクライブするとアクセス権が付与されます。

商品の作成

Dashboard > Commerce > Products で Create product をクリックするか（または AI に「"Create a Pro plan at $29/month and a Business plan at $99/month."」と依頼してください）、各商品に以下を設定します：

表示名（例：「Pro」）
少なくとも1つのバリアント

バリアント

各バリアントには独自の価格設定があります：

フィールド	備考
`name`	バリアントの表示ラベル（「Monthly」「Annual」「Large」など）
`currency`	ISO 3文字コード — 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 を参照）

価格は変更不可です。 バリアントを作成した後は価格を変更できません。代わりに新しいバリアントを作成してください。これにより、既存のサブスクライバーが誤った価格変更の影響を受けないよう保護されます。

フィーチャー（エンタイトルメント）

フィーチャーはアクセス制御の基本単位です。フィーチャーを一度作成し、1つ以上の商品に紐付けます。

// 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')
});

商品を作成する際、「リソース」を通じてフィーチャーを紐付けます。商品をサブスクライブした顧客は、その商品に紐付けられたすべてのフィーチャーへのアクセス権を得ます。

次に、アプリ内で顧客がアクセス権を持っているかどうかを確認します：

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.

寄付

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

在庫管理

Proyecta Commerce は現在、物理的な商品の在庫追跡に対応していません。在庫のある商品を販売する場合は、アプリのデータベースで在庫数を管理し、チェックアウトフロー内で確認してください。

近日公開予定

チェックアウトフィールドのカスタマイズ — 購入者から追加情報を収集
Pay-what-you-want 価格設定
物理的な商品向けの組み込み在庫追跡