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

プロモーションコード

プロモーションコードは、顧客がチェックアウト時に割引を受けるために入力する、ユーザー向けの特定のコードです。各プロモーションコードは親のクーポンにリンクされており、これが実際の割引（例：20%オフ、$10オフ）を定義します。この2層構造により、同じ基礎となる割引を指す複数のユニークなコードを作成でき

プロモーションコードは、顧客がチェックアウト時に割引を受けるために入力する、ユーザー向けの特定のコードです。各プロモーションコードは親のクーポンにリンクされており、これが実際の割引（例：20%オフ、$10オフ）を定義します。この2層構造により、同じ基礎となる割引を指す複数のユニークなコードを作成でき、さまざまなマーケティングキャンペーンや配布チャネルを簡単に追跡できます。

このAPIを使用すると、プロモーションコードの作成、管理、および使用状況の追跡ができます。

プロモーションコードオブジェクト

プロモーションコードオブジェクトには、親クーポン、使用制限、制約など、特定のコードに関するすべての情報が含まれています。

  • id string — プロモーションコードの一意の識別子。
  • coupon_id string — このプロモーションコードが関連付けられているクーポンのID。
  • code string — 顧客が割引を適用するために入力するユーザー向けのコード。
  • description string — プロモーションコードの内部説明。
  • active boolean — プロモーションコードが現在アクティブで使用可能かどうか。
  • max_redemptions number — このプロモーションコードが利用できる最大回数。
  • times_redeemed number — このプロモーションコードが利用された回数。
  • expires_at number — プロモーションコードが失効する時期を示すUnixタイムスタンプ。
  • verification_type string — 割引の対象資格を検証するために使用される方法。「code」、「nft」、「vc」、または「user_restricted」が可能です。
  • nft_config object — NFTベースの検証のための設定。
  • vc_config object — 検証可能な資格情報（VC）ベースの検証のための設定。
  • customer_dids string[] — このコードを使用する資格のある顧客DIDの配列。
  • restrictions object — このプロモーションコードに適用される一連の制約。
  • metadata object — オブジェクトに添付できるキーと値のペアのセット。
  • coupon object — このプロモーションコードに関連付けられた展開済みのクーポンオブジェクト。
  • livemode boolean — オブジェクトがライブモードまたはテストモードのどちらに存在するかを示します。
  • created_at string — オブジェクトが作成されたときのタイムスタンプ。
  • updated_at string — オブジェクトが最後に更新されたときのタイムスタンプ。

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

新しいプロモーションコードオブジェクトを作成します。

パラメータ

  • coupon_id string (required) — このプロモーションコードに関連付けるクーポンのID。
  • code string — ユーザー向けのコード。指定しない場合、ランダムなコードが生成されます。最大16文字。
  • description string — コードのオプションの内部説明。最大250文字。
  • active boolean (default: true) — プロモーションコードがアクティブかどうか。デフォルトは true です。
  • max_redemptions number — プロモーションコードが利用できる最大回数。
  • expires_at number — このUnixタイムスタンプ以降、プロモーションコードは無効になります。
  • verification_type string (default: code) — 検証方法を指定します。「code」、「nft」、「vc」、または「user_restricted」が可能です。
  • nft_config object — NFTベースの検証のための設定。verification_type が nft の場合に必須です。
    • addresses string[] — コントラクトアドレスのリスト。
    • tags string[] — NFTタグのリスト。
    • trusted_issuers string[] — 信頼できる発行者のDIDのリスト。
    • trusted_parents string[] — 信頼できる親コレクションIDのリスト。
    • min_balance number (default: 1) — ユーザーが保持する必要があるNFTの最小残高。
  • vc_config object — 検証可能な資格情報（VC）ベースの検証のための設定。verification_type が vc の場合に必須です。
    • roles string[] — VCで要求されるロールのリスト。
    • trusted_issuers string[] — VCの信頼できる発行者のDIDのリスト。
  • customer_dids string[] — このプロモーションコードの使用が許可されている顧客DIDのリスト。verification_type が user_restricted の場合に必須です。
  • restrictions object — プロモーションコードが適用される条件を定義します。
    • currency_options object — プロモーションコードを適用するために必要な通貨別の最小金額。
      • {currency_code} object
        • minimum_amount number (required) — 指定された通貨での最小取引金額。
    • first_time_transaction boolean — trueの場合、プロモーションコードは顧客の初回取引にのみ適用されます。
  • metadata object — オブジェクトに関する追加情報を保存するためのキーと値のペアのセット。

戻り値

作成されたプロモーションコードオブジェクトを返します。

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

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

