# Klaviyo連携（ベータ版）

> 共通設定

Klaviyoと連携すると、返品・交換の申請や承認、返金、商品のお届けなどがあったときに、Klaviyoのお客様のプロフィールにイベントとして記録されます。記録したイベントは、Klaviyoのフロー（自動で送るメール）の起点や、セグメントの条件に使えます。

> **注意: ベータ版です**
>
> Klaviyo連携はベータ版です。
>
> - ご利用いただけるのは、Recustomerからご案内したストアだけです
> - イベントの名前と項目は、今後変わることがあります。変えるときは、名前の末尾の版（`_v0`）を上げた別のイベントとして送り、事前にご案内します
> - 不具合やご要望は、Recustomerの担当者までお知らせください

1. [記録されるイベント](#1-記録されるイベント)

2. [イベントの項目](#2-イベントの項目)

3. [連携の手順](#3-連携の手順)

4. [連携した直後に届くサンプルのイベント](#4-連携した直後に届くサンプルのイベント)

5. [補足](#5-補足)

## 1. 記録されるイベント

### 返品・交換

| イベント名 | 記録するとき |
| --- | --- |
| `BETA_requested_return_v0` | 返品・交換の申請が作られたとき（返品ポータル・管理画面・CSVのどれから作っても記録します） |
| `BETA_approved_return_v0` | 申請の商品を承認したとき（申請時の自動承認を含みます） |
| `BETA_rejected_return_v0` | 申請の商品の承認を拒否したとき（申請時の自動拒否を含みます） |
| `BETA_received_return_v0` | 返送された商品を受入済みにしたとき |
| `BETA_refunded_return_v0` | 元の支払い方法への返金を返金済みにしたとき（ストアクレジットでの返金と、返金の拒否では記録しません） |
| `BETA_shipped_exchange_v0` | 交換品を発送済みにしたとき |

承認・拒否・受入・交換品の発送のイベントは、商品ごとではなく、操作1回につき1件送ります。複数の商品をまとめて承認した場合などは、それらの商品が1件のイベントの `items` にまとめて入ります。

### 配送

配送追跡をご利用のストアで、発送の配送状況が変わったときに記録します。配送状況の意味は、[配送会社のステータスとの対応表](../tracking/faq.html)をご覧ください。

| イベント名 | 変わった先の配送状況 |
| --- | --- |
| `BETA_info_received_fulfillment_v0` | 荷物受付け |
| `BETA_in_transit_fulfillment_v0` | 配送中 |
| `BETA_available_for_pickup_fulfillment_v0` | 受取可能 |
| `BETA_delivered_fulfillment_v0` | お届け完了 |
| `BETA_attempt_fail_fulfillment_v0` | ご不在のため持ち戻り |
| `BETA_exception_fulfillment_v0` | 配送トラブル |
| `BETA_expired_fulfillment_v0` | 保管期限の超過 |

配送のイベントは、発送ごとに、それぞれの配送状況に初めて変わったときの1回だけ記録します。持ち戻りの後にもう一度配送中になったときや、2回目の持ち戻りでは記録しません。

### 記録する相手

イベントは、注文または申請のお客様のメールアドレスのプロフィールに記録します。メールアドレスが無い注文・申請では記録しません。

## 2. イベントの項目

Klaviyoのメールの本文では、`{{ event.order_number }}` のように項目の名前で値を差し込めます。値が無い項目は `null` になります。

商品の一覧（`items`）は、1つずつ取り出して並べます。`{% for item in event.items %}` と `{% endfor %}` で囲んだ部分が商品の数だけ繰り返され、その中では `{{ item.product_name }}` のように `item.` に続けて商品の項目の名前を書きます。

```
{% for item in event.items %}
{{ item.product_name }}（{{ item.sku }}）
{% endfor %}
```

### 返品・交換のイベント

| 項目 | 内容 | 例 |
| --- | --- | --- |
| `return_id` | Recustomerの返品の番号 | `5424` |
| `rma_number` | 返品申請ID | `#1001_01` |
| `order_number` | 注文番号 | `#1001` |
| `items` | 商品の一覧（下の表） | |
| `request_channel` | 申請した経路。申請のイベントだけ | `return_portal`（返品ポータル）、`merchant_dashboard`（管理画面）、`csv_import`（CSV） |
| `refund_amount` | 確定した返金額。返金のイベントだけ | `1000.0` |
| `refund_currency` | 返金額の通貨。返金のイベントだけ。通貨を確定できない場合は `null` | `JPY` |

`items` の商品ごとに、次の項目が入ります。

| 項目 | 内容 | 例 |
| --- | --- | --- |
| `product_name` | 商品名 | `Tシャツ ホワイト / M` |
| `sku` | SKU | `TS-WH-M` |
| `price` | 商品の価格 | `3300.0` |
| `currency` | 価格の通貨 | `JPY` |
| `image_url` | 商品の画像のURL。交換品の発送のイベントには入りません | |
| `reject_reason` | 承認しなかった理由。拒否のイベントだけ | |
| `arrival_date` | 返送された商品が届いた日（YYYY-MM-DD）。受入のイベントだけ | `2026-01-01` |

### 配送のイベント

| 項目 | 内容 | 例 |
| --- | --- | --- |
| `order_number` | 注文番号 | `#1001` |
| `tracking_number` | 追跡番号 | `123456789012` |
| `carrier` | 配送会社 | `yamato`、`sagawa`、`jp`、`seino_unyu`、`eco_hai`、`dhl`、`ninjavan`、`askullogist`、`global`、`others` |
| `items` | 発送した商品の一覧。要素の項目は `product_name`・`sku`・`quantity`（数量）・`price`・`currency`・`image_url` | |
| `delivered_date` | お届けの日（日本時間のYYYY-MM-DD）。お届け完了のイベントだけ | `2026-01-01` |
| `delivered_at` | お届けの日時（日本時間）。お届け完了のイベントだけ。配送会社が時刻を示していない場合は `null` | `2026-01-01T12:00:00+09:00` |

## 3. 連携の手順

連携できるKlaviyoアカウントは、1つのストアにつき1つです。1つのKlaviyoアカウントを、複数のストアと連携することもできません。

1. Recustomerの [設定 > 外部サービス連携 > 連携サービス > Klaviyo](https://rcmr.io/settings/integrations/integration/externals/klaviyo) へ移動します

2. 「Klaviyo と連携する」を押します

3. Klaviyoの画面に移るので、連携するKlaviyoアカウントにログインし、連携を許可します

   Recustomerが求める権限は、アカウント情報の読み取りと、イベントの書き込みだけです。お客様のプロフィールやリストを読み取ることはありません。

   ※「App has not been reviewed」と表示された場合は、「Continue」を押して進んでください

4. Recustomerの画面に戻り、「Klaviyo と連携しました」と表示されたら完了です

   連携したKlaviyoのアカウント名・アカウントID・連携した日時が表示されます。

連携を解除するときは、同じ画面の「連携を解除する」を押します。

### 連携できなかったとき

| 表示 | 対処 |
| --- | --- |
| この Klaviyo アカウントは、別のストアと連携しています | 別のKlaviyoアカウントで連携してください |
| このストアは、別の Klaviyo アカウントと連携しています | 連携するアカウントを変える場合は、先に連携を解除してください |
| Klaviyo 側で連携が外されたか、期限が切れました | 「もう一度連携する」から連携し直してください |
| 追加の許可が必要です | 「もう一度連携する」から、すべての権限を許可してください |

## 4. 連携した直後に届くサンプルのイベント

Klaviyoでフローやセグメントを作るときは、一度も届いたことのないイベントを一覧から選べません。そこで、連携が完了した時点で、「[1. 記録されるイベント](#1-記録されるイベント)」の13種類のイベントのサンプルを1件ずつ送ります。これにより、実際の返品・交換や配送がまだ無くても、連携した直後からフローを作り始められます。

- サンプルのイベントは、「Recustomer 見本」という名前のプロフィールに付きます
- 注文番号は `#1001`、商品名は「見本の商品」です。項目には `is_sample: true` が付きます
- このプロフィールはメールアドレスも電話番号も持たないため、フローを公開していてもメール・SMSは送られません
- 連携し直しても、サンプルのイベントは増えません

> **注意: セグメントの人数に入ります**
>
> サンプルのイベントが付いたプロフィールは、Recustomerのイベントを条件にしたセグメントの人数に入ります。除きたい場合は、セグメントの条件に「Properties about someone」で「First Name」が「Recustomer 見本」と等しくない（doesn't equal）を足してください。

メールアドレスの無いプロフィールは、Klaviyoの「Profiles and Email」プランで課金される人数に数えられません（[Klaviyoのヘルプ](https://help.klaviyo.com/hc/en-us/articles/115000976672)）。

## 5. 補足

- 連携していない間（連携する前・連携を解除している間・連携が切れている間）のイベントは、Klaviyoに届きません。後から送り直すこともありません
- 同じイベントが Klaviyo に二重に記録されることはありません
- 返品・交換のイベントは、操作してから通常数分以内に記録されます。配送のイベントは、配送追跡で配送状況を取得したときに記録されます
