Klaviyo Integration: Events & Payloads


There are 18 events that Loop can send to Klaviyo via the Loop <> Klaviyo integration. These are: 

  1. Return created: When a return is submitted by the customer via the Returns Portal
  2. Return status updated: When the status of a return changes (e.g. open, closed, cancelled) 
  3. Label created: When a label is successfully generated by a carrier (e.g. USPS, FedEx)
  4. Label updated: When the tracking status of a label is updated (e.g. new, in transit, delivered)
  5. Label resend request: When a Loop admin user clicks a button to resend a return confirmation
  6. 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
  7. Gift return request: When a customer submits a gift return request
  8. Exchange out of stock: When we attempt to place a return order and an exchange item is not available
  9. Out of stock resolved: When we resolve an Out of Stock issue either by issuing a refund or a gift card
  10. Return expiring: When a return is 21 days old but has not yet been shipped (7 days until expiry)
  11. Return expired: When a return is 28 days old but has not been shipped (label is expired) 
  12. Payment transaction: When we take a customer payment via Stripe during a Shop Now transaction
  13. Refund transaction: When we refund a customer's Stripe payment following a return of an exchange
  14. Instant Exchange notice: When a customer has initiated a return with an instant exchange on it
  15. 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
  16. Shop Later offer: Sent within 24 hours of a Shop Later eligible return being created
  17. Warranty claim rejected: Sent when a merchant rejects a customer's warranty claim
  18. 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. 


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
Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.