クーポン利用API（Redeem）

Vivoldiのクーポン利用API（Redeem）は、発行済みクーポンを利用済み状態に更新する機能です。

ダッシュボードでの手動処理を行わず、APIによって自動的に利用処理を実行できます。
呼び出しごとに利用回数が減少し、上限に達するとそれ以降は利用できなくなります。

このAPIはパーソナルプラン以上で利用できます。

PUT

/api/coupon/v1/redeem 

{
    "cpnNo": "ZJLF0399WQBEQZJM",
    "userId": "x77hu",
    "memo": "IP Address: 210.123.111.222, Request Page: https://example.com/shop/bags/p112233"
}

Request Parameters

cpnNo string required
クーポン番号。
onsitePwd string
現場クーポンのパスワード。 現場クーポンにパスワードが設定されている場合は必須入力です。
userId string
ユーザーID。 クーポン発行者・利用者を識別するためのID。
クーポンの利用可能回数が 2～5 に設定されている場合は必ず入力してください。
memo string
内部参照用メモ。 ユーザーのIP、クーポン利用先、その他の情報を記録できます。
クーポン利用回数が無制限の場合、userIdの代わりにこのメモを使ってユーザーを区別できます。 
{
    "code": 0,
    "message": "",
    "result": null
}

Response Parameters

code integer
応答コード: 0 = 成功、それ以外の値 = エラー
message string
応答メッセージです。応答コードが0でない場合、エラーメッセージが返されます。
result null

検証APIと併用する方法

クーポン利用APIは状態を変更するため、呼び出し前に検証APIで有効性を確認することを推奨します。

事前に有効なクーポンであることを確認することで、期限切れや利用済みクーポンへの不要な処理を防げます。

基本フローは「検証 → 利用」です。

このAPIを利用する場面

クーポン検証後、実際にクーポンを適用する際に利用します。

  • 決済完了時にクーポンを利用処理する場合
  • 注文確定時に割引適用を記録する場合
  • 店舗や現地での利用処理
  • 重複利用を防ぐための状態更新

つまり、クーポンを実際に消費する最終ステップです。

クーポン利用処理の仕組み

クーポン番号（cpnNo）を基準に、クーポンを利用済み状態に変更します。

  • 利用時に即座に利用回数が減算される
  • 再利用不可の状態に遷移する
  • ユーザー情報（userId）に基づいて利用履歴を記録
  • memoを使って追加ログを記録可能

この処理は単なる状態変更ではなく、決済処理に紐づく重要なトランザクションです。

ユーザー識別とメモの活用

userIdはクーポンを利用したユーザーを識別するために使用されます。

利用回数が2～5回に設定されている場合は必須であり、同一ユーザーによる重複利用を防ぐ基準となります。

memoにはユーザーIPや利用場所、リクエスト元などの内部情報を記録できます。
利用回数制限がない場合は、userIdの代わりにmemoでユーザーを識別することも可能です。

店舗用クーポンのパスワード処理

onsitePwdはクーポンにパスワードが設定されている場合に入力が必要です。

店舗や現場でスタッフがクーポンを処理する際に、パスワード確認として利用されます。

活用例

  • EC決済連携：決済完了時にAPIを呼び出し、クーポンを自動適用し割引履歴を記録
  • 店舗での処理：スタッフがQRコードをスキャンし、クーポン番号を取得してAPIで即時利用処理
  • 利用履歴の追跡：memoにIPやリクエスト元を記録し、不正利用や異常パターンを分析
  • 複数回利用クーポン管理：userIdで同一ユーザーの利用回数超過を防止

削除後でも同じクーポンコードで再作成することが可能です。

利用時の注意点

  • 安全性のため、必ず検証APIの後に呼び出してください。
  • 利用処理後はクーポンを再利用できません。
  • 決済失敗時に備え、ロールバック戦略が必要になる場合があります。
  • 重複リクエストによる二重利用を防ぐため、対策を実装してください。