ユーザークーポンAPI
コンシューマー（エンドユーザー）向けのクーポンAPIです。お気に入り店舗のクーポン一覧・詳細の取得（user.coupons.read）と、アカウントへの受け取り、お会計での使用、使用の取り消し（user.coupons.write）に対応しています。
api/v1/user/coupons
APIリファレンスで確認
エンドポイント一覧
| メソッド | パス | 説明 | レスポンス |
|---|---|---|---|
| GET |
/api/v1/user/coupons/
|
クーポン一覧を取得（お気に入り店舗から）
ユーザーのお気に入り店舗のアクティブなクーポンを一括取得します。有効期限が近い順に返します。スコープ: user.coupons.read
|
200 401 403 |
| GET |
/api/v1/user/coupons/{storeId}/{couponId}
|
クーポン詳細を取得
店舗IDとクーポンIDを指定して単一クーポンの詳細を取得します。スコープ: user.coupons.read
|
200 404 401 |
| GET |
/api/v1/user/coupons/mine
|
受け取ったクーポンの一覧
このアカウントが受け取ったクーポンを、すべての店舗について返します。未使用（有効期限が近い順）、使用済み（新しい順）の順です。各クーポンにアカウント固有のコード（issuedCode）と、使用済みなら usedAt・undoUntil が入ります。スコープ: user.coupons.read
|
200 401 403 |
| POST |
/api/v1/user/coupons/{storeId}/{couponId}/claim
|
クーポンを受け取る
クーポンをこのアカウントに発行します。受け取り済みなら同じものを返すため、再送しても2枚にはなりません。受け取れないクーポンは 404 {"error":"unavailable"}。スコープ: user.coupons.write
|
200 404 401 403 |
| POST |
/api/v1/user/coupons/{storeId}/{couponId}/use
|
お会計でクーポンを使う
店員の目の前で押す操作です。未受け取りなら受け取ってから使用します。使用済みは 409 already_used、繰り返し利用可のクーポンは使用状態を持たないため 409 reusable、期限切れ・停止中は 404 expired / inactive。返る usedAt で経過時間つきの使用済み表示を出してください。スコープ: user.coupons.write
|
200 404 409 401 403 |
| POST |
/api/v1/user/coupons/{storeId}/{couponId}/use/undo
|
使用を取り消す
押し間違いを、使用から10分以内（undoUntil まで）に取り消します。取り消した記録は残ります。未使用は 409 not_used、期限を過ぎたら 409 window_passed。スコープ: user.coupons.write
|
200 404 409 401 403 |
エンドポイント詳細
ユーザーのお気に入り店舗のアクティブなクーポンを一括取得します。有効期限が近い順に返します。スコープ: user.coupons.read
GET /api/v1/user/coupons/
店舗IDとクーポンIDを指定して単一クーポンの詳細を取得します。スコープ: user.coupons.read
GET /api/v1/user/coupons/{storeId}/{couponId}
このアカウントが受け取ったクーポンを、すべての店舗について返します。未使用（有効期限が近い順）、使用済み（新しい順）の順です。各クーポンにアカウント固有のコード（issuedCode）と、使用済みなら usedAt・undoUntil が入ります。スコープ: user.coupons.read
GET /api/v1/user/coupons/mine
クーポンをこのアカウントに発行します。受け取り済みなら同じものを返すため、再送しても2枚にはなりません。受け取れないクーポンは 404 {"error":"unavailable"}。スコープ: user.coupons.write
POST /api/v1/user/coupons/{storeId}/{couponId}/claim
店員の目の前で押す操作です。未受け取りなら受け取ってから使用します。使用済みは 409 already_used、繰り返し利用可のクーポンは使用状態を持たないため 409 reusable、期限切れ・停止中は 404 expired / inactive。返る usedAt で経過時間つきの使用済み表示を出してください。スコープ: user.coupons.write
POST /api/v1/user/coupons/{storeId}/{couponId}/use
押し間違いを、使用から10分以内（undoUntil まで）に取り消します。取り消した記録は残ります。未使用は 409 not_used、期限を過ぎたら 409 window_passed。スコープ: user.coupons.write
POST /api/v1/user/coupons/{storeId}/{couponId}/use/undo
リクエスト例
GET /api/v1/user/coupons
Authorization: Bearer {access_token}
[
{
"storeId": "store-abc",
"storeName": "ファミリーマート 新宿店",
"couponId": "cpn-001",
"name": "コーヒー100円引き",
"code": "COFFEE100",
"discountType": "Fixed",
"discountValue": 100,
"validUntil": "2026-04-30T23:59:59Z",
"isExpired": false,
"isFullyUsed": false
}
]
認証について
このAPIを利用するには、Authorization: Bearer {access_token} ヘッダーが必要です。トークンの取得方法は認証ガイドをご確認ください。