メインコンテンツへスキップ

割引

PaymentKitは、クーポンとプロモーションコードを使用した柔軟な割引システムを提供します。これにより、パーセンテージ割引、定額割引、期間限定オファーなど、さまざまな種類の割引を顧客に提供できます。

  • クーポン: 割引率や割引額、期間（例：1回限り、無期限、繰り返し）、最大総利用回数などの基本的な割引ルールを定義します。
  • プロモーションコード: これらはクーポンにリンクされた顧客向けのコードです。個別の利用回数制限、有効期限、制限（例：初回顧客のみ）など、独自のルールを設定できます。

クーポンは割引のテンプレートと考えることができ、プロモーションコードは顧客が使用できるその割引の具体的なインスタンスと考えることができます。

利用可能なすべてのAPI操作の詳細については、クーポンAPIリファレンスおよびプロモーションコードAPIリファレンスを参照してください。

割引の仕組み

次の図は、クーポン、プロモーションコード、および取引中のそれらの適用の関係を示しています。

Discounts

クーポンの作成

Couponオブジェクトには、割引がパーセンテージか定額かなどの割引情報が含まれています。クーポンを作成し、それにプロモーションコードを添付することができます。

プロモーションコード付きのクーポンを作成する

1回のAPI呼び出しで、クーポンと1つ以上の関連プロモーションコードを作成できます。これは、新しいキャンペーンを迅速に設定するのに役立ちます。

Create Coupon with Promo Code

javascript
import payment from '@blocklet/payment-js';

async function createDiscountCampaign() {
  try {
    const result = await payment.coupons.create({
      name: 'New User Discount',
      percent_off: 20,
      duration: 'once',
      max_redemptions: 1000, // クーポン自体の最大利用回数
      promotion_codes: [
        {
          code: 'WELCOME20',
          description: 'Welcome discount for new users',
          max_redemptions: 100, // この特定のコードの最大利用回数
          expires_at: Math.floor(Date.now() / 1000) + (30 * 24 * 60 * 60) // 今から30日後
        }
      ]
    });

    console.log('クーポンが作成されました:', result.coupon);
    console.log('プロモーションコードが作成されました:', result.promotion_codes);
  } catch (error) {
    console.error('クーポンの作成中にエラーが発生しました:', error.message);
  }
}

createDiscountCampaign();

パラメーター

  • name string (required) — クーポンの名前、内部表示用。
  • percent_off number — 小計から割引されるパーセンテージ（0～100）。amount_offが設定されている場合は提供してはなりません。
  • amount_off string — 小計から割引される固定額。percent_offが設定されている場合は提供してはなりません。
  • currency_id string — amount_offが設定されている場合に必須。固定額割引の通貨ID。
  • duration string (required) — 割引が適用される期間を記述します。once、forever、またはrepeatingが可能です。
  • duration_in_months number — durationがrepeatingの場合、クーポンが適用される月数。
  • max_redemptions number — クーポンが利用できる最大回数。
  • redeem_by number — クーポンの有効期限を指定するUnixタイムスタンプ。
  • promotion_codes array — このクーポンに作成して添付するプロモーションコードオブジェクトの配列。
    • code string — 顧客向けのコード。省略された場合、ランダムなコードが生成されます。
    • max_redemptions number — この特定のプロモーションコードが使用できる最大回数。
    • expires_at number — このプロモーションコードが失効するUnixタイムスタンプ。
    • description string — プロモーションコードのオプションの説明。
  • metadata object — 追加情報を保存するための一連のキーと値のペア。

プロモーションコードの作成

クーポンと一緒にプロモーションコードを作成することもできますが、別々に作成して既存のクーポンに添付することもできます。これは、単一のキャンペーンに対して複数のユニークなコードを生成するのに役立ちます。

スタンドアロンのプロモーションコードを作成する

Create Promotion Code

javascript
import payment from '@blocklet/payment-js';

async function createPromoCode(couponId) {
  try {
    const promotionCode = await payment.promotionCodes.create({
      coupon_id: couponId, // 既存のクーポンのID
      code: 'SAVE15NOW',
      description: 'Save 15% on your next purchase',
      max_redemptions: 500,
      restrictions: {
        first_time_transaction: true, // 新規顧客のみ
      }
    });
    console.log('プロモーションコードが作成されました:', promotionCode);
  } catch (error) {
    console.error('プロモーションコードの作成中にエラーが発生しました:', error.message);
  }
}

createPromoCode('coupon_xxx'); // 実際のクーポンIDに置き換えてください

