Klaviyo Event Payload Structure | Kaching Bundles Help Center

This guide explains the structure of event data sent to Klaviyo when subscription events occur. Understanding this structure will help you create more effective email templates and automation flows.

Overview

All subscription events sent to Klaviyo include a comprehensive payload containing information about the subscription contract, customer, line items, pricing, delivery, and payment details. The event data structure is consistent across all event types.

Event Types

The following subscription events send data to Klaviyo:

Subscription Contract Create - When a new subscription is created
Subscription Contract Pause - When a subscription is paused
Subscription Contract Activate - When a subscription is activated/resumed
Subscription Contract Cancel - When a subscription is cancelled
Billing Attempt Success - When a billing attempt succeeds
Billing Attempt Failure - When a billing attempt fails
Order Skipped - When a subscription order is skipped
Order Unskipped - When a previously skipped order is unskipped

Complete Payload Structure

Top-Level Fields

Field	Type	Description	Example
`contractId`	string	Unique identifier for the subscription contract	`"44017680677"`
`currencyCode`	string	Three-letter currency code	`"USD"`
`linesCount`	number	Total number of line items in the subscription	`2`
`isPrepaid`	boolean	Whether this is a prepaid subscription	`false`
`manageSubscriptionUrl`	string	URL where customers can manage their subscription	`"https://shopify.com/..."`
`merchantSupportEmail`	string or null	Merchant's support email address	`"[email protected]"`

Customer Object

Contains detailed information about the subscriber:

Field	Type	Description	Example
`customer.id`	string	Unique customer identifier	`"1000000000000"`
`customer.email`	string	Customer's email address	`"[email protected]"`
`customer.firstName`	string or null	Customer's first name	`"John"`
`customer.lastName`	string or null	Customer's last name	`"Doe"`
`customer.displayName`	string or null	Customer's full display name	`"John Doe"`
`customer.lifetimeDuration`	string or null	How long the customer has been active	`"about 2 months"`
`customer.locale`	string or null	Customer's locale/language	`"en-US"`
`customer.numberOfOrders`	number or null	Total orders placed by customer	`5`
`customer.tags`	array of strings	Customer tags	`["kaching-subscriber"]`
`customer.isEmailVerified`	boolean or null	Whether email is verified	`true`

Common Customer Tags:

kaching-subscriber - Customer has at least one subscription
kaching-has-active-subscription - Has an active subscription
kaching-has-paused-subscription - Has a paused subscription
kaching-has-cancelled-subscription - Has a cancelled subscription
kaching-has-payment-failure - Has experienced payment failures

Line Items Array

Each subscription can have multiple line items. Access via lines array:

Field	Type	Description	Example
`lines[].title`	string	Product title	`"Premium Coffee"`
`lines[].variantTitle`	string or null	Variant title (e.g., size, color)	`"Medium Roast"`
`lines[].productId`	string or null	Unique product identifier	`"10000000000001"`
`lines[].variantId`	string or null	Unique variant identifier	`"10000000000002"`
`lines[].quantity`	number	Quantity of this line item	`2`
`lines[].variantImageUrl`	string or null	URL to variant image	`"https://..."`
`lines[].variantImageAltText`	string or null	Alt text for image	`"Coffee bag"`
`lines[].lineDiscountedPrice`	number	Line total after discounts (numeric)	`10.00`
`lines[].lineDiscountedPriceFormatted`	string	Formatted price with currency symbol	`"$10.00"`

Pricing Information

All monetary values are provided in both raw and formatted versions:

Subtotal:

subtotalPrice.amount (number): Raw subtotal amount
subtotalPrice.currencyCode (string): Currency code
subtotalPriceFormatted (string): Formatted subtotal (e.g., "$20.00")

Shipping:

totalShippingPrice.amount (number): Raw shipping amount
totalShippingPrice.currencyCode (string): Currency code
totalShippingPriceFormatted (string): Formatted shipping (e.g., "$10.00")

Total:

totalPrice.amount (number): Raw total amount
totalPrice.currencyCode (string): Currency code
totalPriceFormatted (string): Formatted total (e.g., "$30.00")

Next Order Information

Details about the upcoming order:

Field	Type	Description	Example
`nextOrderDate`	string or null	ISO 8601 date in customer's timezone	`"2027-11-25T13:00:00.000+02:00"`
`humanReadableNextOrderDate`	string or null	Formatted date for display	`"November 25, 2027"`
`nextCycleIndex`	number or null	The cycle number for next order	`1`

Modified Order Information

When an order is skipped or unskipped, these fields contain the modified order details:

Field	Type	Description	Example
`modifiedOrderDate`	string or null	ISO 8601 date of modified order	`"2026-11-20T15:00:00-05:00"`
`humanReadableModifiedOrderDate`	string or null	Formatted modified date	`"November 20, 2026"`
`modifiedCycleIndex`	number or null	The cycle number that was modified	`1`

