# ポイント割り当て

# 全ポイント割り当て情報の取得

# ルート

以下のGETルートを使用してストア内のすべてのポイント割り当て情報を取得できます。

GET https://loyalty.slrs.io/api/shopify/point_allotments

# 引数

本ルートはページネーションされています。

# 必須パラメーター

なし

# オプションパラメーター

以下のフィルターが使用可能です:

キー	タイプ	定義
`type`	Point Allotment Type	取得する割り当てのタイプ
`before`	Timestamp	ISO8601フォーマットのタイムスタンプ, 指定した日時以前の割り当て情報のみを取得
`after`	Timestamp	ISO8601フォーマットのタイムスタンプ, 指定した日時以降の割り当て情報のみを取得

# 戻り値

以下のデータを含む配列が返されます：

キー	タイプ	定義
`uid`	String	ポイント割り当てのEasyPoints ID
`point_value`	Integer	変動したポイント数
`inserted_at`	String	ポイント割り当てがeasyPointsに挿入された日時データ（ISO8601フォーマット）
`alloted_at`	String	割り当てがeasyPoints内で実行された日時データ（ISO8601フォーマット
`type`	Point Allotment Type	easyPoints内のデータタイプ
`point_balance_uid`	String	ポイント割り当てに紐づくeasyPointsの固有ID
`allotment_cascade`	Boolean \| null	より大きな easyPoints アクションの一部であるかどうか（複数発送を含む注文の一部など）
`app_reference`	String	ポイント割り当てのソース（easyPointsもしくはSmapify）
`object`	String	ポイント割り当てに関与しているオブジェクト（line_item, rewards, etc...）
`parent`	String	ポイント割り当ての親要素. (order_number, point_story, etc...)
`points_deducted`	Integer	ポイント割り当てから差し引かれたポイント数

# 使用例

リクエストと結果の例：

curl -X GET \
 'https://loyalty.slrs.io/api/shopify/point_allotments' \
-H 'content-type: application/json' \
-H 'authorization: Basic ${API_CREDENTIALS}'

{
  "data": [
    {

      "action": "fulfillment-1",
      "allotment_cascade": null,
      "allotted_at": "2000-01-01T00:00:00.000000",
      "app_reference": "shopify_integration",
      "event_id": 1,
      "inserted_at": "2023-01-01T00:00:00.000000",
      "object": "line_item-1",
      "parent": "order-1",
      "point_balance_uid": "f715bfd4-de77-11ed-8597-787b8aae8c7a",
      "point_value": 100,
      "points_deducted": 0,
      "type": "fulfillment",
      "uid": "e94d0d42-df50-11ed-bb36-787b8aae8c7a"
    },
    {
      "action": null,
      "allotment_cascade": true,
      "allotted_at": "2023-01-01T00:00:00.000000",
      "app_reference": "shopify_integration",
      "event_id": null,
      "inserted_at": "2023-01-01T00:00:00.000000",
      "object": null,
      "parent": "point_story-2",
      "point_balance_uid": "f70bf33c-de77-11ed-9367-787b8aae8c7a",
      "point_value": 500,
      "points_deducted": 0,
      "type": "manual",
      "uid": "8a6e8036-e305-11ed-a715-787b8aae8c7a"
    }
  ]
}

# 特定の顧客のポイント割り当て情報を取得する

# ルート

以下のGETルートを利用して特定の顧客のポイント割り当て情報を取得できます。

GET https://loyalty.slrs.io/api/shopify/point_allotments/:shopify_customer_id

:shopify_customer_idの箇所に該当の顧客IDを入力してください。

例えばこのようなGETルートhttps://admin.shopify.com/store/{store_domain}/customers/1234567890では、1234567890が顧客IDに相当します.

# 引数

本ルートはページネーションされています。

# 必須パラメーター

なし

# オプションパラメーター

以下のフィルターが使用可能です:

キー	タイプ	定義
`type`	Point Allotment Type	取得するポイント割り当てのタイプ
`before`	Timestamp	ISO8601フォーマットのタイムスタンプ, 指定した日時以前の割り当て情報のみを取得
`after`	Timestamp	ISO8601フォーマットのタイムスタンプ, 指定した日時以降の割り当て情報のみを取得

# 戻り値

以下のデータが返されます:

キー	タイプ	定義
`uid`	String	ポイント割り当てのEasyPoints ID
`point_value`	Integer	変動したポイント数
`inserted_at`	String	顧客の現在のポイント有効期限日時 (ISO8601フォーマット　　　　　　　　　　　　　　　　　　)
`type`	Point Allotment Type	easyPoints内データにおけるポイント割り当てのタイプ
`point_balance`	Point Balance	ポイント残高レコードのデータ

# 使用例

リクエストと結果の例

curl -X GET \
 'https://loyalty.slrs.io/api/shopify/point_allotments/1234567890' \
-H 'content-type: application/json' \
-H 'authorization: Basic ${API_CREDENTIALS}'

