This page is about the events Appstle sends to Klaviyo. To receive subscription events on your own server, use webhooks. To react to them inside Shopify, use Shopify Flow.
Get started
1
Connect Klaviyo
In the Appstle admin, go to App Integrations and open Klaviyo Email, SMS & Contacts Sync. Click Connect Klaviyo and approve the connection in Klaviyo. Then turn on Enable Klaviyo Email & SMS. From then on, Appstle sends its subscription emails to Klaviyo as events instead of sending them itself.
2
Create a flow for each event
Click Create draft flows to create one draft flow for each event, or create a flow in Klaviyo yourself with the event’s metric as its trigger. The draft flows have smart sending off and aren’t marked as transactional, so Klaviyo applies its marketing consent rules to them. Review each flow’s sender, content and consent settings. Each draft flow’s email uses the subject line
{{ event.subject }}, which is the Subject of the matching template in Email > Templates with its variables filled in. Appstle creates a draft flow once and doesn’t change it afterward, so you can replace the subject in Klaviyo with any text, or change the template’s Subject in Appstle.3
Send a test event
In Email > Templates, click Test Email on a template, choose an address and click Send Test Email. The list offers only the store’s Allowed Email Addresses for Notifications, which the store owner manages in Shop settings. Appstle sends that template’s event for the address you chose and adds
- TEST to the heading. It fills the event from the store’s oldest active subscription whose email hasn’t bounced. To test with another subscription, open the template, click the subscription number next to Live Data in Preview, search by ID, name or email, and select a subscription. Then click More actions > Test Email. Find the event in that profile’s activity in Klaviyo, and preview the flow’s message with it. If the store has no such subscription, the event carries sample data (see the note below).4
Set the flows live
Set each flow live in Klaviyo. Keep the matching template Active in Email > Templates, because turning a template off stops its event.
When the store has no such subscription, a test event carries sample data. The customer is a sample customer named John Doe, the item is the store’s first active or unlisted product (or
Test Product when it has none), and nextOrderDate is two days from today in the customer portal date format (- for Subscription Cancelled and Subscription Paused). Other properties hold fixed sample values, such as subscriptionContractId 1111111 and lastFourDigits 4242. nextOrderDateISO and challengeUrl are null, and manageSubscriptionLink is only the store’s address, https://<your-store>.myshopify.com, not a customer portal link. Create a subscription, then send the test again to see real values.Even with a real subscription, a test Security Challenge event has a challengeUrl only when that subscription has a billing attempt waiting for the customer to confirm the payment. A Security Challenge event sent for a real challenge carries the link for that attempt.How Appstle sends an event
For each email Appstle would send, it posts one event to Klaviyo’s Events API for the customer’s profile:- Metric name. One metric per email type, listed in Events. In Klaviyo, create a flow triggered by that metric.
- Profile. The customer’s email address, plus
phone_numberwhen the customer or the shipping address has one. Each event also updates three properties on the profile. See Profile properties. - Event properties. The same values that the Appstle email template can use, such as the customer, the items, the amounts and the dates. See Event properties.
- Value.
valueandvalue_currency.valueisfirstOrderAmount, so it’s the same on every event of a subscription. When that amount isn’t known,valueiscontractAmount.value_currencyis the subscription’s currency, butfirstOrderAmountis in the store’s currency, so the two don’t match when a customer subscribes in another currency. For the recurring amount in a flow, readnextOrderPriceornextOrderPriceFormattedfrom the properties.
When an event is sent
Appstle sends an event only when all three of these are true:- A Klaviyo account is connected and Enable Klaviyo Email & SMS is on in App Integrations > Klaviyo. While it’s on, Appstle sends these emails through Klaviyo only. It doesn’t also send its own email.
- The email template is active. Each email has a template in Email > Templates with an Active or Inactive badge and a Disable or Enable button. Turning a template off stops the Klaviyo event as well as the Appstle email.
- The subscription is allowed to get email. If Disable Email Notifications for Paused or Cancelled Contracts is on, Appstle sends no event for a paused or canceled subscription. The exceptions are the paused, resumed, canceled and subscription management link events, the bulk events to all, paused and canceled subscribers, and the created event for a subscription that came with an order.
Events
The metric name is the exact text Klaviyo shows. Each event comes from an email template of the same name in Email > Templates (the bulk events come from Email > Bulk Communications).Profile properties
Each event also sets three properties on the customer’s Klaviyo profile. They describe all of the customer’s subscriptions in the store, and each event replaces their earlier values.next_order_date, order_amount, currency_code and order_frequency are left out when the subscription has no value for them. Some events add more fields to each object: next_order_date_time, created_at, activated_on, paused_on, cancelled_on, contract_amount and contract_amount_usd. Don’t build on them, because not every event sends them.
Event properties
Every event carries the same set of about 125 properties, and a property that doesn’t apply to the event isnull. A few are left out when they have no value: skippedOrderDate, skippedOrderDateISO and customer.phone. The tables below list every property that carries data. The others hold the Appstle template’s styling and labels, such as the colors, logo_url, heading_image_url and the *_text labels. A Klaviyo template doesn’t need them.
Customer and subscription
Schedule
Items
orderItems is an array with one object for each line of the subscription. Lines skipped for the next order are left out. productIds and variantIds are arrays of the lines’ product and variant IDs, as numbers.
Amounts
Addresses and delivery
Payment method
The events carry no payment method ID.
Properties of a single event
Free trial
These describe a subscription’s free trial and arenull when it has none: isCurrentlyOnFreeTrial (Boolean), freeTrialStartDate, freeTrialEndDate, daysRemainingInFreeTrial (Number), totalFreeTrialDuration (Number), freeTrialDurationUnit, firstRegularBillingDateAfterTrial and willResumeOriginalScheduleAfterTrial (Boolean).
The portal link and token
manageSubscriptionLink depends on the store’s customer portal:
If the template sets a Button link for its Manage subscription button,
manageSubscriptionLink is that link instead, with the template’s variables filled in.
customer.token and customer_token are the same 2-hour token. To build your own link in Klaviyo, such as a quick action, use {{ event.customer_token }} and {{ event.subscriptionContractId }}. Quick Actions in the Appstle admin builds these links for you when you set Sending tool to Klaviyo.
Example
The Transaction failed event for one subscription, trimmed to the properties you’d use. The values are placeholders in the formats Appstle sends. Appstle posts it tohttps://a.klaviyo.com/api/events with the connected account’s credentials.
orderItems, customer and the other properties keep the shapes described above. A real event also holds the other properties of Event properties, most of them null.
Use the properties in Klaviyo
In a Klaviyo email or SMS template, read a property with{{ event.<property> }}, a nested one with a dot, and loop over an array with {% for %}:
Create draft flows sends Klaviyo one placeholder event for each flow so the flow can find its metric. The placeholder goes to a sample profile, not to a customer, and has only
appstle_flow_setup (true), appstle_event_name, subject, heading and bodyLines. Real events carry everything on this page.Customer Hub and Contacts Sync
When Enable Klaviyo Customer Hub is also on, Appstle sends Klaviyo’s$hub.subscription.state event each time a subscription is created or changes, so that Klaviyo’s Customer Hub can show the customer’s subscriptions. It uses Klaviyo’s Customer Hub format, not the properties on this page.
A property without a value is left out, so
canceled_date appears only once a subscription is canceled. The updated event also carries an appstle_details object for Appstle’s own use. Don’t build on it, because its fields can change.
Enable Klaviyo Contacts Sync adds each new subscriber’s email address to the Klaviyo list you choose. It sends no event.
Match an event to an attempt or a payment method
An event carries no billing attempt ID, no payment method ID and no idempotency key. UsesubscriptionContractId to find the records.
- A billing attempt. Call Get past orders with
subscriptionContractId. The Transaction failed event describes the attempt with the latestattemptTimewhosestatusisFAILUREorSKIPPED_DUNNING_MGMT. On that attempt,attemptCountisnumberOfFailedAttemptsplus one,billingDateislastBillingDate, andattemptTimeisfailedPaymentDate. If your server receives thesubscription.billing-failurewebhook, it carries the same failure with the IDs:idis Appstle’s attempt ID and stays the same across retries, andbillingAttemptIdis Shopify’s ID for the latest try. - A payment method. The contract webhooks carry
customerPaymentMethod.idand theinstrument, as the webhook payload reference shows. The event holds onlylastFourDigits,maskedCardNumberandcardLogofor the method the contract uses at that moment.
Next steps
Webhooks
Receive the same lifecycle events on your own server, with IDs and signatures.
Shopify Flow
Use Appstle triggers and actions inside Shopify.