Note: These fields are only populated for order_skipped and order_unskipped events.

Delivery Schedule

Information about when products are delivered:

Field	Type	Description	Possible Values
`deliveryInterval`	string	Time unit for delivery	`"DAY"`, `"WEEK"`, `"MONTH"`, `"YEAR"`
`deliveryFrequency`	number	Number of intervals between deliveries	`1`, `2`, `3`, etc.

Examples:

Deliver every month: deliveryInterval: "MONTH", deliveryFrequency: 1
Deliver every 2 weeks: deliveryInterval: "WEEK", deliveryFrequency: 2

Billing Schedule:

Information about when payments are processed:

Field	Type	Description	Possible Values
`billingInterval`	string	Time unit for billing	`"DAY"`, `"WEEK"`, `"MONTH"`, `"YEAR"`
`billingFrequency`	number	Number of intervals between billing	`1`, `2`, `3`, etc.
`maxCycles`	number or null	Maximum number of billing cycles	`12` or `null`
`minCycles`	number or null	Minimum number of billing cycles	`3` or `null`

Delivery Method

Shipping or local delivery details.

The structure varies by delivery type.

For shipping delivery (typename: "SubscriptionDeliveryMethodShipping"):

{
  "typename": "SubscriptionDeliveryMethodShipping",
  "address": {
    "address1": "2515 South Broad Street",
    "address2": null,
    "city": "Linden",
    "province": "New Jersey",
    "provinceCode": "NJ",
    "countryCodeV2": "US",
    "zip": "07036",
    "firstName": "John",
    "lastName": "Doe",
    "phone": null
  },
  "shippingOption": {
    "title": "Standard shipping",
    "presentmentTitle": "Standard shipping"
  }
}

For local delivery (typename: "SubscriptionDeliveryMethodShipping"):

{
  "typename": "SubscriptionDeliveryMethodLocalDelivery",
  "address": {
    "address1": "123 Main Street",
    "address2": "Apt 4",
    "city": "Portland",
    "province": "Oregon",
    "provinceCode": "OR",
    "countryCodeV2": "US",
    "zip": "97201",
    "firstName": "Jane",
    "lastName": "Smith",
    "phone": "+15551234567"
  },
  "localDeliveryOption": {
    "title": "Local Delivery",
    "presentmentTitle": "Same-Day Local Delivery"
  }
}

For pickup (typename: "SubscriptionDeliveryMethodPickup"):

{
  "typename": "SubscriptionDeliveryMethodPickup",
  "pickupOption": {
    "title": "In-Store Pickup",
    "presentmentTitle": "Pick up at Downtown Store"
  }
}

You can find out more about delivery method object structure in the official Shopify API docs: SubscriptionDeliveryMethod.

Payment Method

Details about the customer's payment method:

Field	Type	Description	Example
`paymentMethod.id`	string	Unique payment method identifier	`"gid://shopify/..."`
`paymentMethod.typename`	string	Type of payment method	`"CustomerPaymentMethod"`
`paymentMethod.revokedAt`	string or null	When the payment method was revoked	`null`
`paymentMethod.revokedReason`	string or null	Why the payment method was revoked	`null`

Payment Instrument (for Credit Cards):

When paymentMethod.instrument.typename is "CustomerCreditCard":

{
  "typename": "CustomerCreditCard",
  "brand": "visa",
  "lastDigits": "4242",
  "billingAddress": {
    "firstName": "John",
    "lastName": "Doe",
    "address1": "2515 South Broad Street",
    "province": "New Jersey",
    "countryCode": "US",
    "city": "Linden",
    "zip": "07036"
  }
}

Possible Card Brands:

visa
mastercard
american_express
discover
etc.

You can find out more about payment method object structure in the official Shopify API docs: CustomerPaymentMethod.

Example event data

