マーケティング担当者向け

クーポンAPI

クーポンの作成・編集・取り下げと、レジでの検証・消込を行います。消込は記録として残り、発行枚数の上限も守られます。

api/v1/stores/{storeId}/coupons View in API Reference

Endpoints

Method Path Description Response
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

Endpoint details

既定では有効なもののみ。includeInactive=true で取り下げ済みも含めます。

Full path: GET /api/v1/stores/{storeId}/coupons/
Response codes: 200

割引内容・有効期間・残り利用可能数を取得します。

Full path: GET /api/v1/stores/{storeId}/coupons/{couponId}
Response codes: 200 404

作成すると、その店舗をお気に入り登録している利用者に通知が届きます。

Full path: POST /api/v1/stores/{storeId}/coupons/
Response codes: 200 400

利用回数以外を更新します。利用回数は消込が管理するため書き換えられません。

Full path: PUT /api/v1/stores/{storeId}/coupons/{couponId}
Response codes: 200 400 404

無効化します。消込の履歴は残ります。

Full path: DELETE /api/v1/stores/{storeId}/coupons/{couponId}
Response codes: 200 404

受け付けられるかを返します。理由は not_found / inactive / not_yet_valid / expired / fully_used。

Full path: POST /api/v1/stores/{storeId}/coupons/verify
Response codes: 200 400

1回分を消費し、消込記録を残します。上限に達している場合は409。

Full path: POST /api/v1/stores/{storeId}/coupons/redeem
Response codes: 200 400 409

新しい順。couponId で1つのクーポンに絞り込めます。

Full path: GET /api/v1/stores/{storeId}/coupons/redemptions
Response codes: 200

Example request

Request 
POST /api/v1/stores/{storeId}/coupons/redeem?organizationId={organizationId}
Authorization: Bearer {access_token}

{
  "code": "SUMMER20",
  "customerId": "cus-123"
}
Response 
{
  "succeeded": true,
  "reason": "ok",
  "remainingUses": 49,
  "redemption": {
    "redemptionId": "25…_9f",
    "couponCode": "SUMMER20",
    "discountType": "Percentage",
    "discountValue": 20,
    "redeemedAt": "2026-08-26T04:12:00Z"
  }
}
About authentication

To use this API, the Authorization: Bearer {access_token} header is required. See the authentication guide for how to obtain a token.

View the authentication & access API
To API Reference