> ## Documentation Index
> Fetch the complete documentation index at: https://developers.appstle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Klaviyo events reference

> The events Appstle Subscriptions sends to Klaviyo: each event's metric name, when it is sent, the properties it carries, and how to use them in a Klaviyo flow.

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.

> [!NOTE]
>
> This page is about the events Appstle sends **to Klaviyo**. To receive subscription events on your own server, use [webhooks](https://developers.appstle.com/subscription/webhooks.md). To react to them inside Shopify, use [Shopify Flow](https://developers.appstle.com/subscription/shopify-flow.md).

## 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.

> [!NOTE]
>
> **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](#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](#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](#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](#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.

> [!WARNING]
>
> 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](#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**).

| Metric name | Template and when it's sent |
| - | - |
| `Create Subscription Event from Appstle` | **Subscription Created**. A new subscription is registered. |
| `Upcoming Order Event from Appstle` | **Upcoming Order**. Before a recurring order, as many days ahead as the template is set to. |
| `Transaction Success Event from Appstle` | **Transaction Success**. A recurring order is billed successfully. |
| `Transaction Failed Event from Appstle` | **Transaction Failed**. A recurring order's payment fails. Sent on the first failed try. On a retry, sent only when **Email the customer after each failed retry** is on in **Failed Payment Recovery**, or when the retry offers a recovery discount. An out-of-stock failure sends the Out of stock event instead. |
| `Security Challenge Event from Appstle` | **Security Challenge**. A billing attempt needs the customer to confirm the payment (`challengeUrl`). |
| `Expiring Credit Card Event from Appstle` | **Expiring Credit Card**. On each of the last three days of the month before the card's expiry month. For a card that expires 12/2026, that's November 28, 29 and 30. Sent once for each of the customer's active subscriptions, whichever payment method the subscription uses. |
| `Out of Stock Event from Appstle` | **Out Of Stock**. A billing attempt is skipped because an item is out of stock. |
| `Order skipped Event from Appstle` | **Order Skipped**. An upcoming order is skipped. |
| `Subscription paused Event from Appstle` | **Subscription Paused**. A subscription is paused. |
| `Subscription resumed Event from Appstle` | **Subscription Resumed**. A subscription is resumed. |
| `Subscription canceled Event from Appstle` | **Subscription Cancelled**. A subscription is canceled. |
| `Shipping Address  Updated Event from Appstle` | **Shipping Address Updated**. The shipping address changes. The metric name has two spaces between `Address` and `Updated`. |
| `Order Frequency Updated Event from Appstle` | **Order Frequency Updated**. The delivery frequency changes. |
| `Next Order Date Updated Event from Appstle` | **Next Order Date Updated**. The next order date changes. |
| `Product added in Subscription Event from Appstle` | **Subscription Product Added**. A product is added to a subscription. |
| `Product removed from Subscription Event from Appstle` | **Subscription Product Removed**. A product is removed from a subscription. |
| `Product replaced in Subscription Event from Appstle` | **Subscription Product Replaced**. A product in a subscription is replaced. |
| `Product Price Updated Event from Appstle` | **Product Price Updated**. A subscribed product's price is updated. |
| `Cancellation Discount Applied Event from Appstle` | **Cancellation Discount Applied**. A notification for the merchant, not the customer. It's sent when a customer accepts a discount offer in the cancellation flow while **Email notifications for accepted discounts** is on in **Retention Management**, and it goes to the **Notification Email Address** set there. |
| `Subscription management link sent Event from Appstle` | **Subscription Management Link**. A customer asks for an email with a link to manage subscriptions without signing in. |
| `Bulk all subscribers Event from Appstle` | **Bulk Communications**. The merchant sends a bulk communication to all subscribers. |
| `Bulk active subscribers only Event from Appstle` | **Bulk Communications**. The merchant sends a bulk communication to active subscribers. |
| `Bulk cancelled subscribers only Event from Appstle` | **Bulk Communications**. The merchant sends a bulk communication to canceled subscribers. |
| `Bulk paused subscribers only Event from Appstle` | **Bulk Communications**. The merchant sends a bulk communication to paused subscribers. |

## 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.

| Property | Type | Description |
| - | - | - |
| `appstle_contracts` | Array of objects | One object for each of the customer's subscriptions, with the fields below |
| `appstle_active_contract_count` | Number | How many of the customer's subscriptions are active |
| `appstle_total_contract_count` | Number | How many subscriptions the customer has, in any status |

| `appstle_contracts` field | Type | Description |
| - | - | - |
| `id` | Number | The subscription's ID, the same as `subscriptionContractId` |
| `status` | String | The subscription's status in lowercase, such as `active`, `paused` or `cancelled` |
| `next_order_date` | String | The next order date in ISO 8601. Some events send a date, such as `2026-11-28`, and others a date and time |
| `order_amount` | Number | The same amount as `firstOrderAmount`, in the store's currency |
| `currency_code` | String | The subscription's currency. It can differ from the currency of `order_amount` |
| `order_frequency` | String | The delivery interval count and unit, such as `2 WEEK` |

`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

| Property | Type | Description |
| - | - | - |
| `customer` | Object | The customer: `id` (Shopify customer ID, a number), `first_name`, `last_name`, `display_name`, `email`, `token` (the portal token, see [Links](#the-portal-link-and-token)), and `phone`, which is the customer's phone or, when the customer has none, the shipping address phone. `phone` is left out when neither has one |
| `customer_token` | String | The same token as `customer.token` |
| `subscriptionContractId` | Number | The subscription contract's ID. It matches the `id` the [Admin API](https://developers.appstle.com/subscription/integration-guide.md) uses |
| `orderId` | String | The name of the order that created the subscription, such as `#1042`. An empty string when unknown. It isn't the order of the billing attempt |
| `subject`, `heading` | String | The email's subject and heading, with the template's variables already filled in |
| `bodyLines` | Array of strings | The template's body text, one string per line |
| `manageSubscriptionLink` | String | The link to the customer portal. See [Links](#the-portal-link-and-token). There is no separate payment update link: on **Transaction Failed**, send the customer to this link, as Appstle's default Transaction Failed email does with its **Manage Subscription** button |
| `shop` | Object | The store, as Shopify describes it, such as `name`, `email`, `myshopifyDomain`, `primaryDomain` and `currencyCode` |
| `planType` | String | `PAY_AS_YOU_GO`, or `PREPAID` when the customer pays for several deliveries at once |
| `sellingPlanGroup` | String | The name of the subscription plan group |
| `note` | String | The subscription's note. An empty string when there's none |
| `allAttributes` | Array | The subscription's custom attributes and every line's custom attributes, each with a `key` and a `value` |
| `customAttributes` | Object | The same attributes as `allAttributes`, as key and value pairs |
| `body_content`, `footer` | String | The template's body and footer, with its variables filled in |

### Schedule

| Property | Type | Description |
| - | - | - |
| `nextOrderDate` | String | The next order date in the store's time zone and its customer portal date format, such as `Nov 28, 2026`. It's `-` when no order is scheduled, on the paused and canceled events, on a created event when the subscription is limited to fewer than two cycles, and on a resumed event when the subscription has a maximum number of cycles |
| `nextOrderDateISO` | String | The same date as `yyyy-MM-dd`. `null` when `nextOrderDate` is `-` |
| `frequency_of_subscription` | String | The delivery interval count and unit, such as `2 WEEK`. For a subscription billed on fixed dates, the dates instead, such as `Billed on Jan 1 and Jul 1` |
| `deliveryInterval`, `deliveryIntervalCount` | String, Number | How often an order is delivered. The interval is `DAY`, `WEEK`, `MONTH` or `YEAR` |
| `billingInterval`, `billingIntervalCount` | String, Number | How often the customer is billed, in the same units |
| `currentCycle` | Number | The cycle the subscription is on: 1 plus the number of orders already billed successfully |
| `minCycles`, `maxCycles` | String | The subscription's minimum and maximum number of billing cycles. An empty string when not set |
| `orderCreatedDate` | String | The date the subscription was created, in the same format as `nextOrderDate` |
| `pauseTillDate`, `pauseDurationCycle` | String, Number | On the paused event, the date the pause ends, in the store's date format, and the number of cycles it lasts. `pauseTillDate` is an empty string when no end date is set |

### 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.

| `orderItems` field | Type | Description |
| - | - | - |
| `title` | String | The product title |
| `variantTitle` | String | The variant title. `null` for a product with only a default variant |
| `quantity` | Number | The quantity |
| `price` | String | The line's price after line discounts, quantity included, in the store's money format, such as `$39.80`. When the contract's currency isn't the store's currency, it's the amount followed by the currency code, such as `39.80 EUR` |
| `basePrice` | String | The variant's current price in Shopify before any subscription discount, as a plain number such as `19.90`. `null` when Appstle couldn't read the variant |
| `imageUrl` | String | The variant's image, or a placeholder image |
| `sellingPlanName`, `sellingPlanId` | String, Number | The selling plan's name and ID |
| `variantSku`, `productId`, `variantId`, `productHandle`, `vendor` | String, Number | The variant's SKU, the product and variant IDs, the product's handle and its vendor |
| `subscriptionProduct`, `skippedProduct`, `taxable` | Boolean | Whether the line is a subscription product, whether the line is skipped for the next order, and whether it's taxable |
| `customAttributes` | Array | The line's custom attributes, each with a `key` and a `value` |

### Amounts

| Property | Type | Description |
| - | - | - |
| `currencyCode` | String | The subscription's currency. `contractAmount`, the shipping amounts and `nextOrderPrice` are in this currency |
| `contractAmount` | Number | The recurring product total for one billing: each line's price after line discounts, added together. It excludes shipping and tax |
| `firstOrderAmount`, `firstOrderAmountUSD` | Number | The subscription's lines on the order that created it, after discounts and with tax but without shipping. `firstOrderAmount` is in the store's currency, not the subscription's. `firstOrderAmountUSD` is the same amount in US dollars |
| `shippingAmount`, `shippingAmountFormatted` | Number, String | The contract's shipping price. `0` and `null` when the contract has none. The formatted string uses the store's money format |
| `orderTotalWithShipping`, `orderTotalWithShippingFormatted` | Number, String | `contractAmount` plus `shippingAmount`. Tax isn't included |
| `nextOrderPrice`, `nextOrderPriceFormatted` | Number, String | The same value as `orderTotalWithShipping`, the recurring price from the next order on |

### Addresses and delivery

| Property | Type | Description |
| - | - | - |
| `shipping_type` | String | How the subscription is delivered: `SHIPPING`, `LOCAL` (local delivery) or `PICK_UP` |
| `deliveryMethod` | String | The title of the delivery option |
| `shipping_first_name`, `shipping_last_name`, `shipping_company`, `shipping_address1`, `shipping_address2`, `shipping_city`, `shipping_province`, `shipping_province_code`, `shipping_zip`, `shipping_country`, `shipping_country_code`, `shipping_phone` | String | The delivery address. For pickup, the pickup location's address, and `shipping_first_name` is the location's name |
| `billing_full_name`, `billing_address1`, `billing_city`, `billing_province`, `billing_province_code`, `billing_zip`, `billing_country`, `billing_country_code` | String | The billing address of the subscription's payment method |
| `shippingAddress`, `billingAddress` | String | Each address as the Appstle template's address block formats it |
| `shippingLines`, `billingLines` | Array of strings | The same address blocks, one string per line |

### Payment method

| Property | Type | Description |
| - | - | - |
| `lastFourDigits`, `maskedCardNumber` | String | The last four digits of the card or Shop Pay method the subscription uses now. For PayPal, `lastFourDigits` is an empty string and `maskedCardNumber` is `null` |
| `cardLogo` | String | An image URL for the payment method: Visa, American Express, Discover, PayPal or Shop Pay. Any other card brand, and a subscription without a payment method, gets the Mastercard image |
| `expiryDate` | String | **The next billing date**, not the card's expiry date. It's in the store's customer portal date format. Use it with care on the Expiring credit card event |

The events carry no payment method ID.

### Properties of a single event

| Event | Properties |
| - | - |
| Transaction failed | Values from the subscription's latest failed attempt: `billingFailureReason` (the decline message, such as `Your card was declined.`), `failedPaymentDate` (when that try failed), `lastBillingDate` (the order date the attempt was for), `nextRetryDate` (only when another retry is scheduled) and `numberOfFailedAttempts` (the attempt's earlier failed tries, so `0` on the first failure). The dates use the store's date format. When the retry offers a recovery discount, the event also carries `recoveryDiscountLabel` and `recoveryDiscountMessage`. On every other event, `numberOfFailedAttempts` is `0` and the rest are `null` |
| Security challenge | `challengeUrl`, the URL where the customer confirms the payment |
| Subscription paused | `pauseReason` and `pauseNote`, as the customer or merchant entered them, when there are any |
| Expiring credit card | No properties of its own. `lastFourDigits`, `maskedCardNumber` and `cardLogo` describe the payment method the subscription uses now, which isn't always the expiring card. `expiryDate` is the next billing date |
| Subscription canceled | `cancellationReason` and `cancellationNote`, as the customer or merchant entered them |
| Cancellation discount applied | Only `subscriptionContractId`, `discountPercentage` (a number), `customer.display_name`, `shop`, `subject`, `heading`, `body_content` and `footer`. Every other property is `null` |
| Order skipped | `skippedOrderDate` (store date format) and `skippedOrderDateISO` (`yyyy-MM-dd`). Left out of every other event |
| Product added, removed or replaced | `itemsAdded` and `itemsRemoved` (arrays of `orderItems` objects), `productsAdded` and `productsRemoved` (arrays of product names). `null` when empty |
| Out of stock | `outOfStockProducts`, an array of product names |
| Product price updated | `productsPriceUpdated`, an array of objects with `productName`, `oldPrice` and `newPrice` (numbers) |

### 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).

## The portal link and token

`manageSubscriptionLink` depends on the store's customer portal:

| The store uses | The link is |
| - | - |
| The classic portal | `https://<domain>/<portal path>/cp/<token>`. `<domain>` is the store's **Public Domain**, and `<portal path>` is `apps/subscriptions` unless the store changed it. The token opens the portal without a sign-in for **2 hours after Appstle sent the event**. After that, the link works only for a customer who is already signed in to the store, so send the email without a delay. |
| The advanced customer portal | `https://<domain>/pages/subscriptions`. No token. The customer signs in. |
| Shopify's customer accounts | `https://shopify.com/<shop ID>/account/pages/<page ID>`. No token. The customer signs in with Shopify. |

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.

```json theme={null}
{
  "data": {
    "type": "event",
    "attributes": {
      "metric": {
        "data": {
          "type": "metric",
          "attributes": {
            "name": "Transaction Failed Event from Appstle"
          }
        }
      },
      "profile": {
        "data": {
          "type": "profile",
          "attributes": {
            "email": "maya@example.com",
            "properties": {
              "appstle_contracts": [
                {
                  "id": 194140176688,
                  "status": "active",
                  "order_amount": 39.8,
                  "currency_code": "USD",
                  "order_frequency": "2 WEEK"
                }
              ],
              "appstle_active_contract_count": 1,
              "appstle_total_contract_count": 1
            }
          }
        }
      },
      "value": 39.8,
      "value_currency": "USD",
      "properties": {
        "subject": "Payment failed for your subscription",
        "heading": "We couldn't process your payment",
        "customer": {
          "id": 7123456789012,
          "display_name": "Maya Brooks",
          "first_name": "Maya",
          "last_name": "Brooks",
          "token": "eyJ0b2tlbiI6InBsYWNlaG9sZGVyIn0",
          "email": "maya@example.com"
        },
        "customer_token": "eyJ0b2tlbiI6InBsYWNlaG9sZGVyIn0",
        "subscriptionContractId": 194140176688,
        "orderId": "#1042",
        "manageSubscriptionLink": "https://demo-store.example.com/apps/subscriptions/cp/eyJ0b2tlbiI6InBsYWNlaG9sZGVyIn0",
        "nextOrderDate": "Nov 28, 2026",
        "nextOrderDateISO": "2026-11-28",
        "frequency_of_subscription": "2 WEEK",
        "deliveryIntervalCount": 2,
        "deliveryInterval": "WEEK",
        "billingIntervalCount": 2,
        "billingInterval": "WEEK",
        "currentCycle": 1,
        "orderItems": [
          {
            "quantity": 2,
            "title": "House Blend Coffee",
            "variantTitle": "12 oz",
            "price": "$39.80",
            "imageUrl": "https://cdn.shopify.com/s/files/1/0000/0000/products/house-blend.jpg",
            "sellingPlanName": "Delivery every 2 weeks",
            "variantSku": "HB-12",
            "productId": 8123456789012,
            "variantId": 44123456789012,
            "subscriptionProduct": true,
            "skippedProduct": false
          }
        ],
        "productIds": [
          8123456789012
        ],
        "variantIds": [
          44123456789012
        ],
        "currencyCode": "USD",
        "contractAmount": 39.8,
        "firstOrderAmount": 39.8,
        "shippingAmount": 5.0,
        "shippingAmountFormatted": "$5.00",
        "orderTotalWithShipping": 44.8,
        "orderTotalWithShippingFormatted": "$44.80",
        "nextOrderPrice": 44.8,
        "nextOrderPriceFormatted": "$44.80",
        "lastFourDigits": "4242",
        "maskedCardNumber": "4242",
        "billingFailureReason": "Your card was declined.",
        "failedPaymentDate": "Nov 14, 2026",
        "lastBillingDate": "Nov 14, 2026",
        "nextRetryDate": "Nov 17, 2026",
        "numberOfFailedAttempts": 0
      }
    }
  }
}
```

`orderItems`, `customer` and the other properties keep the shapes described above. A real event also holds the other properties of [Event properties](#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 %}`:

```liquid theme={null}
Hi {{ event.customer.first_name }},

Your next order ships on {{ event.nextOrderDate }}.

{% for item in event.orderItems %}
  {{ item.quantity }} x {{ item.title }} {{ item.variantTitle }} ({{ item.price }})
{% endfor %}

Total: {{ event.nextOrderPriceFormatted }}

<a href="{{ event.manageSubscriptionLink }}">Manage your subscription</a>
```

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](#get-started)).

> [!NOTE]
>
> **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.

| Property | Type | Description |
| - | - | - |
| `action` | String | `created` or `updated` |
| `provider` | String | `appstle` |
| `external_id`, `charge_id` | String | The subscription's ID, as text, the same as `subscriptionContractId` |
| `status` | String | `active`, `paused`, `cancelled` or `expired` |
| `next_billing_date`, `started_date`, `canceled_date` | String | When the next order is billed, when the subscription started and when it was canceled, as UTC timestamps in ISO 8601, such as `2026-11-28T08:00:00Z` |
| `source_updated_at` | String | When the subscription last changed, as a UTC timestamp in ISO 8601. On a created event, the time Appstle sent the event |
| `cancellation_reason` | String | On an updated event, the subscription's cancellation note, when there is one |
| `billing_interval` | String | `day`, `week`, `month` or `year` |
| `billing_interval_count` | Number | How many of those units pass between bills |
| `currency_code` | String | The subscription's currency |
| `line_items` | Array of objects | One object for each line, with `product_title`, `variant_title`, `quantity`, `sku`, `image_src`, `price`, `currency_code`, `product_id`, `variant_id`, `selling_plan_id`, `selling_plan_name` and `line_id` |
| `manage_url` | String | The customer portal link, without a sign-in token |

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](https://developers.appstle.com/subscription-admin-api/billing-&-payments/get-past-orders.md) 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](https://developers.appstle.com/subscription/webhooks), 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](https://developers.appstle.com/subscription/webhooks.md) shows. The event holds only `lastFourDigits`, `maskedCardNumber` and `cardLogo` for the method the contract uses at that moment.

## Next steps

> [card] [Webhooks](https://developers.appstle.com/subscription/webhooks.md)
>
> Receive the same lifecycle events on your own server, with IDs and signatures.

> [card] [Shopify Flow](https://developers.appstle.com/subscription/shopify-flow.md)
>
> Use Appstle triggers and actions inside Shopify.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.