クーポン | ArcBlock

クーポンは、製品やサービスに割引を提供するための強力なツールです。クーポンオブジェクトには、割引率や固定割引額など、特定の割引に関する情報が含まれています。クーポンを利用可能にするには、1つ以上のプロモーションコードに関連付ける必要があります。このAPIを使用すると、クーポンの作成、管理、および使用状況の追跡ができます。

クーポンの作成

新しいクーポンを作成します。オプションで、同じリクエスト内でこのクーポンに関連付ける1つ以上のプロモーションコードを作成できます。

パラメータ

name string (required) — 顧客に表示されることを意図したクーポンの名前。例：SUMMER25。
percent_off number — 1から100までの正の整数で、サブスクリプションの請求書小計から割引される割合を表します。percent_offまたはamount_offのいずれかが必要です。
amount_off string — 請求書に適用される割引額を表す正の小数。percent_offまたはamount_offのいずれかが必要です。currency_idの設定が必要です。
currency_id string — amount_offが適用される通貨のID。amount_offが設定されている場合に必要です。
duration string (required) — 割引が有効な期間を指定します。once、repeating、またはforeverのいずれかです。
duration_in_months number — durationがrepeatingの場合、クーポンが適用される月数。durationがrepeatingの場合に必要です。
max_redemptions number — クーポンが利用できる最大回数を指定する正の整数。これを空にすると、クーポンは無制限に利用できます。
redeem_by number — クーポンが利用できる最終日時を指定するUnixタイムスタンプ。この日時以降、クーポンは新規顧客に適用できなくなります。
applies_to object — このクーポンが適用される製品IDを含むハッシュ。
- products string[] — このクーポンが適用される製品IDの配列。
currency_options object — amount_offが指定されている場合、このハッシュを使用して通貨ごとのクーポン金額を設定できます。顧客の通貨がハッシュ内のキーと一致する場合、そのキーの値が割引額として使用されます。
metadata object — オブジェクトに添付できるキーと値のペアのセット。オブジェクトに関する追加情報を構造化された形式で保存するのに役立ちます。
promotion_codes array — このクーポンに作成して添付するプロモーションコードオブジェクトの配列。詳細は以下を参照してください。

promotion_codes オブジェクトのプロパティ

code string — 顧客向けのコード。空のままにすると、ランダムなコードが生成されます。
description string — プロモーションコードのオプションの説明。
max_redemptions number — この特定のプロモーションコードが利用できる最大回数。
expires_at number — プロモーションコードの有効期限を指定するUnixタイムスタンプ。

戻り値

新しく作成されたcouponオブジェクトとpromotion_codesの配列を含むオブジェクトを返します。

**** object
- coupon object — 作成されたクーポンオブジェクト。
- promotion_codes array — 作成されたプロモーションコードオブジェクトの配列。

例

Create a Coupon

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

