Google PlayからVivoldiアプリをインストールすれば、さらに便利に。

オンラインクーポン作成API (v2)

Vivoldiのクーポン作成APIを使用すると、割引クーポンをプログラムで発行できます。

割引率（%）または固定金額を選択し、有効期限・利用回数・グループ・テンプレートなどの詳細オプションをリクエスト時に設定できます。

複数のクーポンを一括で作成する場合は、ダッシュボードをご利用ください。
画像が必要な場合は、事前にダッシュボードでクーポングループを作成し、画像を登録したうえで、そのグループを指定してクーポンを生成してください。

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

POST

/api/coupon/v2/create 

{
    "cpnNo": "",
    "cpnNoDigits": 12,
    "domain": "https://vvd.bz",
    "webhookEnableYn": "N",
    "nm": "$5 discount coupon",
    "discTypeIdx": 458,
    "disc": 5,
    "discCurrency": "USD",
    "strtYmd": "2025-01-01",
    "endYmd": "2025-12-31",
    "useLimit": 1,
    "grpIdx": 271,
    "tmplIdx": 0,
    "onsiteYn": "Y",
    "onsitePwd": "123456",
    "branchIdx": 11,
    "storeIdx": 22,
    "useScope": "BRANCH",
    "useBranchIdx": 11,
    "memo": "New Member Registration, IP: 211.111.222.33",
    "url": "https://bestshop.com",
    "userId": "att78z",
    "userNm": "Brown Smith",
    "userPhnno": "+1 123-4567-8900",
    "userEml": "test@gmail.com",
    "userEtc1": "Gold rating",
    "userEtc2": ""
}

Request Parameters

cpnNostring
クーポン番号。 英数字8～16桁。値がない場合はシステムで自動生成されます。特殊文字は使用不可。
例: V5H8GR5T
cpnNoDigits integer
Default:16
Enum:
16128
クーポンコードの桁数。
指定がない場合はデフォルト値（16桁）が適用されます。
クーポンコードを指定しない場合にのみ有効で、選択した桁数で自動生成されます。
domain string
デフォルト:https://vvd.bz
クーポンドメイン。
空の場合はデフォルトドメインで保存されます。
プレミアムプラン以上では、「リンクドメイン管理」で登録したカスタムドメインを指定できます。
webhookEnableYn string
Enum:
YN
Webhook の有効化設定。
グローバル Webhook が有効になっている必要があります。
この機能はエンタープライズプランでのみ利用可能です。
nmstringrequired
クーポン名。
discTypeIdxintegerrequired
割引タイプ。（457: 割引率 %, 458: 金額割引）
discdoublerequired
割引率（457）の場合: 1～100% の範囲。 金額割引（458）の場合: 金額を入力。
discCurrencystring
通貨単位。金額割引（discTypeIdx:458）を使用する場合は必須。
strtYmddaterequired
クーポン有効開始日。例: 2024-10-01
endYmddaterequired
クーポン有効期限日。例: 2024-12-31
有効期限は翌年の12月31日までしか設定できません。
useLimitintegerrequired
クーポン使用可能回数。（0: 無制限、1～5: 回数制限）
2回以上に設定する場合は userId を必ず指定する必要があります。
grpIdxinteger
クーポングループ。 グループで管理する場合に使用します。グループIDXはダッシュボードで確認可能。
グループ設定とクーポン設定が重複する場合は、グループ設定が優先されます。
tmplIdxinteger
クーポンテンプレート。 クーポン作成時に参照するテンプレート。テンプレートIDXはダッシュボードで確認可能。
onsiteYnstring
店舗用クーポンの有無。クーポンページに 「クーポンを使用」 ボタンを表示。
オフライン店舗でスタッフが利用処理を行う際に必要。
onsitePwdstring
店舗用クーポンのパスワード。クーポン利用時に必要。
memostring
内部参照用メモ。
urlstring
URLを入力すると、クーポンページに 「クーポンを使う」 ボタンが表示されます。
ボタンまたはクーポン画像をクリックすると、そのURLにリダイレクトされます。
colorstring
クーポン文字色。HEX値で指定。例: #4F4F4F
backgroundstring
クーポン背景色。HEX値で指定。例: #FFFFFF
userIdstring
クーポン発行対象者を管理するために使用。
使用回数が2～5に設定されている場合は必須入力。通常は会員のログインIDまたは英字氏名を指定。
userNmstring
クーポン利用者名。内部管理用。
userPhnnostring
クーポン利用者の連絡先。内部管理用。
userEmlstring
クーポン利用者のメールアドレス。内部管理用。
userEtc1string
追加の内部管理用フィールド。
userEtc2string
追加の内部管理用フィールド。
branchIdx integer
発行支店IDX。省略した場合は本社発行となり、0を送ると本社に戻します。
ビジネスプラン以上でご利用いただけます。
storeIdx integer
発行店舗IDX。指定すると、その店舗が属する支店が発行支店になります。異なる支店を一緒に送るとエラーになります。
useScope string
利用可能範囲。ALL(すべての店舗)またはBRANCH(特定の支店)のみ指定できます。省略時はALLです。
useBranchIdx integer
利用可能支店IDX。useScope = BRANCHの場合のみ必要で、ALLのときは常に空です。 
{
    "code": 0,
    "message": "",
    "result": "ZJLF0399WQBEQZJM"
}

