Shopifyのポイントアプリ（easyPoints）を入れた案件で、初回購入特典をFlowで組んだときの理解ログ。 結論だけ見れば「タグで付与済みを管理する」だけの話なんだけど、 そこに行き着くまでに、自分の思い込みが3回崩れたので残しておく。

発端：新規会員登録特典が使えなかった

やりたかったのは「初めて買ってくれた人に500pt」。 アプリの標準機能には「新規会員登録特典」があるので、最初はそれで行けると思っていた。

無理だった。ストアが新しいお客様アカウント（メールにコードが飛んでくる方式）だったから。 開発元の回答は「登録時の付与はできない。ただし初回購入時ならShopify Flowで実現できる」。

ここで頭の中がこう切り替わった。

× 会員登録したとき → ポイント
○ 初めて買ってくれたとき → ポイント

同じ「初回特典」でも、フックするタイミングを別のイベントに置き換えるという発想。 これは他のアプリ制約でも使えそうなので覚えておきたい。

前提

Shopify Flow が入っていること（無料）

easyPoints が入っていて、Flow連携のアクションが使えること

顧客タグを運用で触らないこと（後述）

1. ワークフローを作る

Flow → ワークフローを作成 → トリガーに Order fulfilled を選ぶ。

「注文作成」ではなく「発送済み」にしているのは、キャンセルされた注文にポイントを付けないため。 代わりに分割出荷で複数回起動するので、あとの条件とキーで受け止める。

2. 条件（Condition）を2つ、ANDで置く

Customer number of orders <= 1 AND Customer tags doesn’t contain 初回特典付与済み

​

== 1

ではなく

<= 1

にする。テスト注文は注文回数に数えられず0になるため

実際に保存される式はこうなる（UIでは「等しい」に見えることがある）

((order.customer.numberOfOrders <= 1) && (order.customer.tags none? |tags_item| (tags_item == ‘初回特典付与済み’)))

​

3. True の分岐に easyPoints のアクションを置く

Adjust Point Balance を追加して、4つのフィールドを埋める。

フィールド	入れる値	意味
Customer ID	{{ order.customer.id }}	誰に付けるか
Point Value	500	付けるポイント数
Note	初回購入ボーナス	ポイント履歴に残る理由
Idempotency Key	{{ order.id | remove: “gid://shopify/Order/” }}	同じ注文で二重に付けないためのキー

Idempotency Key は、注文IDから

gid://shopify/Order/

を取り除いて数字だけにしている。 同じキーで2回来たら、アプリ側が「もう処理した」と判断して弾いてくれる。

4. その下に Add customer tags を置く

タグは

初回特典付与済み

。条件で使う文字列と完全に一致させる。

5. 保存して、ワークフローをオンにする

作っただけでは動かない。ステータスが「アクティブ」になっているか確認する。

6. 動かして、3か所を見る

Flow の「最近の実行」：結果が「完了2件」なら、付与とタグ付けの2アクションが走っている

easyPoints の履歴：付与されたポイント数と有効期限

顧客ページのタグ：

初回特典付与済み

が付いたか

分割出荷を試すなら、1つの注文の商品を別々に発送済みにして、 2回目・3回目の実行結果が「なし」になり、ポイントが増えないことを見る。

二重付与を防ぐ仕組みは2段ある

役割が違うので、どちらも入れておく。

仕組み	防げる範囲
Idempotency Key	同じ注文の中での重複（＝分割出荷で複数回起動したとき）
顧客タグ	別の注文をまたいだ重複（＝2回目の注文でまた初回特典が付く）

※今回のテストでは3回目の実行が条件で止まったので、 キーとタグのどちらが効いたかまでは切り分けていない。

やり直したいとき

顧客ページからタグ

初回特典付与済み

を消す → もう一度付与される状態に戻る

付いてしまったポイントは、easyPoints 側で手動調整する

同じ注文でやり直す場合、Idempotency Key が同じだと弾かれる可能性がある（未検証）

運用で決めておくこと

ポイントが付くのは注文時ではなく発送時。お客様への案内文に影響する

顧客タグを手で消さない。消すともう一度もらえる

ポイント数を変えるときは Point Value を書き換えるだけ

購入金額に応じた通常ポイントは別の仕組み。アプリ側でポイントプログラムを開始しないと動かない