コンテンツにスキップ

ポイント・ギフト券・クーポン（Points System）

ポイント/ギフト券/クーポンの運用を支えるプラグイン。ギフト券コード登録によるポイント加算、ポイント残高/履歴の取得、動的マイナス価格によるポイント割引、クーポン割引の仮想商品出力を担う。

用語の整理: ここでの ギフト券 は「名前などのメタデータを持つ期限付きのポイント付与手段」であり、ポイントの下位概念。キャンペーンの特典として無償付与される ギフト品（add_gift_items / select_gift_items）とは別概念で、業務系統も異なる（ギフト品は CommercialRulesPlugin の campaign 側が担当）。「ギフト」という語が両者に付くため混同しないこと。系統の正本は glossary を参照。

役割

  • ギフト券管理: ギフト券コード登録によるポイント付与（Storefrontのマイメニュー/URL query からの登録）。
  • ポイント管理: ポイント残高と獲得履歴の管理、有効期限の制御。
  • ポイント利用: 注文時のポイント適用（動的なマイナス価格としての処理）。
  • 管理機能: ギフト券コードの発行、無効化、削除、および仮想商品割り当ての編集（Vendure Dashboard）。
  • SMILE連携: クーポン割引やポイント利用を仮想商品行として注文CSVに出力。

仮想商品コード

割引・付与などの金額調整を SMILE 注文 CSV へ「仮想商品行」として出すための商品番号。

重要（番号は未定 / Vendure 設定値が正本）: 下表の商品番号は 暫定の既定値であり、まだ確定していない。runtime で実際に使う値は Vendure の設定値に従う＝ Vendure Dashboard「設定 > 仮想商品割り当て」で保存した値（SettingsStore key points.virtual-product-assignments）が SSOT で、未保存時のみ PointsSystemPluginOptions 既定値（packages/plugins/src/standard-extensions/points/types.ts）／ seed（apps/vendure-server/src/data/points-seed.ts）へフォールバックする。コード・SMILE 出力・帳票はこの設定値を参照するため、ドキュメント中の数値を固定値として扱わないこと。確定したら Vendure 側設定と本表を更新する。

商品番号（暫定） 設定キー 用途 価格 runtime での消費
80000060（暫定） giftBaseProductCode ギフト用（ギフト券＝メタデータ付き期限付きポイント付与の商品コード） −¥1 ギフト券（GiftVoucher.baseProductCode）の既定値
80000061（暫定） pointsBaseProductCode ポイント用（注文へのポイント利用 surcharge と帳票・SMILE のポイント利用行） −¥1 applyPointsToOrder の surcharge SKU / SMILE「ポイント利用」行 / 見積の控除判定
80000088（暫定） couponBaseProductCode クーポン用（SMILE クーポン割引行。コード別 override 可） −¥1 SMILE「クーポン割引」行
  • ギフト用とポイント用は別コード。ギフト＝メタデータ付きポイント付与、ポイント＝ポイントそのもの、という別概念に対応する（glossary）。
  • キャンペーンのギフト品（add_gift_items / select_gift_items）はこの仮想商品を使わず、実商品 SKU を ¥0 で出す。混同しないこと。

プラグイン情報

  • コード配置: packages/plugins/src/standard-extensions/points
  • エントリーポイント: PointsSystemPlugin (packages/plugins/src/standard-extensions/points/index.ts)
  • 初期化: PointsSystemPlugin.init({ ... })

GraphQL API

Shop API

  • pointSummary: ポイント残高と次回失効情報（残高、次回失効日、失効予定額）。
  • pointHistory: 獲得履歴（降順）。
  • applyGiftCode(code: String!): ギフト券コード登録。
  • applyPointsToOrder(amount: Int!): 注文へのポイント適用。指定したポイント額を上限に、注文合計額または残高の範囲内で適用し、マイナスのSurchargeを追加する。

Storefront: URL query によるギフト券自動適用

  • Storefront の任意ページで ?gift_code=... が付与されている場合、ログイン済みなら自動で applyGiftCode を実行する。
  • 未ログインの場合は、gift_code を一時保存し、ログイン後に自動適用する（自動リダイレクトはしない）。
  • gift_code は適用処理の開始時点で URL から除去される（他の query は維持される）。

Admin API

  • pointSummaryForCustomer(customerId: ID!): 顧客指定のポイント残高確認。
  • pointHistoryForCustomer(customerId: ID!): 顧客指定の履歴確認。
  • createGiftVoucher(input: ...): ギフト券マスタの作成。
  • createGiftVoucherCode(input: ...): ギフト券コードの発行。
  • disableGiftCode(code: String!): 未使用コードの無効化。
  • deleteGiftCode(code: String!): 未使用コードの削除。
  • giftVoucherCodeByCode(code: String!): コードの詳細照会。
  • pointsVirtualProductSettings: ギフト用 / ポイント用 / クーポン割引用の仮想商品割り当て設定を取得。
  • updatePointsVirtualProductSettings(input: ...): 仮想商品割り当て設定を更新。

