クーポン

チェックアウト時に顧客が適用できる割引コードを作成します。パーセント割引または固定金額割引、期限付きまたは上限付き、一回限りまたは繰り返し利用が可能です。

クーポンは、Builder の Commerce パネル > Products > Coupons サブタブ、または SDK の proyecta.commerce.coupons を通じて管理できます。

クーポンの構成要素

フィールド	説明
`code`	チェックアウト時に顧客が入力するプロモコード（例：`LAUNCH20`）
`percent_off` または `amount_off`	相互に排他的です。パーセントは1〜100。金額は最小通貨単位（セント）で指定します。
`currency`	`amount_off` 割引に必要です（3文字のISOコード）。作成時に受け付けられ Stripe に転送されますが、その後はAPIに保存・返却されません。
`duration`	`once`（初回支払いのみ）、`repeating`（`duration_in_months` に対して）、または `forever`
`duration_in_months`	`duration` が `repeating` の場合に必須
`max_redemptions`	全顧客を通じた利用回数の上限
`redeem_by`	クーポンが無効になる有効期限
`name`	顧客に表示される表示名
`active`	削除せずに有効・無効を切り替えるトグル

クーポンの作成

Coupons サブタブで Add coupon をクリックし、各フィールドを入力します。または SDK を使って作成することもできます：

// 20% off forever
await proyecta.commerce.coupons.create({
    code: 'LAUNCH20',
    name: 'Launch discount',
    percent_off: 20,
    duration: 'forever',
});

// $10 off, single use, expires in 30 days
await proyecta.commerce.coupons.create({
    code: 'WELCOME10',
    amount_off: 1000,
    currency: 'USD',
    duration: 'once',
    max_redemptions: 1,
    redeem_by: new Date(Date.now() + 30 * 86400 * 1000).toISOString(),
});

// 50% off for the first 3 months of a subscription
await proyecta.commerce.coupons.create({
    code: 'EARLY3',
    percent_off: 50,
    duration: 'repeating',
    duration_in_months: 3,
});

チェックアウト時にクーポンを適用する

顧客は Stripe がホストするチェックアウトページでクーポンコードを自分で入力できます。プロモコードの入力欄は自動的に表示されます。

await proyecta.commerce.checkout({
    customer_id,
    line_items: [{ variant_id: 'var_pro_monthly' }],
    success_url: 'https://myapp.com/welcome',
});

チェックアウト呼び出し時にクーポンコードをプログラムで渡す機能は、現時点ではサポートされていません。

一覧表示・更新・無効化

// Browse every coupon (only lists coupons created via the SDK)
const { data } = await proyecta.commerce.coupons.list();
for (const coupon of data.data) {
    console.log(coupon.code, coupon.times_redeemed, '/', coupon.max_redemptions);
}
// Paginate using data.has_more and the starting_after query parameter if needed.

// Disable a coupon (without deleting)
await proyecta.commerce.coupons.update({ couponId: 'coupon_123', active: false });

注意： coupons.list() は SDK を通じて作成されたクーポンのみを返します。Builder の Dashboard で作成したクーポンは coupons.list() では表示されません。

注意事項と制限

コードと割引額は変更できません。 表示用の name の更新や active の切り替えは可能ですが、percent_off、amount_off、code 自体は変更できません。異なる条件が必要な場合は、新しいクーポンを作成してください。
times_redeemed は自動でインクリメントされる読み取り専用の値で、キャンペーンのパフォーマンス追跡に役立ちます。
クーポンは注文単位ではなく、顧客単位で適用されます。 クーポンが forever に設定されている場合、顧客がサブスクリプションを契約すると、更新のたびに割引が適用されます。