Klaviyo Integration: Events & Payloads
OVERVIEW
This article details the events and payloads available to merchants through the Loop / Klaviyo integration.
Events
There are 18 events that Loop can send to Klaviyo via the Loop <> Klaviyo integration. These are:
Return created: When a return is submitted by the customer via the shopper return portal
Return status updated: When the status of a return changes (e.g. open, closed, cancelled)
Label created: When a label is successfully generated by a carrier (e.g. USPS, FedEx)
Label updated: When the tracking status of a label is updated (e.g. new, in transit, delivered)
Label resend request: When a Loop admin user clicks a button to resend a return confirmation
Return method created: When a customer creates a non-box and ship return, e.g. a Happy Returns return, and contains information specific to that return method
Gift return request: When a customer submits a gift return request
Exchange out of stock: When we attempt to place a return order and an exchange item is not available
Out of stock resolved: When we resolve an Out of Stock issue either by issuing a refund or a gift card
Return expiring: When a return is 21 days old but has not yet been shipped (7 days until expiry)
Return expired: When a return is 28 days old but has not been shipped (label is expired)
Payment transaction: When we take a customer payment via Stripe during a Shop Now transaction
Refund transaction: When we refund a customer's Stripe payment following a return of an exchange
Instant Exchange notice: When a customer has initiated a return with an instant exchange on it
Instant Exchange reminder: Sent twice, once when a return with an instant exchange is 7 days out from the charge date, but the label is not yet in transit, and one more time the day before the charge date, provided the label is not yet in transit
Shop Later offer: Sent within 24 hours of a Shop Later eligible return being created
Warranty claim rejected: Sent when a merchant rejects a customer's warranty claim
Deep link created: Sent when a merchant sends a customer a return deeplink from the Find an order page in the Loop admin
Events are saved as custom metrics within the corresponding customer's Klaviyo profile.
Payloads
By default, each event contains the following fields in its payload:
event_id
brand_image
instant_exchange_capture_date
keep_item (boolean)
label
label_updated
labels_enabled (boolean)
order
outcome
primary_color
return_by
return_date
return_destination:
name
street_address
city
state
zip
country
country_code
phone
return_id (number)
return_method: (will read None if return is box and ship or Keep Item)
id
return_id
address_id
type
name
qr_code_url
rma_code
state
meta (array)
scheduled_at (null when not applicable)
expires_at
created_at
updated_at
deleted_at
scannable_id
address (array, the drop-off location's address)
return_policy:
title
exchanges_enabled (boolean)
exchange_processing_event
refunds_enabled (boolean)
refund_processing_event
gift_cards_enabled (boolean)
gift_card_processing_event
keep_item_enabled (boolean)
keep_item_process_immediate (boolean)
return_reason_parents
return_reasons
return_status
returned_product_images
returned_product_names
returned_product_skus
returned_product_types
returned_product_variant_titles
status_page_url
support_email
tracking_carrier
tracking_number
tracking_status
tracking_url
All fields are strings (or an array of strings) unless otherwise noted.
Additional fields
The following events have additional or modified fields in their payload.
Return method created
This is a key event for merchants leveraging the Happy Returns or Veho return methods.
Follows the same payload structure as most other events. Will only fire when the customer has chosen a non-box and ship return method, e.g. Happy Returns or Veho. The return_method field will always be populated with this trigger.
Exchange out of stock
In the event an exchange item out of stock, the following fields will contain only the items that are out of stock and unable to be fulfilled:
product_names
product_images
product_variant_titles
product_skus
Out of stock resolved
When we resolve an out of stock issue, we will also include only the items that are out of stock, as well as the outcome of the resolution (refund or gift card).
product_names
product_images
product_variant_titles
out_of_stock_outcome
Payment transaction
Includes the following additional fields:
payment_taken
charge_amount (number)
charge_currency
charge_amount_formatted
card_type
Refund transaction
Includes the following additional fields:
refund_processed
refund_amount (number)
refund_currency
refund_amount_formatted
Gift return request
The Gift Return Request does not use the standard payload above; instead the fields are based on a form the customer fills out when submitting a return:
gifter
product_return
product_request
shipping_address_address
shipping_address_city
shipping_address_zip
shipping_address_state
shipping_address_country
shipping_address_phone
gift_info
question1
question2
question3
question4
Shop Later offer
Includes the following additional fields:
shop_later: (array)
conversion_url
formatted_credit_amount (number)
formatted_refund_amount (number)
currency_code
line_items: (array)
formatted_price
image
title
variant_title
Deep link created
The Deep link created event does not use the standard payload above; instead the fields are just the below:
deep_link_url
order
Loop Order Tracking
Below are possible values for "status" in the Klaviyo Metric Loop Order Tracking Updated. Learn more about Loop Order Tracking.
Most common:
label_created
pre_transit (carrier has received the package)
in_transit
out_for_delivery
delivered
Less common:
available_for_pickup (if a customer opted to have their package sent to a pick up location)
Statuses that indicate issues. In most cases, these shipments will not reach the customer.
error
failure
return_to_sender
Very rare and not relevant to your customers
new
unknown
Please reach out to support@loopreturns.com with any additional questions.