パラメーター

  • coupon_id string (required) — このプロモーションコードを添付するクーポンのID。
  • code string — 顧客向けのコード。省略された場合、ランダムなコードが生成されます。
  • active boolean (default: true) — プロモーションコードが現在有効かどうか。
  • max_redemptions number — この特定のプロモーションコードが使用できる最大回数。
  • expires_at number — このプロモーションコードが失効するUnixタイムスタンプ。
  • restrictions object — このプロモーションコードに制限を適用します。
    • first_time_transaction boolean — trueの場合、プロモーションコードは支払い履歴のない顧客のみが利用できます。
    • minimum_amount number — コードを使用するために必要な最低取引額。
    • minimum_amount_currency string — 最低額の通貨。
  • metadata object — 追加情報を保存するための一連のキーと値のペア。

チェックアウト時の割引適用

顧客がチェックアウトページでプロモーションコードを入力できるようにするには、チェックアウトセッションまたは支払いリンクを作成する際に、このオプションを明示的に有効にする必要があります。

チェックアウトセッションで有効にする

チェックアウトセッションを作成する際に、allow_promotion_codesパラメータをtrueに設定します。これにより、顧客がコードを入力するためのフィールドが支払いページに追加されます。

Enable Promotion Codes

javascript
import payment from '@blocklet/payment-js';

async function createCheckoutWithDiscounts() {
  try {
    const session = await payment.checkout.sessions.create({
      success_url: 'https://example.com/success',
      cancel_url: 'https://example.com/cancel',
      mode: 'payment',
      line_items: [
        { price_id: 'price_xxx', quantity: 1 }
      ],
      allow_promotion_codes: true // これによりプロモーションコードフィールドが有効になります
    });
    console.log('プロモーションコードが有効なチェックアウトセッションが作成されました:', session.url);
  } catch (error) {
    console.error('チェックアウトセッションの作成中にエラーが発生しました:', error.message);
  }
}

createCheckoutWithDiscounts();

支払いリンクで有効にする

再利用可能な支払いリンクにも同じロジックが適用されます。allow_promotion_codesをtrueに設定すると、そのリンクを使用する誰もが有効なプロモーションコードを適用できるようになります。

Enable on Payment Link

javascript
import payment from '@blocklet/payment-js';

async function createPaymentLinkWithDiscounts() {
  try {
    const paymentLink = await payment.paymentLinks.create({
      line_items: [{
        price_id: 'price_xxx',
        quantity: 1,
      }],
      allow_promotion_codes: true,
    });
    console.log('プロモーションコードが有効な支払いリンクが作成されました:', paymentLink.url);
  } catch (error) {
    console.error('支払いリンクの作成中にエラーが発生しました:', error.message);
  }
}

createPaymentLinkWithDiscounts();

割引の管理

SDKは、割引を管理および追跡するためのさまざまなメソッドを提供します。

コードでプロモーションコードを取得する

顧客向けのコード文字列を使用して、プロモーションコードの詳細を直接取得できます。

Get Promotion Code by Code

javascript
import payment from '@blocklet/payment-js';

async function getPromoDetails(code) {
  try {
    const promoByCode = await payment.promotionCodes.byCode(code);
    console.log('プロモーションコードが見つかりました:', promoByCode);
    // これで関連するクーポンの詳細にアクセスできます
    console.log('割引:', promoByCode.coupon);
  } catch (error) {
    console.error(`プロモーションコード '${code}' が見つからないか、エラーが発生しました:`, error.message);
  }
}

getPromoDetails('WELCOME20');

クーポン使用状況の確認

クーポンが少なくとも1回利用されたかどうかを判断します。これは、クーポンのルールがまだ編集可能かどうかを判断するのに役立ちます。

Check Coupon Usage

javascript
import payment from '@blocklet/payment-js';

async function checkCouponUsage(couponId) {
  try {
    const { used } = await payment.coupons.used(couponId);
    if (used) {
      console.log(`クーポン ${couponId} は使用されており、そのルールは現在ロックされています。`);
    } else {
      console.log(`クーポン ${couponId} はまだ使用されていません。`);
    }
  } catch (error) {
    console.error('クーポンの使用状況の確認中にエラーが発生しました:', error.message);
  }
}

checkCouponUsage('coupon_xxx'); // 有効なクーポンIDに置き換えてください

利用履歴のリスト表示

特定のクーポンまたはプロモーションコードを利用した顧客またはサブスクリプションのページ分割されたリストを取得できます。

List Coupon Redemptions

javascript
import payment from '@blocklet/payment-js';

async function getCouponRedemptions(couponId) {
  try {
    const redemptions = await payment.coupons.redemptions(couponId, {
      type: 'customer', // または 'subscription'
      page: 1,
      pageSize: 10
    });
    console.log(`クーポン ${couponId} の顧客利用が ${redemptions.count} 件見つかりました:`);
    redemptions.customers.forEach(customer => {
      console.log(`- 顧客ID: ${customer.id}`);
    });
  } catch (error) {
    console.error('利用履歴の取得中にエラーが発生しました:', error.message);
  }
}

getCouponRedemptions('coupon_xxx'); // 有効なクーポンIDに置き換えてください