async function createCoupon() {
  try {
    const result = await payment.coupons.create({
      name: '20% Off First Month',
      percent_off: 20,
      duration: 'once',
      max_redemptions: 100,
      promotion_codes: [
        {
          code: 'NEWUSER20',
          description: 'Discount for new users',
          max_redemptions: 50,
          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);
  }
}

createCoupon();

レスポンスの例

{
  "coupon": {
    "id": "coupon_12345",
    "name": "20% Off First Month",
    "percent_off": 20,
    "amount_off": null,
    "currency_id": null,
    "duration": "once",
    "duration_in_months": null,
    "max_redemptions": 100,
    "times_redeemed": 0,
    "valid": true,
    "livemode": false,
    "created_at": "2023-10-27T10:00:00.000Z",
    "updated_at": "2023-10-27T10:00:00.000Z"
  },
  "promotion_codes": [
    {
      "id": "promo_67890",
      "coupon_id": "coupon_12345",
      "code": "NEWUSER20",
      "description": "Discount for new users",
      "active": true,
      "max_redemptions": 50,
      "times_redeemed": 0,
      "expires_at": 1699984800,
      "livemode": false
    }
  ]
}

クーポンの取得

指定されたIDのクーポンを取得します。レスポンスには、関連付けられたプロモーションコードとクーポンが適用される製品が含まれます。

パラメータ

id string (required) — 取得するクーポンのID。

戻り値

有効なIDが提供された場合、クーポンオブジェクトを返します。それ以外の場合はエラーを返します。

**** object — 取得されたクーポンオブジェクト。関連するプロモーションコードと適用された製品で展開されます。

例

Retrieve a Coupon

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

async function retrieveCoupon(couponId) {
  try {
    const coupon = await payment.coupons.retrieve(couponId);
    console.log('取得したクーポン:', coupon);
  } catch (error) {
    console.error('クーポンの取得中にエラーが発生しました:', error);
  }
}

retrieveCoupon('coupon_12345');

レスポンスの例

{
  "id": "coupon_12345",
  "name": "20% Off First Month",
  "percent_off": 20,
  "duration": "once",
  "valid": true,
  "promotion_codes": [
    {
      "id": "promo_67890",
      "code": "NEWUSER20",
      "active": true
    }
  ],
  "applied_products": []
}

クーポンの更新

渡されたパラメータの値を設定して、指定されたクーポンを更新します。提供されなかったパラメータは変更されません。

パラメータ

id string (required) — 更新するクーポンのID。
name string — クーポンの名前。
description string — クーポンのオプションの説明。
max_redemptions number — クーポンが利用できる最大回数。
redeem_by number — クーポンが利用できる最終日時を指定するUnixタイムスタンプ。
valid boolean — クーポンが現在有効かどうか。
currency_options object — 通貨ごとのクーポン金額を更新します。
metadata object — オブジェクト上で更新するキーと値のペアのセット。

戻り値

更新されたクーポンオブジェクトを返します。

**** object — 更新されたクーポンオブジェクト。

例

Update a Coupon

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

async function updateCoupon(couponId) {
  try {
    const updatedCoupon = await payment.coupons.update(couponId, {
      name: 'Summer Sale 2024',
      metadata: { campaign: 'summer-2024' },
    });
    console.log('クーポンが更新されました:', updatedCoupon);
  } catch (error) {
    console.error('クーポンの更新中にエラーが発生しました:', error);
  }
}

updateCoupon('coupon_12345');

レスポンスの例

{
  "id": "coupon_12345",
  "name": "Summer Sale 2024",
  "percent_off": 20,
  "duration": "once",
  "valid": true,
  "metadata": {
    "campaign": "summer-2024"
  }
}

すべてのクーポンを一覧表示

クーポンの一覧を返します。

パラメータ

valid boolean — 有効性でクーポンをフィルタリングします。
name string — 名前でクーポンをフィルタリングします。
page number (default: 1) — 取得するページ番号。
pageSize number (default: 20) — ページごとに取得するアイテムの数。

戻り値

クーポンの配列を含むlistプロパティ、クーポンの総数を含むcountプロパティ、およびpagingオブジェクトを持つオブジェクト。

**** object
- list array — クーポンオブジェクトの配列。
- count number — クエリに一致するクーポンの総数。
- paging object — ページネーション情報。
  - page number — 現在のページ番号。
  - pageSize number — 1ページあたりのアイテム数。

例

List Coupons

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

async function listCoupons() {
  try {
    const coupons = await payment.coupons.list({ valid: true, pageSize: 5 });
    console.log('見つかったクーポン:', coupons.list);
  } catch (error) {
    console.error('クーポンの一覧表示中にエラーが発生しました:', error);
  }
}

listCoupons();

レスポンスの例

{
  "count": 25,
  "list": [
    {
      "id": "coupon_12345",
      "name": "Summer Sale 2024",
      "percent_off": 20,
      "valid": true
    },
    {
      "id": "coupon_67890",
      "name": "10 USD Off",
      "amount_off": "1000",
      "valid": true
    }
  ],
  "paging": {
    "page": 1,
    "pageSize": 5
  }
}

クーポンの削除

APIを介してクーポンを削除できます。クーポンを削除すると、将来のサブスクリプションへの適用が防止されます。ただし、すでに適用されているサブスクリプションからは削除されません。

パラメータ

id string (required) — 削除するクーポンのID。

戻り値

削除されたクーポンオブジェクトを返します。クーポンが使用されている場合、削除できず、エラーがスローされます。

**** object — 削除されたクーポンオブジェクト。

例

Delete a Coupon

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

async function deleteCoupon(couponId) {
  try {
    const deletedCoupon = await payment.coupons.del(couponId);
    console.log('クーポンが削除されました:', deletedCoupon.id);
  } catch (error) {
    console.error('クーポンの削除中にエラーが発生しました:', error);
  }
}

deleteCoupon('coupon_abcde');

レスポンスの例

{
  "id": "coupon_abcde",
  "name": "Temporary Discount",
  "percent_off": 15,
  "valid": false
}

クーポンが使用されているか確認

クーポンが少なくとも1回利用されたかどうかを確認します。

パラメータ

id string (required) — 確認するクーポンのID。

戻り値

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

used boolean — クーポンが利用されている場合はtrue、そうでない場合はfalse。

例

Check Coupon Usage

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

async function checkCouponUsage(couponId) {
  try {
    const result = await payment.coupons.used(couponId);
    console.log(`クーポン ${couponId} は使用されていますか？`, result.used);
  } catch (error) {
    console.error('クーポンの使用状況の確認中にエラーが発生しました:', error);
  }
}

checkCouponUsage('coupon_12345');

レスポンスの例

{
  "used": true
}

クーポン利用状況の取得

どの顧客やサブスクリプションがクーポンを使用したかなど、クーポンの利用に関する詳細な分析データを取得します。

パラメータ

id string (required) — クーポンのID。
type string — 取得する利用データのタイプ。customerまたはsubscriptionを指定できます。
page number (default: 1) — 取得するページ番号。
pageSize number (default: 20) — ページごとに取得するアイテムの数。

戻り値

利用詳細を含むデータオブジェクトを返します。

**** object
- count number — 利用総数。
- subscriptions array — クーポンを利用したサブスクリプションのリスト（タイプが'subscription'の場合）。
- customers array — クーポンを利用した顧客のリスト（タイプが'customer'の場合）。
- paging object — ページネーション情報。

例

Get Coupon Redemptions

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

async function getRedemptions(couponId) {
  try {
    const redemptions = await payment.coupons.redemptions(couponId, {
      type: 'customer',
      pageSize: 10,
    });
    console.log('総利用回数:', redemptions.count);
    console.log('利用した顧客:', redemptions.customers);
  } catch (error) {
    console.error('利用状況の取得中にエラーが発生しました:', error);
  }
}

getRedemptions('coupon_12345');

レスポンスの例

{
  "count": 1,
  "subscriptions": [],
  "customers": [
    {
      "id": "cus_abc123",
      "did": "did:abt:z123...",
      "email": "customer@example.com",
      "name": "Test Customer",
      "coupon_usage_stats": {
        "coupon_12345": 1
      }
    }
  ],
  "paging": {
    "page": 1,
    "pageSize": 10
  }
}