Skip to main content
When a store connects Klaviyo and turns on Enable Klaviyo Email & SMS, Appstle Subscriptions sends its subscription emails to Klaviyo as events instead of sending them itself. You build the message in a Klaviyo flow that uses the event’s properties. This page lists the events, when they’re sent, what each property holds, and how to match an event to a billing attempt or a payment method.
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_number when 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. value and value_currency. value is firstOrderAmount, so it’s the same on every event of a subscription. When that amount isn’t known, value is contractAmount. value_currency is the subscription’s currency, but firstOrderAmount is 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, read nextOrderPrice or nextOrderPriceFormatted from the properties.
Appstle sends no event ID and no billing attempt ID with an event. To match an event to a billing attempt, see Match an event to an attempt or a payment method.

When an event is sent

Appstle sends an event only when all three of these are true:
  1. 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.
  2. 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.
  3. 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.
If a template has Only Send this email as Admin notification? checked, Appstle sends that template’s event for the template’s Admin Notification / BCC Email address instead of the customer’s, and the customer’s profile gets no event for it. A template set up this way before you connected Klaviyo keeps sending to that address.
The three gift emails (Gift Purchased Merchant, Gift Received and Gift Thank You) send no Klaviyo event. Appstle sends them itself, even while Klaviyo is on. The Upcoming order event is also skipped when the subscription isn’t active in Shopify at the moment it’s due. The Subscription created event reaches Klaviyo about five minutes after checkout, and a subscription bought as a gift sends none. If Klaviyo rejects an event, Appstle doesn’t retry it and doesn’t send its own email instead. Turning a template off stops its event, but some events still update the customer’s profile properties.

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 is null. 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 are null when it has none: isCurrentlyOnFreeTrial (Boolean), freeTrialStartDate, freeTrialEndDate, daysRemainingInFreeTrial (Number), totalFreeTrialDuration (Number), freeTrialDurationUnit, firstRegularBillingDateAfterTrial and willResumeOriginalScheduleAfterTrial (Boolean). 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 to https://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 %}:
The sample template that Create draft flows adds uses the same syntax. Property names are case sensitive. Preview the message with a test event before you set the flow live (see Get started).
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. Use subscriptionContractId to find the records.
  • A billing attempt. Call Get past orders with subscriptionContractId. The Transaction failed event describes the attempt with the latest attemptTime whose status is FAILURE or SKIPPED_DUNNING_MGMT. On that attempt, attemptCount is numberOfFailedAttempts plus one, billingDate is lastBillingDate, and attemptTime is failedPaymentDate. If your server receives the subscription.billing-failure webhook, it carries the same failure with the IDs: id is Appstle’s attempt ID and stays the same across retries, and billingAttemptId is Shopify’s ID for the latest try.
  • A payment method. The contract webhooks carry customerPaymentMethod.id and the instrument, as the webhook payload reference shows. The event holds only lastFourDigits, maskedCardNumber and cardLogo for 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.