Docs
Common settings

Klaviyo integration (beta)

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

Returns and exchanges

Event nameRecorded when
BETA_requested_return_v0A return or exchange request is created (from the return portal, the admin dashboard or CSV)
BETA_approved_return_v0Items in a request are approved (including automatic approval at request time)
BETA_rejected_return_v0Approval of items in a request is rejected (including automatic rejection at request time)
BETA_received_return_v0Returned items are marked as received
BETA_refunded_return_v0A refund to the original payment method is marked as refunded (not recorded for store credit refunds or rejected refunds)
BETA_shipped_exchange_v0Exchange 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.

Event nameNew 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

PropertyDescriptionExample
return_idRecustomer return number5424
rma_numberReturn request ID#1001_01
order_numberOrder number#1001
itemsList of items (see the table below)
request_channelWhere the request was made. Request events onlyreturn_portal (return portal), merchant_dashboard (admin dashboard), csv_import (CSV)
refund_amountConfirmed refund amount. Refund events only1000.0
refund_currencyCurrency of the refund amount. Refund events only. null if the currency cannot be determinedJPY

Each item in items has the following properties.

PropertyDescriptionExample
product_nameProduct nameT-shirt White / M
skuSKUTS-WH-M
priceItem price3300.0
currencyCurrency of the priceJPY
image_urlProduct image URL. Not included in exchange shipment events
reject_reasonReason for not approving. Rejection events only
arrival_dateDate the returned item arrived (YYYY-MM-DD). Receipt events only2026-01-01

Delivery events

PropertyDescriptionExample
order_numberOrder number#1001
tracking_numberTracking number123456789012
carrierCarrieryamato, sagawa, jp, seino_unyu, eco_hai, dhl, ninjavan, askullogist, global, others
itemsList of shipped items. Each element has product_name, sku, quantity, price, currency and image_url
delivered_dateDelivery date (YYYY-MM-DD, Japan time). Delivered events only2026-01-01
delivered_atDelivery date and time (Japan time). Delivered events only. null if the carrier does not provide the time2026-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

  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

MessageWhat to do
This Klaviyo account is connected to another storeConnect with a different Klaviyo account
This store is connected to a different Klaviyo accountTo change the account, disconnect first
The connection was removed in Klaviyo or has expiredConnect again from "Connect again"
Additional permissions are requiredFrom "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. 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).

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
© Recustomer, Inc.