コンテンツにスキップ

クーポン新規作成API

概要

POSTされたデータを使用して、新しくクーポンを作成します。

URL

/cmapi/v2/coupons/

メソッド

POST

リクエスト

リクエストパラメータ

なし

リクエストボディ

基底オブジェクト

キー 必須 デフォルト 許容値 説明 詳細 備考
providers 数値配列 - [] 数値 クーポン利用可能店舗ID 利用可能店舗のIDを指定。

指定がない(空配列)場合は「全店舗」となる。
※ 配列内には数値が1つのみ指定可能。
is_distributable 真偽値 o - - 限定クーポンとするかどうか true:限定クーポン
false:通常クーポン
-
name 文字列 o - 1文字以上30文字以下 クーポン名 - 推奨 20文字以内
short_description 文字列 o - 1文字以上100文字以下 クーポン概要説明 - 推奨 60文字以内
description 文字列 - "" 1000文字以内 クーポン利用条件 - -
priority 数値 - 0 9999以下 表示順ポイント クーポン一覧画面での表示優先順位。値の大きい順に上から表示される。 -
user_usable_count 数値 - null 1以上 1人あたり使えるクーポン枚数 1人が1つのクーポンを使用可能な回数。

null を指定した場合は「無制限」となる。
-
total_usable_count 数値 - null 1以上 クーポン利用上限枚数 全ユーザに対する、1つのクーポンの利用上限枚数。

null を指定した場合は「無制限」となる。
-
user_distributable_count 数値 - 0 1以上 【限定クーポン用パラメータ】
1人あたり配布できるクーポン枚数
1人に配布可能な1つの限定クーポンの枚数。

限定クーポンの場合は、指定必須 null 不可。
通常クーポンの場合は、利用されません。
total_distributable_count 数値 - null 1以上 【限定クーポン用パラメータ】
全体のクーポン配布上限枚数
全ユーザに対する、1つの限定クーポンの配布上限枚数。

null の場合は「無制限」となる。
通常クーポンの場合は、利用されません。
visible_start_at 文字列 o - - 表示開始日時 「yyyy-mm-dd hh:MM:ss」の形式で指定。 -
visible_end_at 文字列 o - - 表示終了日時 「yyyy-mm-dd hh:MM:ss」の形式で指定。 -
usable_start_at 文字列 o - - 有効開始日時 「yyyy-mm-dd hh:MM:ss」の形式で指定。 -
usable_end_at 文字列 o - - 有効終了日時 「yyyy-mm-dd hh:MM:ss」の形式で指定。 -
usable_days 数値 - null 0以上 【限定クーポン用パラメータ】
配布後有効日数
限定クーポンを受け取った時点を起点とした限定クーポンの有効期限を設定する。「配布後有効日数」より「有効終了日時」が優先される。

nullを指定した場合は、配布後有効期限無しとなる。
通常クーポンの場合は、利用されません。

有効日数が適用される場合の時刻は「23:59:59」までとなる。
is_open 真偽値 - false - ステータス ユーザにクーポンを公開するか、非公開とするかのステータス。

true : 公開
false : 非公開
「非公開」の場合、ユーザには表示されない。
additional_items オブジェクト o - - 任意追加項目 「リクエスト "additional_items" オブジェクト」を参照。 -

リクエスト "additional_items" オブジェクト

  • "additional_items" には、 FANSHIP システム公式の 5 項目の他に、ユーザ独自の項目を付与することが可能です。
    • ユーザ独自の項目が付与されていた場合、"additional_items" に値が登録されます。
  • "additional_items" オブジェクト内のキー名の命名規則については次の通り(value については特に制限を設けません)。
    • FANSHIP システム : [A-Za-z][A-Za-z0-9_\-]*
    • ユーザ独自 : _[A-Za-z0-9_\-]+

※ユーザ独自項目(以下記載の 5 項目以外)をご利用される場合は、必ずご相談ください。

キー 必須 デフォルト 最大 説明 詳細 備考
image 文字列 - - - クーポン画像 クーポン画像データのフルパス(https:// .... )を指定。 画像指定に関する仕様については「画像登録」シートを参照。
thumbnail 文字列 - - - サムネイル サムネイル画像データのフルパス(https:// ... )を指定。 画像指定に関する仕様については「画像登録」シートを参照。
couponCode 文字列 - - 20 クーポンコード 英数字のみ指定可能。
クーポンの利用時に認証コードの入力を必須とする場合に設定。
couponCode と couponCodeList はどちらか一方しか登録できない。
couponCodeList 文字配列 - - 20 (クーポンコード 1 件あたり) クーポンコードリスト 英数字のみ指定可能。
クーポンの利用時に認証コードの入力を必須とする場合に設定。
リスト形式で、クーポンコードを最大 2,000 件まで登録可能。
couponCode と couponCodeList はどちらか一方しか登録できない。
couponCodeVisible 真偽値 - - - クーポンコード表示設定 クーポンコードをアプリ画面に表示するかどうか。

true : 表示
false : 非表示
couponCode または couponCodeList を指定した場合は必須。
couponCodeList を指定した場合、リストの要素が 1 件である時のみ true を設定可能。

リクエストのサンプル

{
    "providers": [1],
    "is_distributable": true,
    "name": "クーポン名",
    "short_description": "概要説明",
    "description": "詳細説明",
    "priority": 1,
    "user_usable_count": 1,
    "total_usable_count": 1,
    "user_distributable_count": 1,
    "total_distributable_count": 10000,
    "visible_start_at": "2019-03-26 00:00:00",
    "visible_end_at": "2222-12-31 23:59:59",
    "usable_start_at": "2019-03-26 00:00:00",
    "usable_end_at": "2222-12-31 23:59:59",
    "usable_days": 1,
    "is_open": false,
    "additional_items": {
        "image": "https://${domain}/storage/1/image/2019/03/26/072128329898/qJnAg8rh6C.png/",
        "thumbnail": "https://${domain}/storage/1/image/2019/03/26/072128329898/8rqgJnh6AC.png/",
        "couponCodeList": ["1234", "abc", "xxx123"],
        "couponCodeVisible": false
    }
}

レスポンス

メディアタイプ

application/json

成功時レスポンス

http status 201 を返却し、作成したリソースを指し示す Location ヘッダを返却

レスポンスのサンプル

なし