Response Parameters

code integer
応答コード: 0 = 成功、それ以外の値 = エラー
message string
応答メッセージです。応答コードが0でない場合、エラーメッセージが返されます。
result string
応答値。生成されたクーポン番号が返されます。
例: ZJLF0399WQBEQZJM

発行支店・店舗と利用可能範囲

ここで指定する値は発行時点で保存されるポリシーです。 「どこで発行されたか」(発行支店・発行店舗)と「お客様がどこで利用できるか」(利用可能範囲・利用可能支店)は 異なる概念のため、パラメータも分かれています。

パラメータ 意味 説明
branchIdx 発行支店 省略すると本社発行になります。0を送ると本社に戻します。
storeIdx 発行店舗 指定すると、その店舗が属する支店が発行支店になります。異なる支店を一緒に送ると拒否されます。
useScope 利用可能範囲 ALL(すべての店舗)またはBRANCH(特定の支店)。省略時はALLです。
useBranchIdx 利用可能支店 useScope=BRANCHの場合のみ必要です。ALLのときは常に空です。

使用できないパラメータ — processStoreIdx(処理店舗)は 検証・利用・付与・差し引きが実際に行われた店舗を指す値のため、このAPIでは使用できません。 一緒に送ると400(エラーコード1227)で拒否されます。

支店・店舗機能はビジネスプラン以上でのみご利用いただけます。

Idempotency-Key

ネットワークエラーで応答を受け取れなかったときに安全に再試行するには、Idempotency-Keyヘッダーに リクエストごとに一意の値を入れて送信します。本文のrequestIdでも送れますが、 両方を送って値が異なる場合は拒否されます。 使用できる形式は英数字と. _ : -を組み合わせた8〜64文字です。

同じkeyで同じリクエストを再送すると、再処理せずに最初の結果をそのまま返します。 重複して処理されることはなく、Webhookも再送されません。

同じkeyは同じ論理操作の再試行にのみ使用してください。 異なる操作には必ず新しいkeyを使用してください。 同じkeyを異なるリクエスト内容や別の操作に使用すると409で拒否される場合があります。

このAPIを利用する場面

プロモーションやイベント、ユーザー獲得施策でクーポンを自動発行したい場合に利用します。

新規登録インセンティブや特定ユーザー向けの割引、広告流入のコンバージョン促進など、さまざまなマーケティング施策に活用できます。

クーポンコード形式の設定方法

クーポンコードはcpNoとcpNoDigitsパラメータで制御します。
cpNoを指定した場合はその値がクーポンコードとして使用され、未指定の場合はシステムが自動生成します。

自動生成時はcpNoDigitsで桁数（デフォルト: 16）を設定できます。
用途に応じて調整してください。桁数が長いほど重複リスクが低くなり、短いほど入力しやすくなります。

ユーザー情報の連携

クーポンを特定のユーザーに紐付けるには、userIdを指定します。

複数ユーザーに紐付ける場合は、userEml·userPhone·userEtc1·userEtc2フィールドを併用できます。
これらの情報はダッシュボードでクーポン所有者の確認やフィルタリングに使用され、ユーザー識別が必要なB2Cサービスに適しています。

活用例

  • 新規登録特典の自動配布：ユーザー登録時にAPIを呼び出し、個別クーポンを即時生成・配布
  • 期間限定プロモーション：開始日と終了日を設定し、特定期間のみ有効なクーポンを発行
  • 広告コンバージョンの追跡：広告リンクにクーポンを紐付け、クリック→利用→購入までを可視化
  • ユーザーターゲティング：メールアドレスやユーザーIDを基にパーソナライズされた割引を提供
  • 店舗利用クーポン：onsiteYnをYに設定し、提示されたクーポンをスタッフがパスワードで処理

利用時の注意点

  • 画像付きクーポンを生成する場合は、事前にダッシュボードでクーポングループを作成し、画像を登録したうえで、grpIdxにグループIDを指定してください。
  • Webhookを受信する場合は、webhookEnablYnをYに設定し、事前にダッシュボードでWebhook URLを登録してください。
  • useLimitが無制限の場合、クーポンは利用されても使用済みとしては扱われません。
  • 店舗利用クーポンでは、利用処理用パスワードの管理を徹底してください。