async function createPromotionCode() {
  try {
    const promotionCode = await payment.promotionCodes.create({
      coupon_id: 'coupon_xxxxxxxxxxxxxx', // 有効なクーポンIDに置き換えてください
      code: 'SUMMER25',
      description: '夏のセールで25%オフ',
      max_redemptions: 100,
      expires_at: Math.floor(new Date('2024-09-01').getTime() / 1000),
      active: true,
    });
    console.log('プロモーションコードが作成されました:', promotionCode);
  } catch (error) {
    console.error('プロモーションコードの作成中にエラーが発生しました:', error.message);
  }
}

createPromotionCode();

レスポンスの例

json
{
  "id": "pc_xxxxxxxxxxxxxx",
  "coupon_id": "coupon_xxxxxxxxxxxxxx",
  "code": "SUMMER25",
  "description": "夏のセールで25%オフ",
  "active": true,
  "max_redemptions": 100,
  "times_redeemed": 0,
  "expires_at": 1725148800,
  "verification_type": "code",
  "nft_config": null,
  "vc_config": null,
  "customer_dids": null,
  "restrictions": {},
  "metadata": {},
  "livemode": false,
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z",
  "coupon": {
    "id": "coupon_xxxxxxxxxxxxxx",
    "name": "Summer Sale",
    "percent_off": 25,
    // ... その他のクーポンの詳細
  }
}

プロモーションコードの取得

既存のプロモーションコードの詳細を取得します。

パラメータ

  • id string (required) — 取得するプロモーションコードの一意の識別子。

戻り値

プロモーションコードオブジェクトを返します。

プロモーションコードの取得

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

async function getPromotionCode(promotionCodeId) {
  try {
    const promotionCode = await payment.promotionCodes.retrieve(promotionCodeId);
    console.log('取得したプロモーションコード:', promotionCode);
  } catch (error) {
    console.error('プロモーションコードの取得中にエラーが発生しました:', error.message);
  }
}

getPromotionCode('pc_xxxxxxxxxxxxxx'); // 有効なプロモーションコードIDに置き換えてください

プロモーションコードの更新

渡されたパラメータの値を設定して、指定されたプロモーションコードを更新します。提供されなかったパラメータは変更されません。プロモーションコードが一度使用されると、そのmetadataのみが更新可能であることに注意してください。

パラメータ

  • id string (required) — 更新するプロモーションコードの一意の識別子。
  • description string — コードのオプションの内部説明。最大250文字。
  • active boolean — プロモーションコードがアクティブかどうか。
  • max_redemptions number — プロモーションコードが利用できる最大回数。
  • expires_at number — このUnixタイムスタンプ以降、プロモーションコードは無効になります。
  • restrictions object — プロモーションコードが適用される条件を定義します。
  • metadata object — オブジェクトに関する追加情報を保存するためのキーと値のペアのセット。

戻り値

更新されたプロモーションコードオブジェクトを返します。

プロモーションコードの更新

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

async function updatePromotionCode(promotionCodeId) {
  try {
    const updatedPromotionCode = await payment.promotionCodes.update(promotionCodeId, {
      description: '更新された夏のセールの説明',
      metadata: { campaign_id: 'summer-2024' },
    });
    console.log('プロモーションコードが更新されました:', updatedPromotionCode);
  } catch (error) {
    console.error('プロモーションコードの更新中にエラーが発生しました:', error.message);
  }
}

updatePromotionCode('pc_xxxxxxxxxxxxxx'); // 有効なプロモーションコードIDに置き換えてください

プロモーションコードの一覧表示

プロモーションコードのリストを返します。

パラメータ

  • page number (default: 1) — ページネーションのためのページ番号。
  • pageSize number (default: 20) — 1ページあたりのアイテム数。
  • coupon_id string — 関連するクーポンIDでプロモーションコードをフィルタリングします。
  • active boolean — アクティブステータスでプロモーションコードをフィルタリングします。

戻り値

ページネーションされたプロモーションコードオブジェクトのリスト。

プロモーションコードの一覧表示

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

async function listPromotionCodes() {
  try {
    const promotionCodes = await payment.promotionCodes.list({
      active: true,
      pageSize: 5,
    });
    console.log('アクティブなプロモーションコード:', promotionCodes.list);
  } catch (error) {
    console.error('プロモーションコードの一覧表示中にエラーが発生しました:', error.message);
  }
}

listPromotionCodes();

レスポンスの例

json
{
  "count": 50,
  "list": [
    {
      "id": "pc_xxxxxxxxxxxxxx",
      "code": "SUMMER25",
      // ... その他のプロモーションコードの詳細
    }
    // ... その他のプロモーションコード
  ],
  "paging": {
    "page": 1,
    "pageSize": 5
  }
}