{
  "subtotalPrice": {
    "currencyCode": "USD",
    "amount": 20
  },
  "humanReadableNextOrderDate": "November 25, 2025",
  "contractId": "44017680677",
  "currencyCode": "USD",
  "deliveryInterval": "MONTH",
  "isPrepaid": false,
  "subtotalPriceFormatted": "$20.00",
  "modifiedOrderDate": null,
  "manageSubscriptionUrl": "https://shopify.com/",
  "merchantSupportEmail": "[email protected]",
  "customer": {
    "numberOfOrders": "0",
    "lastName": "John",
    "firstName": "Doe",
    "id": "9313802453285",
    "displayName": "John Doe",
    "tags": [
      "kaching-has-active-subscription",
      "kaching-has-cancelled-subscription",
      "kaching-has-paused-subscription",
      "kaching-has-payment-failure",
      "kaching-subscriber"
    ],
    "lifetimeDuration": "about 2 months",
    "locale": "en-US",
    "email": "[email protected]",
    "isEmailVerified": true
  },
  "totalShippingPrice": {
    "currencyCode": "USD",
    "amount": "10.0"
  },
  "nextOrderDate": "2025-11-25T13:00:00.000+02:00",
  "deliveryMethod": {
    "typename": "SubscriptionDeliveryMethodShipping",
    "shippingOption": {
      "title": "Standard shipping",
      "presentmentTitle": "Standard shipping"
    },
    "address": {
      "address1": "2515 South Broad Street",
      "lastName": "Doe",
      "address2": null,
      "province": "New Jersey",
      "phone": null,
      "firstName": "John",
      "provinceCode": "NJ",
      "zip": "07036",
      "countryCodeV2": "US",
      "city": "Linden"
    }
  },
  "totalPriceFormatted": "$30.00",
  "billingInterval": "MONTH",
  "nextCycleIndex": 1,
  "paymentMethod": {
    "id": "gid://shopify/CustomerPaymentMethod/1283f7016e680465b7ab15f47d971432",
    "instrument": {
      "lastDigits": "4242",
      "typename": "CustomerCreditCard",
      "billingAddress": {
        "address1": "2515 South Broad Street",
        "lastName": "Doe",
        "firstName": "John",
        "province": "",
        "countryCode": "US",
        "zip": "07036",
        "city": "Linden"
      },
      "brand": "visa"
    },
    "revokedAt": null,
    "revokedReason": null
  },
  "billingFrequency": 1,
  "totalPrice": {
    "currencyCode": "USD",
    "amount": 30
  },
  "linesCount": 2,
  "maxCycles": null,
  "modifiedCycleIndex": null,
  "minCycles": null,
  "totalShippingPriceFormatted": "$10.00",
  "lines": [
    {
      "variantImageUrl": "https://cdn.shopify.com/s/files/1/0957/5756/6245/files/hat.jpg?v=1761388161",
      "lineDiscountedPriceFormatted": "$10.00",
      "quantity": 1,
      "variantTitle": null,
      "variantId": "51451354349861",
      "title": "Hat",
      "productId": "10200405147941",
      "lineDiscountedPrice": "10.0",
      "variantImageAltText": null
    },
    {
      "variantImageUrl": "https://cdn.shopify.com/s/files/1/0957/5756/6245/files/shirt.jpg?v=1761388177",
      "lineDiscountedPriceFormatted": "$10.00",
      "quantity": 1,
      "variantTitle": null,
      "variantId": "51451354415397",
      "title": "Blue Shirt",
      "productId": "10200405213477",
      "lineDiscountedPrice": "10.0",
      "variantImageAltText": null
    }
  ],
  "deliveryFrequency": 1,
  "humanReadableModifiedOrderDate": null
}

Practical Examples for Email Templates

Example 1: Personalized Greeting with Order Total:

Hi {{ event.customer.firstName }},
Your next subscription order of {{ event.totalPriceFormatted }} will be processed on {{ event.humanReadableNextOrderDate }}.

Output:

Hi John,
Your next subscription order of $30.00 will be processed on November 25, 2027.

Example 2: List All Subscription Items

Your subscription includes:
{% for line in lines %}
- {{ line.quantity }}x {{ line.title }}{% if line.variantTitle %} ({{ line.variantTitle }}){% endif %} - {{ line.lineDiscountedPriceFormatted }}
{% endfor %}

Output:

Your subscription includes:
- 1x Hat - $10.00
- 1x Blue Shirt - $15.00

Example 3: Display Delivery Schedule

You'll receive deliveries every {{ deliveryFrequency }} {{ deliveryInterval | downcase }}{% if deliveryFrequency > 1 %}s{% endif %}.

Output:

You'll receive deliveries every 1 month. You'll receive deliveries every 2 weeks.

Important Notes

Date Formats

nextOrderDate and modifiedOrderDate are ISO 8601 formatted strings in the customer's timezone
humanReadableNextOrderDate and humanReadableModifiedOrderDate are pre-formatted strings ready for display, localized based on the customer's locale

Price Formats

Use the *Formatted fields (e.g., totalPriceFormatted) for display in emails - these include the currency symbol and proper formatting
Use the .amount fields (e.g., totalPrice.amount) for calculations or comparisons

Null Values

Many fields can be null if the information is not available
Always check for null values in your templates to avoid display issues

Customer Tags

Use customer tags to segment and personalize your communications
Tags are automatically managed by the app based on subscription status

Delivery Method Types

Always check deliveryMethod.typename to determine which fields are available
Shipping and Local Delivery have address objects, while Pickup has pickupOption

Testing Your Templates

You can send test events from the Klaviyo integration settings page to verify your email templates work correctly with real subscription data. Test events are available for all event types.

Need help? Drop us a message in the live chat, and we'll sort it out together.