データモデル

  • ポイント台帳 (ritsubi_point_ledger)
  • 付与/減算履歴を保持。
  • amount: 正の値は付与、負の値は消費。
  • expiresAt: 有効期限（付与時のみ設定）。

  • sourceType/sourceId: 発生源（ギフト券コード、注文IDなど）。

  • ギフト券マスタ (ritsubi_gift_voucher)

  • 付与ポイント、登録期限、有効期限ルール（相対日数/固定日）、対象制限（顧客/グループ）を定義。

  • baseProductCode: 紐づくギフト用仮想商品コード（デフォルト 80000060）。

  • ギフト券コード (ritsubi_gift_voucher_code)

  • 個別のシリアルコード。
  • status: ACTIVE（有効）、USED（使用済）、DISABLED（無効）。
  • issuedByAdminId: 発行担当者ID。

  • productCodeOverride: 将来、コード単位で出力商品番号を切り替えたい場合の拡張用（現状はポイント利用のSMILE出力には反映しない）。

  • クーポンコード上書き (ritsubi_coupon_code_override)

  • 特定のクーポンコードに対して、デフォルトと異なる仮想商品番号を出力したい場合に利用。

ロジック詳細

動的マイナス価格（ポイント利用）

ポイントを利用する場合、通常の割引（Promotion）ではなく、負の価格を持つ Surcharge（追加料金） として注文に追加される。

  1. 注文合計、ポイント残高、利用指定額から、適用可能な最大ポイント数を算出。
  2. ポイント利用用の仮想商品（price: toVendureMoneyFromYen(-1)、つまり -100 Vendure Money） を使用し、利用ポイント数ぶんの円額を toVendureMoneyFromYen() で Surcharge に追加。
  3. ポイント台帳から同額のポイントを消費（減算レコード追加）。

有効期限

  • 相対日付: ギフト券登録日（または付与日）の JST 日付 から N 日後の暦日として扱う。
  • 固定日付: 特定の日付（例：2026-12-31）を JST 日付 として扱い、その当日中まで有効とする。
  • 消費時は、有効期限の近いポイントから順に充当される（先入先出に似たロジックだが、厳密には期限優先）。
  • React Dashboard の登録期限 / 固定有効期限入力は YYYY-MM-DD の日付入力に統一し、保存時は JST 0:00 の境界へ正規化する。

シードデータ（開発環境）

apps/vendure-server/src/data/points-seed.ts により、以下のデータが自動投入される（seed-data.ts 実行時）。

  • 仮想商品（商品番号は暫定の既定値。確定値は Vendure の設定値に従う。仮想商品コード参照）:
  • 80000060: ギフト調整（価格: -1円, 税率: 0%）
  • 80000061: ポイント利用（価格: -1円, 税率: 0%）
  • 80000088: クーポン割引（価格: -1円, 税率: 0%）
  • テスト用ギフト券:
  • 名称: 「新規登録キャンペーン500pt」
  • ポイント: 500pt
  • コード: WELCOME-500

SMILE連携

  • クーポン割引/ポイント利用は 仮想商品行 として注文CSVに出力される。
  • これにより、基幹システム側では「商品」として扱われ、会計上の処理（値引きではなく売上減額や別勘定など）が可能となる。
  • ベース仮想商品番号（ポイント用 80000061 / クーポン用 80000088、いずれも暫定の既定値）。実際に使う番号は Vendure の設定値に従う（仮想商品コード参照）。
  • ポイント利用は 総計して1行 で出力する（商品コードは pointsBaseProductCode 固定）。

設定

商品番号は未確定で、実値は Vendure の設定値が正本。運用中の割り当ては Vendure Dashboard の 設定 > 仮想商品割り当て から更新し、その値（SettingsStore）が実行時に使われる。PointsSystemPlugin.init のオプションは Dashboard 未保存時のフォールバック既定値にすぎない（下記の番号も暫定）。

PointsSystemPlugin.init({
  giftBaseProductCode: "80000060", // ギフト用（ギフト券）※暫定の既定値
  pointsBaseProductCode: "80000061", // ポイント用（注文ポイント利用 / SMILE ポイント利用行）※暫定
  couponBaseProductCode: "80000088", // クーポン用 ※暫定
});
  • Dashboard で保存した設定は SettingsStoreService に保持され、ポイント利用・SMILE 注文 CSV・帳票生成が実行時に参照する。