プロモーションコードのアーカイブ

プロモーションコードを無効化し、利用できなくします。この操作は元に戻せません。

パラメータ

  • id string (required) — アーカイブするプロモーションコードの一意の識別子。

戻り値

activeがfalseに設定された、アーカイブ済みのプロモーションコードオブジェクトを返します。

プロモーションコードのアーカイブ

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

async function archivePromotionCode(promotionCodeId) {
  try {
    const archivedCode = await payment.promotionCodes.archive(promotionCodeId);
    console.log('プロモーションコードがアーカイブされました:', archivedCode);
  } catch (error) {
    console.error('プロモーションコードのアーカイブ中にエラーが発生しました:', error.message);
  }
}

archivePromotionCode('pc_xxxxxxxxxxxxxx'); // 有効なプロモーションコードIDに置き換えてください

プロモーションコードの削除

プロモーションコードを削除します。この操作は、プロモーションコードがまだ利用されていない場合にのみ可能です。使用されている場合はロックされ、削除できません。代わりにアーカイブする必要があります。

パラメータ

  • id string (required) — 削除するプロモーションコードの一意の識別子。

戻り値

削除されたプロモーションコードオブジェクトを返します。

プロモーションコードの削除

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

async function deletePromotionCode(promotionCodeId) {
  try {
    const deletedCode = await payment.promotionCodes.del(promotionCodeId);
    console.log('プロモーションコードが削除されました:', deletedCode);
  } catch (error) {
    console.error('プロモーションコードの削除中にエラーが発生しました:', error.message);
  }
}

deletePromotionCode('pc_xxxxxxxxxxxxxx'); // 未使用のプロモーションコードIDに置き換えてください

使用済みか確認

プロモーションコードが少なくとも1回利用されたかどうかを確認します。

パラメータ

  • id string (required) — 確認するプロモーションコードの一意の識別子。

戻り値

ブール値のusedプロパティを含むオブジェクト。

プロモーションコードが使用済みか確認

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

async function checkUsage(promotionCodeId) {
  try {
    const result = await payment.promotionCodes.used(promotionCodeId);
    console.log(`プロモーションコードは使用済みですか？ ${result.used}`);
  } catch (error) {
    console.error('プロモーションコードの使用状況の確認中にエラーが発生しました:', error.message);
  }
}

checkUsage('pc_xxxxxxxxxxxxxx'); // 有効なプロモーションコードIDに置き換えてください

レスポンスの例

json
{
  "used": true
}

コードによる取得

ユーザー向けのコード文字列によってプロモーションコードの詳細を取得します。

パラメータ

  • code string (required) — ユーザー向けのコード文字列。

戻り値

プロモーションコードオブジェクトを返します。

コード文字列によるプロモーションコードの取得

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

async function getByCode(code) {
  try {
    const promotionCode = await payment.promotionCodes.byCode(code);
    console.log('プロモーションコードが見つかりました:', promotionCode);
  } catch (error) {
    console.error('コードによるプロモーションコードの取得中にエラーが発生しました:', error.message);
  }
}

getByCode('SUMMER25');

利用履歴の一覧表示

特定のプロモーションコードを利用した顧客とサブスクリプションのリストを取得します。

パラメータ

  • id string (required) — プロモーションコードの一意の識別子。
  • page number (default: 1) — ページネーションのためのページ番号。
  • pageSize number (default: 20) — 1ページあたりのアイテム数。
  • type 'customer' | 'subscription' — 一覧表示する利用履歴のタイプ。「customer」または「subscription」が可能です。

戻り値

顧客とサブスクリプションのリストを含む利用履歴データを含むオブジェクト。

プロモーションコードの利用履歴の一覧表示

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

async function listRedemptions(promotionCodeId) {
  try {
    const redemptions = await payment.promotionCodes.redemptions({
      id: promotionCodeId,
      type: 'customer',
      pageSize: 10
    });
    console.log('利用履歴:', redemptions);
  } catch (error) {
    console.error('利用履歴の一覧表示中にエラーが発生しました:', error.message);
  }
}

listRedemptions('pc_xxxxxxxxxxxxxx'); // 有効なプロモーションコードIDに置き換えてください

レスポンスの例

json
{
  "count": 5,
  "subscriptions": [],
  "customers": [
    {
      "id": "cus_yyyyyyyyyyyyyy",
      "did": "did:abt:z...",
      // ... その他の顧客の詳細
    }
    // ... その他の顧客
  ],
  "paging": {
    "page": 1,
    "pageSize": 10
  }
}