With Stay Ai's Klaviyo integration, Stay Ai passes various metrics to Klaviyo so you can use these metrics to trigger email flows and build segments. These metrics also allow you to take a deeper dive into analytics, so you can better understand where email-attributed conversions come from—new subscription purchases, recurring subscription orders, or one-time purchases.
Setting Up the Klaviyo Integration
To set up the Klaviyo integration, you will need access to the store's Klaviyo account. For the easiest setup process, log into your Klaviyo account first before proceeding with the steps below.
Open the Stay app and navigate to Account > Integrations.
Click on the button to integrate Klaviyo with Stay AI.
Click "Activate" on the modal.
You'll be redirected to Klaviyo. Select the account to integrate the Stay account with.
If the "App has not been reviewed" modal displays, click "Continue".
Click "Allow" to accept permissions and complete the integration setup. This is what allows Stay to create event metrics and send them to Klaviyo (e.g. order upcoming, subscription canceled).
Once you click "Allow", you'll be redirected back to your Stay account's Integrations page, and the setup is complete!
NOTE: When you click "Manage Integration" on the Klaviyo integration card, you should see an option to update the integration, delete the integration, or sync metrics to Klaviyo. This indicates that the integration has been successfully set up.
To sync the Stay metrics into Klaviyo so they are immediately available for merchants to create flows, click Sync Metrics to Klaviyo
Understanding Stay Metrics in Klaviyo
Metrics should already be populated in Klaviyo from step 9 in the setup above. Below are the available metrics, once triggered.
Note: Since we have updated our company name, we will eventually be updating the metrics from "Retextion" to "Stay". In the interim, those listed above are correct.
General Subscription Metrics
Below are the metrics that are relevant to all subscription types.
Retextion - Subscription Started - This metric is triggered by checkout subscription orders and indicates the creation of a new subscription
Retextion - Subscription Purchased - This metric is triggered by all subscription orders created in Shopify, including checkout subscription orders and recurring subscription orders
Tip! If you would like to build a flow that triggers only for recurring subscription orders, you can achieve that by doing the following:
Use the "Retextion - Subscription Purchased" metric to trigger the recurring subscription order flow
Add a trigger filter "orderNumber is greater than 1". This will exclude the first subscription order (aka the checkout order) from triggering this flow.
Retextion - Subscription Canceled - This metric is triggered when a customer cancels their subscription
Retextion - Subscription Paused - This metric is triggered when a customer pauses their subscription for any period of time
Retextion - Subscription Reactivated - This metric will trigger when a subscription is reactivated.
Retextion - Subscription Skipped - This metric is triggered by the 'skip next order' action being taken on the subscription
Retextion - Order Upcoming - This metric is triggered 2-5 days leading up to the next order date on a subscription
Note: By default, this metric fires 5 days before the next order.
If you've changed the default 5 days to 2-4 days in the Stay Ai Upcoming Order email setting, this Klaviyo metric will respect that as well.
To change the number of lead-up days, navigate to your Stay Ai app > Notifications > Emails > Upcoming Charge > Notification Cadence
Retextion - Promotion Applied - This metric is triggered when an ExperienceEngine promotion you've created in Stay is applied to a subscription. For more information on using this metric, please visit our article on using Klaviyo for ExperienceEngine Promotions.
Retextion - Billing Attempt Failed - This metric triggers when payments fail billing attempts
Retextion - Payment Method Expiring - This metric triggers on the first of the month for payments expiring in the following month. For example, this will fire on January 1st for payments expiring in February
Note: When building a flow off of the Payment Method Expiring metric, please add a flow filter to exclude customers with the stay_inactive is true profile property. This will ensure that customers with only canceled subscriptions will be excluded from the flow.
Retextion - Item Out Of Stock - This metric triggers when an item is identified as out of stock on a billing attempt
Retextion - Order Partially Fulfilled - This metric triggers when an order respects partial order fulfillment in Stay, and fires an order without items that are currently out of stock
Prepaid Subscription-Specific Metric
Retextion - Subscription Expired - This metric triggers when the last order in a prepaid subscription is processed through to Shopify
Retextion - First Gift Sent - This metric triggers when the first gift of a prepaid gifted subscription is ordered
Retextion - Gift Sent - This metric triggers when a prepaid gifted subscription order is fired
Retextion - Last Gift Sent - This metric triggers when the last prepaid order in a gifted subscription is fired
Digital Punch Card-Specific Metrics
Retextion - Punch Earned - This metric triggers when a customer earns 1+ punch on their punch card.
Additional properties passed with this event:
punch_card_date_earned: Date and time that the punch was earned
punch_card_issued_date: Date and time that the active punch card was issued to the customer
punch_card_punch_number: Last punch issued on the active punch card
punch_card_remaining_punches: Remaining punches on the active punch card until the most upcoming reward
punch_card_upcoming_reward: Details for the upcoming reward (Free product, discounted order or free order details)
Retextion - Award Earned - This metric triggers when a customer earns an award on their punch card
Additional properties passed with this event:
punch_card_reward_earned: Type of the reward that was earned (Free product, discounted order, free order)
punch_card_reward_earned_value: Details of the earned reward (Product/variant information, or discounted/free order details)
Retextion - Award Redeemed - This metric triggers when a customer applies an award to their subscription order
Additional properties passed with this event:
punch_card_reward_redeemed:Type of the reward that was redeemed (Free product, discounted order, free order)
punch_card_reward_redeemed_discount_code: Details of the redeemed reward (Product/variant information, or discounted/free order details)
punch_card_reward_redeemed_value: Details of the redeemed reward (Product/variant information, or the discount code that was issued)
WinbackEngine-Specific Metrics
Retextion - Winback Ready - This metric triggers when Stay's machine learning model has determined that a truly canceled subscriber is ready for winback communication
All properties that are passed on the Retextion - Subscription Cancelled metric are passed on Retextion - Winback Ready, including cancellationReasons
Additional properties passed on this event:
cancelledAt: date and timestamp of the last cancellation event of the subscriber
daysSinceCancellation: number of days since the last cancellation
Important! This metric will only fire if you have set up your WinbackEngine in the Stay app > Optimization > WinbackEngine. You must set up your time delay range, enable the engine, and click Save.
You must also set up a flow in Klaviyo that is triggered off of the Retextion - Winback Ready metric in order for customers to receive an email. If you would like to get started with Stay's templated Winback flow, reach out to your CSM or OM.
Understanding Metric Event Properties
Every time Stay sends a metric to Klaviyo, it includes a set of data called event properties. These are the variables passed along with the metric — things like the names of the items in a subscription, the order number, or the next billing date. You can use these properties to personalize email content, build trigger splits, and create conditions in your Klaviyo flows.
For example, if your fifth-order subscribers receive a free gift, you can use the orderNumber property on the Retextion - Order Upcoming metric to send them a different email than first-order subscribers.
Note: The properties listed below are the variable names as they appear in Klaviyo. When inserting a property into an email template, use Klaviyo's variable syntax: #{{ event.orderNumber }}, #{{ event.itemNames }}, etc.
Universal Event Properties
The following properties are included with every Stay metric that fires to Klaviyo.
Property | Description |
itemNames | Display name(s) of the product(s) in the subscription (e.g., Handmade Soap, Vitamin C Serum) |
items | Full item details for each product in the subscription. Includes productID, productName, quantity, itemPrice, rowTotal, imageURL, variantId, displayName, sku, and onlineStorePreviewUrl |
orderNumber | The order count for this subscription (e.g., 1 for the first order, 5 for the fifth) |
orderIntervalFrequency | The number of interval units between orders (e.g., 1) |
orderIntervalUnit | The time unit for the billing interval (e.g., MONTH, WEEK) |
nextBillingDate | The date and time of the next scheduled order |
discountValue | The discount amount applied to the order |
retextionSubscriptionID | Stay's internal ID for the subscription |
subscriptionContractID | The Shopify subscription contract ID |
rtx_active_subscriber | true if the customer has at least one active subscription |
rtx_active_subscription_count | Count of the customer's active subscriptions |
rtx_active_subscription_variant_ids | Variant IDs of the line items in the customer's active subscriptions |
rtx_cancelled_subscription_count | Count of the customer's cancelled subscriptions |
rtx_external_customer_id | The customer's Shopify customer ID |
rtx_first_charge_processed_at | Date and time the customer's first subscription charge was processed |
rtx_subscriptions | Summary of the customer's subscriptions, including product name, variant, and status |
rtx_all_subscriptions | Full subscription object including billing policy, address, payment method, and status history |
Metric-Specific Event Properties
Some metrics pass additional properties beyond the universal set above. Expand each metric below to see what's available.
Retextion - Order Upcoming
In addition to the universal properties, this metric passes:
Property | Description |
churnRisk | A score between 0 and 1 representing the likelihood this subscriber will cancel (e.g., 0.24) |
currency | The currency code for the order (e.g., USD) |
prePaid | true if the subscription is prepaid; false if standard recurring |
rtx_customer_has_promotion | true if an ExperienceEngine promotion is currently pending for this subscription |
Tip! The orderNumber field on this metric reflects the number of the upcoming order — not the last completed one. Use this to build order-milestone flows (e.g., send a loyalty reward email when orderNumber equals 6).
If rtx_customer_has_promotion is true, the following additional promotion properties are also included:
Property | Description |
rtx_promotion_customer_response | Whether the customer has responded to the promotion (e.g., APPROVE) |
rtx_promotion_email_sent | true if a promotion email has already been sent to this customer |
rtx_promotion_product_name | The name of the product included in the promotion |
rtx_promotion_discount_type | The discount type (e.g., PERCENTAGE, FIXED) |
rtx_promotion_discount_value | The discount amount |
rtx_promotion_price | The discounted order price |
rtx_promotion_link | A unique URL for the customer to approve or interact with the promotion |
Retextion - Subscription Canceled
In addition to the universal properties, this metric passes:
Property | Description |
cancellationReasons | An array of the reason(s) the customer provided when canceling. Returns empty if no reason was given |
Best Practice: Use cancellationReasons to route canceled subscribers into different winback flows based on why they left (e.g., price-sensitive cancellations vs. those pausing for travel).
Retextion - Subscription Paused
In addition to the universal properties, this metric passes:
Property | Description |
pausedAt | The date and time the subscription was paused |
pausedUntil | The date and time the subscription is scheduled to resume |
Retextion - Subscription Skipped
In addition to the universal properties, this metric passes:
Property | Description |
dateSkipped | The date and time of the order that was skipped |
Retextion - Billing Attempt Failed
In addition to the universal properties, this metric passes:
Property | Description |
pausedAt | The date and time the subscription entered a failed billing state |
pausedUntil | The date and time the subscription is scheduled to exit the failed billing state |
Note: The orderNumber on this metric reflects the order number that failed to process — useful for personalizing recovery messaging based on how long a customer has been subscribed.
Retextion - First Gift Sent / Gift Sent / Last Gift Sent
In addition to the universal properties, these metrics pass:
Property | Description |
gifteeInformation | An object containing the gift recipient's details: email, first_name, last_name, phone_number, and rtx_customer_hash |
Understanding Stay Profile Properties
Profile properties are persistent attributes that Stay writes directly to a customer's Klaviyo profile — separate from event properties, which only exist at the moment a metric fires. Because they live on the profile itself, they're available at any time, not just when a subscription event occurs.
You'll find them on any subscriber's Klaviyo profile page, and you can reference them in the Klaviyo segment builder by searching "Stay." The most common uses are building segments (e.g., all active subscribers, all paused subscribers), adding flow filters (e.g., exclude customers where stay_inactive is true), and suppressing sends to customers who no longer have an active subscription.
The following custom properties are currently available.
stay_active & stay_active_subscriber - 'true' if the customer has at least one active subscription; 'false' if the customer only has paused or cancelled subscriptions
stay_inactive - 'true' if the customer only has cancelled subscriptions; 'false' if the customer has any paused or active subscriptions
stay_paused - 'true' if the customer has at least one paused subscription; 'false' if the customer does not have any paused subscriptions
stay_active_subscription_count - count of the customer's active subscriptions
stay_active_subscription_variant_ids - the variant IDs of the line items in the customer's active subscriptions
stay_cancelled_subscription_count - count of the customer's cancelled subscriptions
stay_cancelled_subscription_variant_ids - the variant IDs of the line items in the customer's cancelled subscriptions
stay_all_subscriptions - subscription IDs of all the subscriptions the customer has
Note: You can view all subscription profile properties by either navigating to a subscription customer's profile in Klaviyo, as seen in the screenshot example below.
You can also create a segment around profile properties and search for "Stay" when prompted to select the property in the segment-builder.
Creating Klaviyo Email Flows
If you'd like to send any subscription emails through Klaviyo instead of Stay (e.g. subscription creation confirmation, order upcoming, cancellation confirmation, etc.), you will need to create flows in Klaviyo. Each flow will be triggered off of a "Retextion" metric. From there, you can build the email you'd like customers to receive when they enter the flow.
Below is a breakdown of the Klaviyo metric you will use to create various subscription email flows.
Note: The 'Security Code' email in Stay must remain toggled on. This email sends the passwordless login verification code to customers so they can access their subscription portal.
Subscription Email | Klaviyo Metric |
Subscription Creation Confirmation | Retextion - Subscription Started |
Subscription Order Skipped | Retextion - Subscription Skipped |
Subscription Paused Confirmation | Retextion - Subscription Paused |
Subscription Cancelation Confirmation | Retextion - Subscription Canceled |
Upcoming Charge | Retextion - Order Upcoming |
ExperienceEngine Promotion Applied | Retextion - Promotion Applied |
Item Out of Stock | Retextion - Item Out of Stock |
Order Partially Fulfilled | Retextion - Order Partially Fulfilled |
Payment Declined | Retextion - Billing Attempt Failed |
Payment Expiring | Retextion - Payment Method Expiring |
Prepaid Order Completed | Retextion - Subscription Expired |
Digital Punch Card Punch Earned | Retextion - Punch Earned |
Digital Punch Card Award Earned | Retextion - Award Earned |
Digital Punch Card Award Redeemed | Retextion - Award Redeemed |
Note: You'll need to reach to Klaviyo to request that they mark the appropriate emails in your subscription flows as transactional. This ensures that those transactional emails are still sent to customers that are unsubscribed to marketing emails. Here is a Klaviyo help article on sending transactional emails through flows.