クーポン更新API (v2)

クーポン更新APIは、発行済みクーポンの情報を変更するための機能です。

クーポンコード（cpNo）を識別子として、割引タイプ、有効期限、利用回数制限、グループ、ユーザー情報などを更新できます。
ただし、すでに利用済みのクーポンは一部の項目を変更できません。

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

API Version

PUT

/api/coupon/v2/update

Request
Response

{
    "cpnNo": "ZJLF0399WQBEQZJM",
    "nm": "$10 discount coupon",
    "disc": 10,
    "endYmd": "2025-12-31",
    "branchIdx": 11,
    "storeIdx": 22,
    "useScope": "BRANCH",
    "useBranchIdx": 11
}

Request Parameters

cpnNostringrequired: クーポン番号。
domain string: クーポンドメイン。
プレミアムプラン以上では、カスタムドメインを指定できます。
webhookEnableYn string
Enum: YN: Webhook の有効化設定。
グローバル Webhook が有効になっている必要があります。
この機能はエンタープライズプランでのみ利用可能です。
nmstring: クーポン名。
discTypeIdxinteger: 割引タイプ。（457: 割引率 %, 458: 金額割引）
discdouble: 割引率 (457) は 1〜100% の範囲、金額割引 (458) は金額を入力。
discCurrencystring: 通貨単位。金額割引 (discTypeIdx:458) を使用する場合は必須。
strtYmddate: クーポンの有効開始日。例: 2024-10-01
endYmddate: クーポンの有効期限。例: 2024-12-31
有効期限は翌年の12月31日までしか設定できません。
useLimitinteger: クーポンの利用可能回数。(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": null
}

Response Parameters

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

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

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

パラメータ	意味	説明
`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を利用する場面

すでに発行されたクーポンの条件を変更したい場合に利用します。

プロモーション期間の延長、割引内容の調整、特定ユーザーへの制限追加など、運用中のキャンペーン管理に適しています。

クーポンコードを変更せずに内容のみ更新できるため、配布済みクーポンを回収することなく条件を変更できます。

有効期限の延長方法

endYmdパラメータに新しい終了日を指定することで、有効期限を延長できます。
期限切れのクーポンも、終了日を未来の日付に更新することで再度利用可能になります。日付形式はYYYY-MM-DDを使用してください。

活用例

プロモーション期間の延長：endYmdを更新してキャンペーンの有効期間を延長
割引設定の調整：マーケティング方針の変更に合わせてdiscを変更
利用回数の拡張：VIPユーザー向けにuseLimitを増やし、同一クーポンの繰り返し利用を可能に
クーポングループの再設定：grpIdxを変更して別グループへ移動し、新しい画像やWebhook設定を適用
ユーザーターゲティング：メールアドレスやユーザーIDに基づくパーソナライズ割引を提供
ランディングページの変更：クーポンの遷移先URLを別のプロモーションページに更新

利用時の注意点

cpNo（クーポンコード）が無効な場合、更新は失敗します。
すでに利用済みのクーポンは、一部項目の変更が制限される場合があります。
割引内容の変更は既存ユーザー体験に影響を与える可能性があります。
期限切れのクーポンは、更新後もすぐに利用可能にならない場合があります。
店舗用クーポンのパスワードは、スタッフ変更時に必ず更新してください。