Integration Settings
The Integrations tab lets you connect Zubs with third-party services to sync subscription data and power marketing automation.
Currently Available:
- Klaviyo (Email Marketing & Analytics)
- Shopify Flow (Automation & Workflows)
Klaviyo Integration
Klaviyo is an email and SMS marketing platform. The Zubs integration sends subscription events and sets custom profile properties in Klaviyo, enabling subscription-aware marketing automation.
Connecting Klaviyo
- Open Settings → Integrations in your Zubs merchant portal
- Find the Klaviyo card and click Connect
- Log in to your Klaviyo account when prompted
- Allow access for Zubs to connect
Once connected, the status shows Connected with a green indicator and events start syncing in real-time.
Events
Zubs automatically sends the following events to Klaviyo as metrics. You can use these to trigger flows, build segments, and create campaigns. These events fire whenever your Klaviyo integration is connected, independent of your native Zubs email notification toggles.
Until November 3, 2026, 12:00 UTC, Zubs also sends the older event names below, alongside the current names. At that time the older names stop. If a flow, segment, or report uses an older name, switch it to the current name before then:
- Flows: Klaviyo doesn't let you change the trigger of an existing flow. Clone the flow, pick the current name as the trigger, then turn off the original. While both names are sent, a flow on each name would email the customer twice, so turn off the flow on the older name as soon as the new one is live.
- Segments and reports: Klaviyo keeps history per event name, so a segment or report on the current name starts from the day it first receives events.
| Older Name | Current Name |
|---|---|
Zubs: Renewal Successful (Timeline) | Zubs: Renewal Successful |
Zubs: Billing Failure (Timeline) | Zubs: Billing Failure |
Zubs: Payment Attempt Failed (Attempt 1) | Zubs: Billing Failure with the trigger filter failure_type = payment and dunning_stage = retry |
Zubs: Payment Attempt Failed (Attempt 2) | Zubs: Billing Failure with the trigger filter failure_type = payment and dunning_stage = last_retry |
Zubs: Payment Attempt Failed (Attempt 3) | Zubs: Billing Failure with the trigger filter failure_type = payment and dunning_stage = exhausted |
Zubs: Inventory Failure | Zubs: Billing Failure with the trigger filter failure_type = inventory |
Zubs: Inventory Failure (Timeline) | Zubs: Billing Failure with the trigger filter failure_type = inventory |
Zubs: Subscription Event | Zubs: Billing Failure with the trigger filter failure_type = inventory, for inventory failures. The per-attempt payment-failure alert for merchants, also sent under this name, has no replacement. |
Zubs: Order Skipped (Timeline) | Zubs: Order Skipped |
Zubs: Order Unskipped (Timeline) | Zubs: Order Unskipped |
Zubs: Subscription Items Updated (Timeline) | Zubs: Subscription Items Updated |
Zubs: Frequency Changed (Timeline) | Zubs: Frequency Changed |
Zubs: Shipping Address Changed (Timeline) | Zubs: Shipping Address Changed |
Zubs: Ship Now Initiated (Timeline) | Zubs: Ship Now Initiated |
Zubs: Billing Date Changed (Timeline) | Zubs: Billing Date Changed |
Zubs: Delivery Method Changed (Timeline) | Zubs: Delivery Method Changed |
Zubs: Discount Added (Timeline) | Zubs: Discount Added |
Zubs: Billing Failure carries its own set of billing failure properties, which differ from the properties on every older billing and inventory failure event, including Zubs: Billing Failure (Timeline). It's also sent a little later than the older events: once Zubs has handled the failed attempt, not when Shopify reports it. Check the filters and template variables of a billing or inventory flow when you switch it.
The merchant-only events stop at the same time without a replacement.
Subscription Lifecycle Events
| Event Name | Triggered When |
|---|---|
Zubs: Subscription Created | Customer starts a new subscription |
Zubs: Subscription Cancelled | Subscription is cancelled |
Zubs: Subscription Paused | Customer pauses their subscription |
Zubs: Subscription Reactivated | Paused subscription is resumed |
Billing & Payment Events
| Event Name | Triggered When |
|---|---|
Zubs: Billing Failure | A billing attempt fails, because the payment failed or an item is out of stock. Sent once per failed attempt that Zubs handles: after it has scheduled the next retry or, on the last attempt, taken your on-failure action (skip, cancel, or pause). It isn't sent for a failure on a subscription that's already cancelled or an order that's already paid. |
Zubs: Renewal Successful | A billing attempt succeeds |
Billing Failure Properties
Zubs: Billing Failure fires on every failed attempt Zubs handles, not just the first or the last. Use a trigger filter on these properties to pick the attempts a flow should react to:
| Property | Type | Description |
|---|---|---|
failure_type | String | payment when the charge failed, inventory when an item is out of stock |
attempt_number | Number | Which attempt this was for the current order, counting the first charge as 1. Payment and out-of-stock attempts on the same order count together |
total_attempts | Number | How many attempts your dunning settings allow in total: the first charge plus every retry |
attempts_remaining | Number | How many more retries your dunning settings allow after this one |
is_final_attempt | Boolean | true when no retry is left and your on-failure action has run |
dunning_stage | String | retry, last_retry (the next attempt is the last one), or exhausted (no retry left) |
next_attempt_date | String | Date of the next retry in UTC, e.g. 2026-11-10. Not set on the final attempt |
terminal_action | String | Your on-failure action from the dunning settings: cancelled, paused, or skipped. Only set on the final attempt |
errorCode | String | Shopify's error code for the failed attempt |
errorMessage | String | Shopify's error message for the failed attempt |
amountAttempted | String | The amount Zubs tried to charge, when Shopify reports it |
currencyCode | String | Currency of amountAttempted |
billingCycleIndex | Number | Which billing cycle of the subscription the failed order belongs to |
Common trigger filters:
- First failure:
attempt_numberequals1 - Last chance before the final attempt:
dunning_stageequalslast_retry - Retries used up:
is_final_attemptistrue - Out-of-stock problems only:
failure_typeequalsinventory
A flow triggered by Zubs: Billing Failure without a trigger filter runs on every failed attempt, so a customer can receive the same email several times for one order.
Order & Change Events
| Event Name | Triggered When |
|---|---|
Zubs: Upcoming Order Reminder | Configurable days before next billing |
Zubs: Order Skipped | A billing cycle is marked as skipped |
Zubs: Order Unskipped | A billing cycle is marked as unskipped |
Zubs: Subscription Items Updated | Customer modifies subscription items |
Zubs: Frequency Changed | Customer changes billing frequency |
Zubs: Shipping Address Changed | Customer updates shipping address |
Zubs: Customer Details Changed | Customer updates their details |
Zubs: Ship Now Initiated | Customer triggers an immediate shipment |
Zubs: Billing Date Changed | A billing date moves to a different day |
Zubs: Delivery Method Changed | Customer changes the delivery method of a subscription |
Zubs: Discount Added | A discount code is applied to a subscription |
Merchant-Only Events
Zubs sends these events until November 3, 2026, 12:00 UTC. They have no replacement in Klaviyo.
| Event Name | Triggered When |
|---|---|
Zubs: Payment Attempt Failed (Attempt 3, Merchant) | Final payment attempt fails (merchant notification) |
Zubs: Inventory Failure (Merchant) | Insufficient inventory for a subscription order |
Each event includes rich metadata such as subscription details, product information, billing data, and customer context. Use Klaviyo's flow builder to personalize emails based on this event data.
Event Properties
For subscriptions that use a Custom Pickup Location, every subscription event above, including the upcoming-order reminder, carries a nested pickup_location object in its event properties. Zubs: Customer Details Changed belongs to the customer, not to a subscription, so it has no pickup_location:
| Property | Type | Description |
|---|---|---|
pickup_location.name | String | Name of the pickup location (always set when pickup_location is present) |
pickup_location.address | String | Street address of the pickup location (optional) |
pickup_location.country_code | String | ISO country code of the pickup location (optional) |
pickup_location.expected_delivery_day | String | Expected delivery day, e.g. "Wednesday" (optional) |
Subscriptions without a Custom Pickup Location do not have a pickup_location key on their events.
Use dot notation in Klaviyo flows and segment filters, e.g. pickup_location.country_code equals "DE" to segment pickup customers in Germany, or {{ event.pickup_location.name }} to personalize a template with the store name.
Zubs: Upcoming Order Reminder also tells you whether the upcoming order contains one-time items, and whether your customer picked them:
| Property | Type | Description |
|---|---|---|
has_one_time_items | Boolean | true when the upcoming order contains at least one one-time item |
has_customer_selected_one_time_items | Boolean | true when your customer picked at least one of those one-time items themselves. Items placed by Default Item Fill, a Sequential Flow or a Shopify Flow action don't count. |
activeContract.lines[].isOneTime | Boolean | true for a one-time item, false for a recurring subscription item |
activeContract.lines[].isCustomerSelected | Boolean | true for a one-time item your customer picked themselves |
To remind customers who haven't chosen their items yet, filter a flow on has_customer_selected_one_time_items equals false.
Custom Profile Properties
Zubs sets the following custom properties on each customer's Klaviyo profile. These are updated automatically whenever a subscription event occurs and can be used for segmentation and personalization.
| Property | Type | Description | Example |
|---|---|---|---|
zubs_is_active_subscriber | Boolean | Whether the customer has at least one active subscription | true |
zubs_active_subscription_count | Number | Number of active subscriptions | 2 |
zubs_active_variant_ids | String | Semicolon-separated numeric Shopify variant IDs | 12345;67890 |
zubs_active_variant_names | String | Semicolon-separated variant names | Dark Roast - 1kg;Medium Roast - 500g |
zubs_subscription_frequencies | String | Semicolon-separated delivery frequencies per subscription | 11111:1 MONTH;22222:2 WEEK |
zubs_has_pickup_subscription | Boolean | Whether the customer has at least one active subscription with a Custom Pickup Location | true |
zubs_active_pickup_locations | String | Semicolon-separated subscriptionId:pickupLocationName per pickup-enabled subscription | 11111:Main Street Store;22222:Downtown Café |
The zubs_subscription_frequencies format is subscriptionId:intervalCount INTERVAL, where the interval is one of DAY, WEEK, MONTH, or YEAR. It tells you how often the customer receives a delivery, not how often they're charged. For most plans those are the same, but they differ on prepaid plans where one charge covers several deliveries: a customer on "delivered every 3 months, paid for 3 up front" shows 3 MONTH.
Use these properties to build Klaviyo segments such as:
- Active subscribers —
zubs_is_active_subscriberistrue - Multi-subscription customers —
zubs_active_subscription_countgreater than 1 - Customers subscribed to a specific product —
zubs_active_variant_idscontains a variant ID - Non-subscribers —
zubs_is_active_subscriberisfalse(for win-back campaigns) - Pickup customers —
zubs_has_pickup_subscriptionistrue(for collection reminders or pickup-specific flows)
Test Connection
After connecting Klaviyo, use the Test connection button on the integration card to verify everything works and to make every current Zubs event available as a flow trigger.
How to use:
- Click Test connection on the Klaviyo integration card
- Open Klaviyo and search for the profile with email
info@zubs.app - Verify that the
Zubs: Test Connectionevent, the current event names listed above and thezubs_test_connection_verified_atproperty appear on the profile
What happens:
- A profile is created (or updated) in Klaviyo using the
info@zubs.appemail address. Real customer profiles are not affected - A
Zubs: Test Connectionevent is sent to that profile - Every current event name listed above is sent to that profile as an empty test event, once per test. Each one carries only the property
zubs_testset totrue, so it becomes available as a flow trigger. The older names and the merchant-only events are not part of the test - A
zubs_test_connection_verified_attimestamp is set on the profile. The other custom profile properties are left untouched
The full properties described above arrive with real activity in your store, for example a new subscription, a skipped order or a scheduled order reminder. Test events count in your Klaviyo metrics like any other event and can trigger flows for the info@zubs.app test profile.
Backfill Data
The Backfill data button syncs profile properties for all existing customers with active subscriptions. This is useful when you first connect Klaviyo or need to re-sync profile data.
When to use:
- After first connecting Klaviyo (existing subscribers won't have profile properties yet)
- After reconnecting a previously disconnected integration
- If you suspect profile data is out of sync
What happens:
- Zubs iterates through all customers with active subscriptions in your store
- For each customer, it computes and sets the custom profile properties listed above
- The process runs in the background — you can close the page
Backfilling can take a while depending on the number of active subscribers. You'll see a confirmation dialog before starting. Only run a backfill if you are aware it may take some time to complete.
Customer Hub Integration
Integration with the Customer Hub (customer-facing portal) is not yet available. Currently, the Klaviyo integration only syncs data from the merchant portal side (Shopify admin). Customer Hub support is planned for a future release.
Shopify Flow
Shopify Flow is Shopify's built-in automation builder. Zubs integrates natively — no connection step is needed. The integration is always available and appears in your Integrations tab with an Available status.
From the integration card you can jump directly into the Shopify Flow builder or read the documentation. Once in Flow, you can use Zubs triggers (subscription created, renewal successful, billing failure, and more) as starting points for automations, and Zubs actions (cancel subscription, skip next cycle, add free item, fetch subscription contracts) as steps within a flow.
See the Shopify Flow Integration article for the full list of triggers and actions.
Disconnecting Integrations
- Navigate to Settings → Integrations
- Find the connected integration and click Disconnect
- Confirm disconnection
What happens:
- Data sync stops immediately
- Future events will not be sent
- Existing data remains in Klaviyo
- You can reconnect at any time
Troubleshooting
Events Not Appearing in Klaviyo
- Check that the integration status shows Connected
- Use the Test connection button to verify the connection works
- The test sends each current event name as an empty event marked
zubs_test. The full event properties appear once the matching activity happens in your store - Events sync in real-time but may take up to a minute to appear
Test Connection Fails
- Check your network connection
- Try again in a few minutes — Klaviyo may be temporarily unavailable
- When the
Zubs: Test Connectionevent fails, the other event names aren't sent. Run the test again once it passes to make them available as triggers - Contact support if the issue persists
Related Resources
- Notification Settings — Configure Zubs native email notifications
- General Settings — Set up subscription features and retention