{
  "data": [
    {
      "action": "fulfillment-1",
      "allotment_cascade": null,
      "allotted_at": "2024-07-01T00:00:00.000000",
      "app_reference": "shopify_integration",
      "event_id": 1,
      "inserted_at": "2023-01-01T00:00:00.000000",
      "object": "line_item-1",
      "parent": "order-1",
      "point_balance_uid": "c5390700-74ce-4381-82a6-1eeac68219b5",
      "point_value": 250,
      "points_deducted": 0,
      "type": "fulfillment",
      "uid": "ed5a7554-c76c-4f82-98bd-83739fa0fd73"
    },
    {
      "action": null,
      "allotment_cascade": true,
      "allotted_at": "2024-07-15T00:00:00.000000",
      "app_reference": "shopify_integration",
      "event_id": null,
      "inserted_at": "2023-01-01T00:00:00.000000",
      "object": null,
      "parent": "point_story-2",
      "point_balance_uid": "c5390700-74ce-4381-82a6-1eeac68219b5",
      "point_value": 900,
      "points_deducted": 0,
      "type": "manual",
      "uid": "b6fdae8b-48b1-48b2-a08c-bb866e1cd195"
    }
  ]
}

# ポイント割り当ての作成

# ルート

以下のPOSTルートを使用して単一の顧客にポイント割り当てを作成します。

POST https://loyalty.slrs.io/api/shopify/point_allotments

# 引数

# 必須引数

キー	タイプ	必須	定義
`customer_id`	String	✔️	ポイントを割り当てられる顧客のShopify ID
`point_value`	Integer	✔️	割り当てられるポイント数（プラス又はマイナス）

# オプション引数

設定した Allotment Reason は管理画面内で確認できます。

キー	タイプ	定義
`reason`	Allotment Reason	ポイント割り当ての理由

# 戻り値

以下のデータが返されます:

キー	タイプ	定義
`uid`	String	ポイント割り当てのEasyPoints ID
`point_value`	Integer	変動したポイント数
`inserted_at`	String	顧客の現在のポイント有効期限日時 (ISO8601フォーマット)
`point_balance`	Point Balance	ポイント残高レコードのデータ

# 使用例

リクエストと結果の例

curl -X POST \
 'https://loyalty.slrs.io/api/shopify/point_allotments' \
-H 'content-type: application/json' \
-H 'authorization: Basic ${API_CREDENTIALS}' \
-d '{
  "point_value": 200,
  "customer_id": "123",
  "reason": {
    "type": "test_allotment"
  }
}'

{
  "data": {
    "id": "36ce8920-4a65-11eb-98c6-000c291828e7",
    "inserted_at": "2020-12-30T06:06:53.000000",
    "point_balance": {
      "expiration_delay": 3,
      "expires_at": "2021-03-20T23:51:09.000000Z",
      "id": "123",
      "point_balance": 594
    },
    "point_value": 200
  }
}

ポイントの付与が正常に発生した上で、残高が取得できない状況の場合は201エラーと共に以下の結果が表示されます。

{
  "data": {
    "id": "36ce8920-4a65-11eb-98c6-000c291828e7",
    "inserted_at": "2020-12-30T06:06:53.000000",
    "point_value": 200
  }
}

# エラーレスポンス

point allotment createエンドポイント（ポイント割り当ての作成）からは以下のようなエラーレスポンスが返される場合があります。

{"errors": [{"status": "400", "title": "Point allotment would result in a negative balance"}]}

= ポイント残高が0より小さい値になるために生じるエラー

{"errors": [{"status": "404", "title": "Customer was not found"}]}

= 該当のIDを持つ顧客データが見つからなかった際に生じるエラー

# ポイント割り当てのタイプ

ポイント割り当てのタイプには以下のものがあります

タイプ	詳細
`coupon_reimbursement`	注文のキャンセルに伴う利用ポイントの変換
`coupon_cancellation`	クーポン利用のキャンセルに伴う利用ポイントの返還
`csv`	CSVインポートによるポイントの調整
`deletion`	ポイントの削除
`expiration`	ポイントの失効
`manual`	ストア管理者によるポイントの手動調整
`refund`	注文のキャンセル・返金に伴う獲得ポイントの差引
`api`	API経由のポイントの調整
`flow`	Shopify Flow経由のポイントの調整
`fulfillment`	注文の発送に伴うポイント付与
`tax`	消費税分に対するポイント付与
`reward`	特典によるポイントの獲得（誕生日、会員登録など）

# ポイント割り当て理由

ポイント割り当て理由のJSONは以下の内容を含みます:

キー	タイプ	定義
`type`	Allotment Reason Type	ポイント割り当て理由のタイプ
`note`	String \| null	割り当て理由に付随する詳細説明（最大255文字まで）

# ポイント割り当て理由のタイプ

タイプ	詳細
`compensation`	お客様補償
`coupon`	クーポン
`expiration`	有効期限
`fulfillment`	フィルフィルメント
`refund`	返金
`reward`	特典
`system_fix`	システム不備対応
`test_allotment`	テスト

← ポイント残高注文履歴 →