OVERVIEW

This article details the events and payloads available to merchants through the Loop / Klaviyo integration.

There are 20 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 shopper return 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

19. Gift receipt created: Sent when a gift receipt is created for a return.

20. Line item rejected: Sent when a return with a rejected line item is processed, with the option to notify the customer checked.

Events are saved as custom metrics within the corresponding customer's Klaviyo profile.

Note: These events must have occurred in Loop (so that the webhook has sent to Klaviyo) in order for them to show as available metrics to select in Klaviyo

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.

The following events have additional or modified fields in their payload.

This is a key event for merchants leveraging Happy Returns.

Follows the same payload structure as most other events. Will only fire when the customer has chosen a non-box and ship return method, like Happy Returns. The return_method field will always be populated with this trigger.

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

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

Includes the following additional fields:

• payment_taken

• charge_amount (number)

• charge_currency

• charge_amount_formatted 

• card_type

Includes the following additional fields:

• refund_processed

• refund_amount (number)

• refund_currency

• refund_amount_formatted

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

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

The Deep link created event does not use the standard payload above; instead the fields are just the below:

• deep_link_url

• order

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

Below are the possible values for the warranty claim rejected email.

• warranty_claim

  • line_items

  • warranty_rejection_comment

The Gift Receipt Created event does not use the standard payload listed above. Instead, it returns only the following fields:

• customer_name

• deep_link_url

• sender_name

This event will only send when a return with a rejected line item on it is processed, and will only trigger if the customer notification checkbox is checked at time of processing. If a return meets the above criteria but the merchant has chosen not to notify the customer of their rejected line item, we will not send this event to Klaviyo.

Includes the following extra fields:

• line_item_rejection_comment

• rejected_items (array)

  • product_name

  • product_image

  • product_type

  • return_reason

  • return_reason_parents

  • size

  • sku

Please reach out to support@loopreturns.com with any additional questions.