# Klaviyo integration (beta)

> Common settings

Once you connect Klaviyo, returns, exchanges and deliveries that happen in Recustomer are recorded as events on your customers' profiles in Klaviyo. You can use these events to trigger Klaviyo flows (automated emails) and as conditions in segments.

> **注意: This feature is in beta**
>
> The Klaviyo integration is in beta.
>
> - Only stores invited by Recustomer can use it
> - Event names and properties may change. When they change, we send them as a separate event with a higher version at the end of the name (`_v0`), and let you know in advance
> - Please report issues and requests to your Recustomer contact

1. [Recorded events](#1-recorded-events)

2. [Event properties](#2-event-properties)

3. [How to connect](#3-how-to-connect)

4. [Sample events sent right after connecting](#4-sample-events-sent-right-after-connecting)

5. [Notes](#5-notes)

## 1. Recorded events

### Returns and exchanges

| Event name | Recorded when |
| --- | --- |
| `BETA_requested_return_v0` | A return or exchange request is created (from the return portal, the admin dashboard or CSV) |
| `BETA_approved_return_v0` | Items in a request are approved (including automatic approval at request time) |
| `BETA_rejected_return_v0` | Approval of items in a request is rejected (including automatic rejection at request time) |
| `BETA_received_return_v0` | Returned items are marked as received |
| `BETA_refunded_return_v0` | A refund to the original payment method is marked as refunded (not recorded for store credit refunds or rejected refunds) |
| `BETA_shipped_exchange_v0` | Exchange items are marked as shipped |

Approval, rejection, receipt and exchange shipment events are sent once per operation, not once per item. For example, if you approve several items at once, those items are all included in the `items` of a single event.

### Deliveries

Recorded when the delivery status of a shipment changes, for stores that use delivery tracking. For the meaning of each status, see the [mapping to carrier statuses](../tracking/faq.html).

| Event name | New delivery status |
| --- | --- |
| `BETA_info_received_fulfillment_v0` | 荷物受付け (Info received) |
| `BETA_in_transit_fulfillment_v0` | 配送中 (In transit) |
| `BETA_available_for_pickup_fulfillment_v0` | 受取可能 (Available for pickup) |
| `BETA_delivered_fulfillment_v0` | お届け完了 (Delivered) |
| `BETA_attempt_fail_fulfillment_v0` | ご不在のため持ち戻り (Delivery attempt failed) |
| `BETA_exception_fulfillment_v0` | 配送トラブル (Exception) |
| `BETA_expired_fulfillment_v0` | 保管期限の超過 (Expired) |

Each delivery event is recorded only once per shipment, the first time the shipment reaches that status. It is not recorded again when the shipment goes back to in transit after a failed attempt, or on a second failed attempt.

### Whose profile

Events are recorded on the profile of the customer's email address on the order or request. Orders and requests without an email address are not recorded.

## 2. Event properties

In the body of a Klaviyo email, you can insert values by property name, such as `{{ event.order_number }}`. Properties without a value are `null`.

The list of items (`items`) is shown one item at a time. The part between `{% for item in event.items %}` and `{% endfor %}` is repeated for each item, and inside it you write `item.` followed by an item property name, such as `{{ item.product_name }}`.

```
{% for item in event.items %}
{{ item.product_name }} ({{ item.sku }})
{% endfor %}
```

### Return and exchange events

| Property | Description | Example |
| --- | --- | --- |
| `return_id` | Recustomer return number | `5424` |
| `rma_number` | Return request ID | `#1001_01` |
| `order_number` | Order number | `#1001` |
| `items` | List of items (see the table below) | |
| `request_channel` | Where the request was made. Request events only | `return_portal` (return portal), `merchant_dashboard` (admin dashboard), `csv_import` (CSV) |
| `refund_amount` | Confirmed refund amount. Refund events only | `1000.0` |
| `refund_currency` | Currency of the refund amount. Refund events only. `null` if the currency cannot be determined | `JPY` |

Each item in `items` has the following properties.

| Property | Description | Example |
| --- | --- | --- |
| `product_name` | Product name | `T-shirt White / M` |
| `sku` | SKU | `TS-WH-M` |
| `price` | Item price | `3300.0` |
| `currency` | Currency of the price | `JPY` |
| `image_url` | Product image URL. Not included in exchange shipment events | |
| `reject_reason` | Reason for not approving. Rejection events only | |
| `arrival_date` | Date the returned item arrived (YYYY-MM-DD). Receipt events only | `2026-01-01` |

### Delivery events

| Property | Description | Example |
| --- | --- | --- |
| `order_number` | Order number | `#1001` |
| `tracking_number` | Tracking number | `123456789012` |
| `carrier` | Carrier | `yamato`, `sagawa`, `jp`, `seino_unyu`, `eco_hai`, `dhl`, `ninjavan`, `askullogist`, `global`, `others` |
| `items` | List of shipped items. Each element has `product_name`, `sku`, `quantity`, `price`, `currency` and `image_url` | |
| `delivered_date` | Delivery date (YYYY-MM-DD, Japan time). Delivered events only | `2026-01-01` |
| `delivered_at` | Delivery date and time (Japan time). Delivered events only. `null` if the carrier does not provide the time | `2026-01-01T12:00:00+09:00` |

## 3. How to connect

Each store can connect one Klaviyo account, and a Klaviyo account cannot be connected to more than one store.

1. In Recustomer, go to [Settings > External service integrations > Integrations > Klaviyo](https://rcmr.io/settings/integrations/integration/externals/klaviyo)

2. Click "Connect to Klaviyo"

3. You are taken to Klaviyo. Log in to the Klaviyo account you want to connect and allow access

   Recustomer only asks for permission to read account information and to write events. It does not read your customers' profiles or lists.

   ※If "App has not been reviewed" is shown, click "Continue"

4. You return to Recustomer. The connection is complete when "Connected to Klaviyo" is shown

   The connected Klaviyo account name, account ID and connection time are shown.

To disconnect, click "Disconnect integration" on the same page.

### If you cannot connect

| Message | What to do |
| --- | --- |
| This Klaviyo account is connected to another store | Connect with a different Klaviyo account |
| This store is connected to a different Klaviyo account | To change the account, disconnect first |
| The connection was removed in Klaviyo or has expired | Connect again from "Connect again" |
| Additional permissions are required | From "Connect again", allow all permissions |

## 4. Sample events sent right after connecting

When you build flows or segments in Klaviyo, you cannot pick an event from the list until at least one has arrived. So when the connection is completed, Recustomer sends one sample of each of the 13 events in [1. Recorded events](#1-recorded-events). This lets you start building flows right after connecting, even before any real returns, exchanges or deliveries.

- The samples are recorded on a profile named "Recustomer 見本" (Recustomer sample)
- The sample order number is `#1001` and the product name is "見本の商品" (sample product). The properties include `is_sample: true`
- This profile has no email address or phone number, so no email or SMS is sent even if your flows are live
- Connecting again does not add more samples

> **注意: The sample profile is counted in segments**
>
> The sample profile is counted in segments that use Recustomer events as conditions. To exclude it, add a condition to the segment: "Properties about someone", "First Name" doesn't equal "Recustomer 見本".

Profiles without an email address are not counted toward Klaviyo's "Profiles and Email" plans ([Klaviyo Help Center](https://help.klaviyo.com/hc/en-us/articles/115000976672)).

## 5. Notes

- Events from while you are not connected (before you connect, while disconnected, or while the connection is lost) do not reach Klaviyo and are not sent later
- The same event is recorded in Klaviyo only once
- Return and exchange events are usually recorded within a few minutes of the operation. Delivery events are recorded when delivery tracking retrieves the delivery status
