マーケティング担当者向け
クーポンAPI
クーポンの作成・編集・取り下げと、レジでの検証・消込を行います。消込は記録として残り、発行枚数の上限も守られます。
api/v1/stores/{storeId}/coupons
APIリファレンスで確認
エンドポイント一覧
| メソッド | パス | 説明 | レスポンス |
|---|---|---|---|
| GET |
/api/v1/stores/{storeId}/coupons/
|
クーポンを一覧取得
既定では有効なもののみ。includeInactive=true で取り下げ済みも含めます。
|
200 |
| GET |
/api/v1/stores/{storeId}/coupons/{couponId}
|
クーポン詳細を取得
割引内容・有効期間・残り利用可能数を取得します。
|
200 404 |
| POST |
/api/v1/stores/{storeId}/coupons/
|
クーポンを作成
作成すると、その店舗をお気に入り登録している利用者に通知が届きます。
|
200 400 |
| PUT |
/api/v1/stores/{storeId}/coupons/{couponId}
|
クーポンを更新
利用回数以外を更新します。利用回数は消込が管理するため書き換えられません。
|
200 400 404 |
| DELETE |
/api/v1/stores/{storeId}/coupons/{couponId}
|
クーポンを取り下げる
無効化します。消込の履歴は残ります。
|
200 404 |
| POST |
/api/v1/stores/{storeId}/coupons/verify
|
コードを検証（消込なし）
受け付けられるかを返します。理由は not_found / inactive / not_yet_valid / expired / fully_used。
|
200 400 |
| POST |
/api/v1/stores/{storeId}/coupons/redeem
|
クーポンを消込
1回分を消費し、消込記録を残します。上限に達している場合は409。
|
200 400 409 |
| GET |
/api/v1/stores/{storeId}/coupons/redemptions
|
消込履歴を取得
新しい順。couponId で1つのクーポンに絞り込めます。
|
200 |
エンドポイント詳細
既定では有効なもののみ。includeInactive=true で取り下げ済みも含めます。
完全パス：
GET /api/v1/stores/{storeId}/coupons/
レスポンスコード：
200
割引内容・有効期間・残り利用可能数を取得します。
完全パス：
GET /api/v1/stores/{storeId}/coupons/{couponId}
レスポンスコード：
200
404
作成すると、その店舗をお気に入り登録している利用者に通知が届きます。
完全パス：
POST /api/v1/stores/{storeId}/coupons/
レスポンスコード：
200
400
利用回数以外を更新します。利用回数は消込が管理するため書き換えられません。
完全パス：
PUT /api/v1/stores/{storeId}/coupons/{couponId}
レスポンスコード：
200
400
404
無効化します。消込の履歴は残ります。
完全パス：
DELETE /api/v1/stores/{storeId}/coupons/{couponId}
レスポンスコード：
200
404
受け付けられるかを返します。理由は not_found / inactive / not_yet_valid / expired / fully_used。
完全パス：
POST /api/v1/stores/{storeId}/coupons/verify
レスポンスコード：
200
400
1回分を消費し、消込記録を残します。上限に達している場合は409。
完全パス：
POST /api/v1/stores/{storeId}/coupons/redeem
レスポンスコード：
200
400
409
新しい順。couponId で1つのクーポンに絞り込めます。
完全パス：
GET /api/v1/stores/{storeId}/coupons/redemptions
レスポンスコード：
200
リクエスト例
リクエスト
POST /api/v1/stores/{storeId}/coupons/redeem?organizationId={organizationId}
Authorization: Bearer {access_token}
{
"code": "SUMMER20",
"customerId": "cus-123"
}
レスポンス
{
"succeeded": true,
"reason": "ok",
"remainingUses": 49,
"redemption": {
"redemptionId": "25…_9f",
"couponCode": "SUMMER20",
"discountType": "Percentage",
"discountValue": 20,
"redeemedAt": "2026-08-26T04:12:00Z"
}
}
認証について
このAPIを利用するには、Authorization: Bearer {access_token} ヘッダーが必要です。トークンの取得方法は認証ガイドをご確認ください。