> For the complete documentation index, see [llms.txt](https://subscriptions-docs.tech-arms.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://subscriptions-docs.tech-arms.io/features/integrations/klaviyo.md).

# Klaviyo

Connect Klaviyo to send subscription events, such as new subscriptions, pauses, and failed payments, and use them in your Klaviyo flows and segments.

[**Klaviyo**](https://apps.shopify.com/klaviyo-email-marketing) is an email and SMS marketing platform. When you connect it, TA Subscriptions App sends an event to Klaviyo each time something happens to a subscription, for example when a customer pauses or a payment fails.

In Klaviyo, you can use these events to:

* trigger flows, such as a win-back email after a cancellation,
* build segments, such as customers who paused in the last 30 days,
* personalize messages with subscription details.

TA Subscriptions App only sends the events. You build the flows, emails, and segments in Klaviyo.

## Connect Klaviyo

{% stepper %}
{% step %}

### Create a private API key in Klaviyo

In your Klaviyo account settings, open **API keys** and create a **private API key**. It starts with `pk_`.

Give the key **Full Access**, or at least these scopes:

* **Events**: Full Access
* **Metrics**: Full Access
* **Profiles**: Read Access

Copy the key. Klaviyo shows it only once.
{% endstep %}

{% step %}

### Open the Klaviyo integration

In the app menu, click **Settings**, then click the **Integrations** card. On the **Klaviyo** card, click **Configure**.

![The Klaviyo card on the Integrations page with the Configure button highlighted](https://3752025337-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F479XnzvtVA5dDE3Rt2Uh%2Fuploads%2FWCJhVTlJLhXHDXCJXQzu%2Fklaviyo-card.png?alt=media)
{% endstep %}

{% step %}

### Paste your key and connect

In the **API Key** card, paste your key into **Private API key** and click **Connect**.

The first time you connect, the **Enable Klaviyo integration** window opens. Read the privacy notice, tick **I understand and agree to share subscription events with Klaviyo**, and click **Confirm**.

![The API Key card with the Private API key field and Connect button highlighted](https://3752025337-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F479XnzvtVA5dDE3Rt2Uh%2Fuploads%2FMIUGl3vROZzmpL8GKi1X%2Fklaviyo-api-key.png?alt=media)

When the key works, the badge changes to **Connected** and the **Subscription Events** card appears.

If you see "That key didn't work. Check it in your Klaviyo account and try again.", check that you copied the whole private key and that it has the scopes above.

{% hint style="info" %}
When you connect, the app sends one sample of each event to Klaviyo, using your store's email address. This makes all event names appear in Klaviyo right away, so you can pick them when you build a flow.
{% endhint %}
{% endstep %}

{% step %}

### Turn on the events you want

In **Subscription Events**, turn on the switch next to each event you want to send. All events are off until you turn them on. When a switch is on, the row shows its **Flow trigger metric**: the event name to use in Klaviyo. Click **Copy** to copy it.

Click **Save** in the bar at the top of the page.
{% endstep %}

{% step %}

### Check that the integration is active

The badge next to the **Klaviyo** title shows **Active** or **Inactive**. Events are sent only while it is **Active**. If it shows **Inactive** right after you connect, reload the page.

On the **Integrations** page, the Klaviyo card shows **Integrated** once the integration is active and at least one event is turned on.
{% endstep %}
{% endstepper %}

## Events

| Event in the app                  | Flow trigger metric in Klaviyo | When it is sent                                                      |
| --------------------------------- | ------------------------------ | -------------------------------------------------------------------- |
| **New subscription**              | TA Subscription New            | A new subscription is created.                                       |
| **Subscription expired**          | TA Subscription Expired        | A subscription expires.                                              |
| **Subscription paused**           | TA Subscription Paused         | A subscription is paused.                                            |
| **Subscription resumed**          | TA Subscription Resumed        | A subscription becomes active again, for example after a pause.      |
| **Subscription cancelled**        | TA Subscription Cancelled      | A subscription is cancelled.                                         |
| **Payment failed (retrying)**     | TA Payment Failed Retry        | A payment fails and will be retried. Sent after each failed attempt. |
| **Payment failed (last attempt)** | TA Payment Failed Last Attempt | The last retry fails.                                                |
| **Order skipped**                 | TA Order Skipped               | An upcoming order is skipped.                                        |
| **Subscription reminder**         | TA Subscription Reminder       | Before the next order is billed. See the note below.                 |

{% hint style="warning" %}
**Subscription reminder** is sent only when the **Upcoming Order Reminder Email** is turned on in [Email Notifications](https://subscriptions-docs.tech-arms.io/features/email-notifications/email-notifications.md). This email is available on some plans only. The other events are sent whether the matching emails are on or off.
{% endhint %}

There is no event for a successful renewal payment. To follow renewals in Klaviyo, use the Shopify order data that Klaviyo already receives. If you turn on the **Recurring Order** rule in [Auto Tag](https://subscriptions-docs.tech-arms.io/features/email-notifications/auto-tag.md), renewal orders carry a tag you can filter on.

## Data sent with each event

Each event is added to the customer's Klaviyo profile, matched by email address. The app sends the customer's **email**, **first name**, and **last name**, plus these event properties:

| Property                        | Use in a Klaviyo template                   | What it contains                                                                   |
| ------------------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------- |
| `order_id`                      | `{{ event.order_id }}`                      | The subscription ID. Despite its name, it is not a Shopify order number.           |
| `customer_id`                   | `{{ event.customer_id }}`                   | The customer's Shopify customer ID.                                                |
| `contract_status`               | `{{ event.contract_status }}`               | The subscription status: `ACTIVE`, `PAUSED`, `CANCELLED`, `EXPIRED`, or `FAILED`.  |
| `billing_policy_interval`       | `{{ event.billing_policy_interval }}`       | The billing unit: `DAY`, `WEEK`, `MONTH`, or `YEAR`.                               |
| `billing_policy_interval_count` | `{{ event.billing_policy_interval_count }}` | How many units between billings. For example, `2` with `WEEK` means every 2 weeks. |
| `currency_code`                 | `{{ event.currency_code }}`                 | The subscription currency, for example `USD`.                                      |
| `delivery_price`                | `{{ event.delivery_price }}`                | The shipping price of each order.                                                  |
| `total_amount`                  | `{{ event.total_amount }}`                  | The subscription total.                                                            |

Events do not include product names, the next billing date, or a link to the customer portal.

{% hint style="info" %}
Add a default value so the email still looks right if a property is empty, for example `{{ event.total_amount|default:0 }}`.
{% endhint %}

## Use the events in Klaviyo

### Build a flow

1. In Klaviyo, create a new flow and build it from scratch.
2. As the trigger, choose a metric. Pick the **Flow trigger metric** name you copied from the app, for example **TA Subscription Cancelled**.
3. Add your emails or SMS messages and turn the flow on.

### Build a segment

In Klaviyo, create a segment and use a condition based on what someone has done. Pick a metric from the table above, for example customers who triggered **TA Subscription Paused** in the last 30 days.

{% hint style="warning" %}
If a Klaviyo flow replaces one of the app's emails, turn that email off in [Email Notifications](https://subscriptions-docs.tech-arms.io/features/email-notifications/email-notifications.md) so customers do not get two messages. This does not work for the reminder: **Subscription reminder** needs the app's reminder email to stay on.
{% endhint %}

## Send a test event

Use a test event to check a flow before real customers trigger it.

{% stepper %}
{% step %}

### Turn on and save the event

The event switch must be on and saved, and the integration must be **Active**.
{% endstep %}

{% step %}

### Send the test

Click **Send test event** under the event. In the **Send test event** window, enter an **Email address** and click **Send**. "Sent successfully" appears when Klaviyo receives the event.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
Use your own email address. A test event sets the profile's name to the store owner's name and has empty event properties. If you use a customer's email, their name in Klaviyo is overwritten.
{% endhint %}

## Change your API key

Click the edit icon next to your saved key. In the **Edit API key** window, paste the new key and click **Save**.

Saving a new key sends the sample events to your store's email address again. If you have live flows on these metrics, you may receive their messages.

## Pause or disconnect Klaviyo

* **To stop sending all events**, click **Deactivate** at the top of the page. The badge changes to **Inactive**. Click **Activate** to start again. Your key and event choices are kept.
* **To stop one event**, turn off its switch and click **Save**.
* **To remove access completely**, deactivate the integration, then delete the private API key in your Klaviyo account. The app still shows **Connected**, because it does not check the key again.

Events already sent stay in Klaviyo. Remove them in Klaviyo if you need to.

## Troubleshooting: events don't appear in Klaviyo

Check these in order:

1. **The integration is Inactive**, or the event switch was turned on but not saved.
2. **The key was deleted or changed in Klaviyo.** The app still shows **Connected**. Click the edit icon and save a working key.
3. **The key is missing a scope.** The app can connect with a key that only reads profiles, but events then fail. Use a key with the scopes listed above.
4. **The reminder conditions are not met.** See the note under [Events](#events).
5. **The customer has no email address.** Events are matched to profiles by email, so they cannot be sent.

To see what arrived, open the metric in Klaviyo's analytics, or open the customer's profile and check its activity. Failed events are not sent again. If you still can't find them, contact us.

## Privacy and data sharing

Connecting Klaviyo shares customer and subscription data with Klaviyo: the customer's email and name, and the event properties listed above. Payment details and Shopify login details are never shared. Klaviyo processes the data under its own privacy policy. You are responsible for following privacy laws and getting any customer consent they require.

## Good to know

* Only events that happen after you connect and turn them on are sent. Past subscription activity is not sent.
* The Klaviyo integration is available on every pricing plan. Only **Subscription reminder** depends on your plan.
* Klaviyo is a separate service. For questions about flows, segments, or your Klaviyo account, contact Klaviyo support.

*If you need help, feel free to reach out to us via in-app* [***Live chat***](https://go.crisp.chat/chat/embed/?website_id=c4ae10a3-f762-4968-b35a-c931caf62a96)***,*** [***Book a call***](https://calendly.com/ta-subscription-app-support/30min) *or at* [***support@tech-arms.io***](mailto:support@tech-arms.io)***.***


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://subscriptions-docs.tech-arms.io/features/integrations/klaviyo.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
