Subscription Flow triggers

This document describes the data payloads available within Shopify Flow when subscription events are triggered by Submarine.

Trigger Payload Overview

The payload structure depends on whether the trigger is at the subscription level or the subscription order level. Both triggers share common top-level keys, but differ in how order data is exposed.

Key difference: In a subscription trigger, the order data is only available nested under subscription.nextScheduledOrder. In an order trigger, the same order data is also available as a top-level subscriptionOrder object, which additionally includes a diff object tracking changes to the order.

Note: The subscription.deliveryMethod may be null in order-level triggers. When this occurs, the delivery address is still available on the subscriptionOrder object itself.

Available Flow Triggers

Subscription Created

A customer's subscription has been created by Submarine.

Name	Object	Type	Description
Active subscription count	Customer Activity	Integer	A count of active subscriptions for this customer
Lifetime subscription count	Customer Activity	Integer	A count of all subscriptions ever created by this customer
Customer email	Customer (Shopify)	Email	The email address of the customer
Customer information	Customer (Shopify)	Various	The customer data available from Shopify, includes total order count, customer tags, metafields, orders
Custom attributes	Subscription	Array	Metadata key-value pairs attached to the subscription (e.g. delivery day, frequency, postcode)
Delivery method	Subscription	Address	The delivery address set for the subscription, including phone number
ID	Subscription	String	The Submarine unique ID used to reference the subscription
Identifier	Subscription	String	The human-readable subscription identifier used in the Submarine UI (e.g. `#1008`)
Line items	Subscription	Array	The products associated with the subscription
Next scheduled order	Subscription	Various	The next scheduled order, including delivery method, billing/delivery dates, financials, lines and status
Source	Subscription	Object	The originating Shopify order that created this subscription
Status	Subscription	String	The status of the subscription (e.g. `active`, `paused`, `cancelled`)
Subscription discounts	Subscription	Array	Any discounts currently applied to the subscription
Subscription group	Subscription	Object	References a relationship between subscriptions created at the same time with different frequencies
Subscription plan	Subscription	Object	The subscription plan and plan group associated with this subscription

Subscription Updated

A customer's subscription has been updated by the customer, an admin user or Submarine. Updates include status changes, delivery address updates, schedule edits or changes to product subscriptions.

💡 If you would only like your flow to run for some changes, you can apply a conditional filter to the flow or within Klaviyo. Use the Diff object to check which fields were changed.

Name	Object	Type	Description
Active subscription count	Customer Activity	Integer	A count of active subscriptions for this customer
Lifetime subscription count	Customer Activity	Integer	A count of all subscriptions ever created by this customer
Customer email	Customer (Shopify)	Email	The email address of the customer
Customer information	Customer (Shopify)	Various	The customer data available from Shopify, includes total order count, customer tags, metafields, orders
Custom attributes	Subscription	Array	Metadata key-value pairs attached to the subscription (e.g. delivery day, frequency, postcode)
Diff	Subscription	JSON	Tracks what changed on the subscription: `changes` provides old and new values, `keys` lists changed fields, `topLevelKeys` lists the parent keys
Delivery method	Subscription	Address	The delivery address set for the subscription, including phone number
ID	Subscription	String	The Submarine unique ID used to reference the subscription
Identifier	Subscription	String	The human-readable subscription identifier used in the Submarine UI (e.g. `#1008`)
Line items	Subscription	Array	The products associated with the subscription
Next scheduled order	Subscription	Various	The next scheduled order, including delivery method, billing/delivery dates, financials, lines and status
Source	Subscription	Object	The originating Shopify order that created this subscription
Status	Subscription	String	The status of the subscription (e.g. `active`, `paused`, `cancelled`)
Subscription discounts	Subscription	Array	Any discounts currently applied to the subscription
Subscription group	Subscription	Object	References a relationship between subscriptions created at the same time with different frequencies
Subscription plan	Subscription	Object	The subscription plan and plan group associated with this subscription

Subscription Order Updated

A customer's subscription order has been updated by the customer, an admin user or Submarine. Updates include status changes, delivery address updates, schedule edits or adjustments to products within the order.

💡 If you would only like your flow to run for some changes, you can apply a conditional filter to the flow or within Klaviyo. Use the Diff object on partner::subscription_order to check which fields were changed.

Name	Object	Type	Description
Active subscription count	Customer Activity	Integer	A count of active subscriptions for this customer
Lifetime subscription count	Customer Activity	Integer	A count of all subscriptions ever created by this customer
Customer email	Customer (Shopify)	Email	The email address of the customer
Customer information	Customer (Shopify)	Various	The customer data available from Shopify, includes total order count, customer tags, metafields, orders
Custom attributes	Subscription Order	Array	Metadata key-value pairs attached to this order (e.g. delivery day, frequency, postcode)
Diff	Subscription Order	JSON	Tracks what changed on the order: `changes` provides old and new values, `keys` lists changed fields, `topLevelKeys` lists the parent keys
Delivery method	Subscription Order	Address	The delivery address for this order, including phone number
Expected billing at	Subscription Order	ISO 8601	The expected date/time the order will be billed
Expected delivery at	Subscription Order	ISO 8601	The expected delivery date/time
Failed payment capture count	Subscription Order	Integer	The number of failed payment capture attempts
Financials (detailed set)	Subscription Order	Various	The financial breakdown of the order including subtotal, total price, shipping, discounts and tax
Financials (summary)	Subscription Order	Various	(Deprecated) Simplified subtotal and total price
Flagging	Subscription Order	Various	Flagging status, reason and description (if the order has been flagged)
ID	Subscription Order	String	The Submarine unique ID used to reference the subscription order
Identifier	Subscription Order	String	The human-readable order identifier (e.g. `#1008-002`)
Line items	Subscription Order	Array	The products in this subscription order, including per-line financials and discounts
Payment status	Subscription Order	String	The payment status (e.g. `pending`, `captured`, `failed`)
Retry payment at	Subscription Order	ISO 8601 \| null	The date/time of the next payment retry, if applicable
Status	Subscription Order	String	The status of the order (e.g. `scheduled`, `processing`, `completed`, `failed`)
Subscription discounts	Subscription Order	Array	Any discounts applied to this specific order
Subscription (parent)	Subscription	Various	The parent subscription, including its delivery method, status, ID, line items, plan and next scheduled order

Upcoming Order Notification

A notification fired ahead of a scheduled subscription order to notify the merchant or customer.

The default upcoming order notification is fired 2 days before the billing time. If you would like this changed, please email help@getsubmarine.com

🔔Configuring Multiple Upcoming Order Notifications

Name	Object	Type	Description
Active subscription count	Customer Activity	Integer	A count of active subscriptions for this customer
Lifetime subscription count	Customer Activity	Integer	A count of all subscriptions ever created by this customer
Customer email	Customer (Shopify)	Email	The email address of the customer
Customer information	Customer (Shopify)	Various	The customer data available from Shopify, includes total order count, customer tags, metafields, orders
Custom attributes	Subscription Order	Array	Metadata key-value pairs attached to this order (e.g. delivery day, frequency, postcode)
Delivery method	Subscription Order	Address	The delivery address for this order, including phone number
Expected billing at	Subscription Order	ISO 8601	The expected date/time the order will be billed
Expected delivery at	Subscription Order	ISO 8601	The expected delivery date/time
Financials (detailed set)	Subscription Order	Various	The financial breakdown of the order including subtotal, total price, shipping, discounts and tax
Financials (summary)	Subscription Order	Various	(Deprecated) Simplified subtotal and total price
Flagging	Subscription Order	Various	Flagging status, reason and description (if the order has been flagged)
ID	Subscription Order	String	The Submarine unique ID used to reference the subscription order
Identifier	Subscription Order	String	The human-readable order identifier (e.g. `#1008-002`)
Line items	Subscription Order	Array	The products in this subscription order, including per-line financials and discounts
Payment status	Subscription Order	String	The payment status (e.g. `pending`, `captured`, `failed`)
Status	Subscription Order	String	The status of the order (e.g. `scheduled`, `processing`, `completed`, `failed`)
Subscription discounts	Subscription Order	Array	Any discounts applied to this specific order
Subscription (parent)	Subscription	Various	The parent subscription, including its delivery method, status, ID, line items, plan and next scheduled order

Payment Failed

A payment capture attempt has failed for a subscription order.

🔔 The default retry policy for payment failures is 3 tries over 24 hours. This means there will be the first attempt at billing time, another 24 hours later, and another 24 hours after that.

Name	Object	Type	Description
Active subscription count	Customer Activity	Integer	A count of active subscriptions for this customer
Lifetime subscription count	Customer Activity	Integer	A count of all subscriptions ever created by this customer
Customer email	Customer (Shopify)	Email	The email address of the customer
Customer information	Customer (Shopify)	Various	The customer data available from Shopify, includes total order count, customer tags, metafields, orders
Charge	Charge	Various	The information pertaining to the charge attempt, including charge description, externalId, failureCode, failureMessage, id, recordStatus, source and status
Resource type	Resource	String	The type of resource associated with the charge
Subscription (resource)	Resource	Various	The subscription that relates to the failed charge, including delivery method, status, ID, line items and next scheduled order
Subscription order (resource)	Resource	Various	The subscription order that relates to the failed charge, including delivery method, expected delivery/billing dates, failed capture count, payment status and retry payment timestamp
Subscription plan	Subscription	Object	The subscription plan and plan group associated with this subscription
Subscription plan group	Subscription	Object	The plan group the subscription plan belongs to

Payload Data Reference

Detailed field-level documentation for all objects referenced by the triggers above.

Reusable Types

The following types are referenced throughout the payload. They are documented once here to avoid repetition.

Money

Represents a monetary value.

Field	Type	Example	Description
`amount`	string	`"59.00"`	The monetary amount as a decimal string
`currency`	string	`"AUD"`	The ISO 4217 currency code

MoneySet

Represents a monetary value in both presentment (customer-facing) and shop currencies.

Field	Type	Example	Description
`exchangeRate`	number	`1`	The exchange rate between presentment and shop currencies
`presentment`	Money	—	The amount in the customer-facing currency
`shop`	Money	—	The amount in the shop's base currency

Address

A postal/delivery address.

Field	Type	Example	Description
`city`	string	`"Viewbank"`	The city or suburb name
`country.code`	string	`"AU"`	The ISO 3166-1 alpha-2 country code
`country.name`	string	`"Australia"`	The full country name
`firstName`	string	`"Jane"`	The recipient's first name
`lastName`	string	`"Smith"`	The recipient's last name
`phone`	string \| null	`"+61400000000"`	The recipient's phone number in E.164 format, or `null` if not provided
`postcode`	string	`"3000"`	The postal/ZIP code
`province.code`	string	`"VIC"`	The state or province code
`province.name`	string	`"Victoria"`	The full state or province name
`street1`	string	`"123 Example Street"`	The primary street address
`street2`	string \| null	`null`	The secondary street address (unit, apartment, etc.)

Custom Attribute

A key-value pair used to store additional metadata on a subscription or order.

Field	Type	Example	Description
`ownedBySubmarine`	boolean	`false`	Whether this attribute is managed by Submarine
`customised`	boolean	`false`	Whether this attribute has been customised by the customer
`name`	string	`"_frequency"`	The attribute key (typically prefixed with `_`)
`value`	string	`"4 weeks"`	The attribute value

Discount Value

Describes how a discount is calculated.

Field	Type	Example	Description
`type`	string	`"percentage"`	The type of discount value (e.g. `percentage`, `fixed_amount`)
`percentage`	number \| null	`50`	The percentage discount amount. Present when `type` is `percentage`
`amount`	number \| null	`null`	The fixed discount amount. Present when `type` is `fixed_amount`

Discount Breakdown Entry

An individual discount entry within a financials breakdown.

Field	Type	Example	Description
`class`	string	`"order"`	The class of discount (e.g. `order`, `shipping`)
`discountId`	string	`"019cb108-07a8-..."`	The UUID of the discount that generated this entry
`title`	string	`"ManualDiscount"`	The display title of the discount
`type`	string	`"manual"`	The discount type (e.g. `manual`, `automatic`, `code`)
`value`	Discount Value	—	How the discount is calculated
`price`	MoneySet	—	The monetary amount of the discount applied

Discount Set

Represents discount information applied to a line or order.

Field	Type	Example	Description
`breakdown`	array of Discount Breakdown Entry	—	A list of individual discount entries applied
`total`	MoneySet	—	The total discount amount

Tax Set

Represents tax information applied to a line or order.

Field	Type	Example	Description
`behaviour`	string	`"inclusive"`	Whether tax is `inclusive` or `exclusive` of the displayed price
`breakdown`	array	`[]`	A list of individual tax entries applied
`total`	MoneySet	—	The total tax amount

Subscription Discount

A discount attached to a subscription or scheduled order.

Field	Type	Example	Description
`status`	string	`"active"`	The status of this discount application (e.g. `active`, `inactive`, `invalid`)
`discount.id`	string	`"gid://submarine/Discount/..."`	The Submarine global ID for the discount
`discount.externalId`	string \| null	`"1085039083565"`	The external (e.g. Shopify) ID for the discount, if applicable
`discount.status`	string	`"active"`	The status of the discount itself (e.g. `active`, `expired`)
`discount.class`	string	`"order"`	The class of discount (e.g. `order`, `shipping`)
`discount.type`	string	`"manual"`	The discount type (e.g. `manual`, `automatic`, `code`)
`discount.title`	string	`"ManualDiscount"`	The display title of the discount
`discount.value`	Discount Value	—	How the discount is calculated

Diff

Tracks changes made to a subscription or order in the current event. When no changes have been made, all arrays will be empty.

Field	Type	Example	Description
`diff.keys`	array of string	`["status"]`	List of changed field keys
`diff.changes`	array of array	`[["~", "status", "active", "paused"]]`	List of change tuples. Each entry is an array of: operator (`~` for modified), field name, old value, new value
`diff.topLevelKeys`	array of string	`["status"]`	List of top-level fields that were changed

Top Level Fields

Field	Type	Example	Description
`partner::customer_activity`	object	—	Summary of the customer's subscription activity
`shopify::customer_id`	string	`"gid://shopify/Customer/1234567890"`	The Shopify global ID for the customer
`partner::subscription`	object	—	The full subscription object
`partner::subscription_order`	object \| absent	—	The subscription order object (order triggers only)

Customer Activity

Field	Type	Example	Description
`activeSubscriptionsCount`	integer	`3`	The number of currently active subscriptions for this customer
`lifetimeSubscriptionsCount`	integer	`8`	The total number of subscriptions this customer has ever had

Subscription

Core Fields

Field	Type	Example	Description
`id`	string	`"gid://submarine/Subscription/..."`	The Submarine global ID for the subscription
`identifier`	string	`"#1118"`	The human-readable subscription identifier
`modelId`	string	`"019cacbf-35bd-..."`	The UUID of the subscription model
`status`	string	`"active"`	The current status of the subscription (e.g. `active`, `paused`, `cancelled`)
`customAttributes`	array of Custom Attribute	—	Metadata key-value pairs attached to the subscription
`subscriptionDiscounts`	array of Subscription Discount	—	Any discounts currently applied to the subscription

Delivery Method

Field	Type	Example	Description
`deliveryMethod`	object \| null	—	The delivery method object. May be `null` in order-level triggers
`deliveryMethod.address`	Address	—	The delivery address for the subscription (when `deliveryMethod` is not `null`)

Diff

Present on the subscription object in subscription-level triggers. See Diff for field details.

Lines

Each entry in the lines array represents a product included in the subscription.

Field	Type	Example	Description
`lines[].id`	string	`"gid://submarine/SubscriptionLine/..."`	The Submarine global ID for the subscription line
`lines[].quantity`	integer	`1`	The quantity of this product per delivery
`lines[].basePrice`	Money	—	The base unit price of the line item
`lines[].basePriceSet`	MoneySet	—	The base unit price in both presentment and shop currencies
`lines[].product.externalId`	string	`"8051842875437"`	The Shopify product ID
`lines[].product.id`	string	`"gid://submarine/Product/..."`	The Submarine global ID for the product
`lines[].product.imageUrl`	string	`"https://cdn.shopify.com/..."`	URL of the product image
`lines[].product.title`	string	`"Butcher's Choice"`	The product title
`lines[].productVariant.externalId`	string	`"44347758542893"`	The Shopify variant ID
`lines[].productVariant.id`	string	`"gid://submarine/ProductVariant/..."`	The Submarine global ID for the variant
`lines[].productVariant.imageUrl`	string	`"https://cdn.shopify.com/..."`	URL of the variant image
`lines[].productVariant.price`	Money	—	The variant's listed price
`lines[].productVariant.sku`	string	`"BOX-SML-FV"`	The variant SKU
`lines[].productVariant.title`	string	`"Box - Small / Fruit & Vegetables / Imperfect"`	The variant title

Source

The originating order that created this subscription.

Field	Type	Example	Description
`source.externalId`	string	`"6149105057837"`	The Shopify order ID
`source.id`	string	`"gid://submarine/Order/..."`	The Submarine global ID for the originating order
`source.type`	string	`"order"`	The source type (e.g. `order`)

Subscription Group

Field	Type	Example	Description
`subscriptionGroup.id`	string	`"gid://submarine/SubscriptionGroup/..."`	The Submarine global ID for the subscription group
`subscriptionGroup.identifier`	string	`"#3032"`	The human-readable subscription group identifier

Subscription Plan

Field	Type	Example	Description
`subscriptionPlan.id`	string	`"gid://submarine/SubscriptionPlan/..."`	The Submarine global ID for the subscription plan
`subscriptionPlan.name`	string	`"Delivered every other Friday"`	The display name of the subscription plan
`subscriptionPlan.subscriptionPlanGroup.id`	string	`"gid://submarine/SubscriptionPlanGroup/..."`	The Submarine global ID for the plan group
`subscriptionPlan.subscriptionPlanGroup.identifier`	string	`"#1000"`	The human-readable plan group identifier
`subscriptionPlan.subscriptionPlanGroup.name`	string	`"Farmers Pick Box"`	The display name of the plan group

Subscription Order

This object describes a subscription order. It appears in different places depending on the trigger type:

Core Fields

Field	Type	Example	Description
`id`	string	`"gid://submarine/SubscriptionOrder/..."`	The Submarine global ID for the subscription order
`identifier`	string	`"#1118-002"`	The human-readable order identifier (subscription identifier + sequence)
`status`	string	`"scheduled"`	The order status (e.g. `scheduled`, `processing`, `completed`, `failed`)
`paymentStatus`	string	`"pending"`	The payment status (e.g. `pending`, `captured`, `failed`)
`expectedBillingAt`	string (ISO 8601)	`"2026-03-31T12:15:00Z"`	The expected date/time the order will be billed
`expectedDeliveryAt`	string (ISO 8601)	`"2026-04-04T12:15:00Z"`	The expected delivery date/time
`failedPaymentCaptureCount`	integer	`0`	The number of failed payment capture attempts
`retryPaymentAt`	string (ISO 8601) \| null	`null`	The date/time of the next payment retry, if applicable
`customAttributes`	array of Custom Attribute	—	Metadata key-value pairs attached to this order
`subscriptionDiscounts`	array of Subscription Discount	—	Any discounts applied to this specific order

Diff (Order Trigger Only)

Present only on partner::subscription_order in order-level triggers. See Diff for field details.

Flagging

Field	Type	Example	Description
`flaggedAt`	string (ISO 8601) \| null	`null`	The date/time the order was flagged, if applicable
`flaggedDescription`	string \| null	`null`	A description of why the order was flagged
`flaggedReason`	string \| null	`null`	The reason code for flagging

Delivery

Field	Type	Example	Description
`deliveryMethod`	object \| null	—	The delivery method object. May be `null`
`deliveryMethod.address`	Address	—	The delivery address for this specific order (when `deliveryMethod` is not `null`)

Financials Summary (Deprecated)

Field	Type	Example	Description
`financials.subtotal`	Money	—	(Deprecated) The subtotal before shipping and discounts
`financials.totalPrice`	Money	—	(Deprecated) The total price including shipping

Financials (Detailed Set)

Field	Type	Example	Description
`financialsSet.presentmentCurrency`	string	`"AUD"`	The customer-facing currency code
`financialsSet.shopCurrency`	string	`"AUD"`	The shop's base currency code
`financialsSet.subtotal`	MoneySet	—	The order subtotal in both currencies
`financialsSet.totalPrice`	MoneySet	—	The total order price in both currencies
`financialsSet.discounts`	Discount Set	—	Discount information for the order
`financialsSet.tax`	Tax Set	—	Tax information for the order
`financialsSet.shipping.total`	MoneySet	—	The total shipping cost
`financialsSet.shipping.breakdown[]`	array	—	Individual shipping rate entries

Shipping Breakdown Entry

Each entry in financialsSet.shipping.breakdown[]:

Field	Type	Example	Description
`code`	string	`"Subscription"`	The shipping rate code
`title`	string	`"Farmers Pick Delivery"`	The display name of the shipping method
`source`	string	`"shopify"`	The source of the shipping rate (e.g. `shopify`)
`price`	MoneySet	—	The shipping price in both currencies

Order Lines

Each entry represents a product line in the subscription order.

Field	Type	Example	Description
`lines[].id`	string	`"gid://submarine/SubscriptionOrderLine/..."`	The Submarine global ID for the order line
`lines[].lineType`	string	`"recurring"`	The type of line (e.g. `recurring`, `one_time`)
`lines[].quantity`	integer	`1`	The quantity of this product in the order
`lines[].basePriceSet`	MoneySet	—	The base unit price in both currencies
`lines[].product.externalId`	string	`"8051842875437"`	The Shopify product ID
`lines[].product.id`	string	`"gid://submarine/Product/..."`	The Submarine global ID for the product
`lines[].product.imageUrl`	string	`"https://cdn.shopify.com/..."`	URL of the product image
`lines[].product.title`	string	`"Butcher's Choice"`	The product title
`lines[].productVariant.externalId`	string	`"44347758542893"`	The Shopify variant ID
`lines[].productVariant.id`	string	`"gid://submarine/ProductVariant/..."`	The Submarine global ID for the variant
`lines[].productVariant.imageUrl`	string	`"https://cdn.shopify.com/..."`	URL of the variant image
`lines[].productVariant.price`	Money	—	The variant's listed price
`lines[].productVariant.sku`	string	`"BOX-SML-FV"`	The variant SKU
`lines[].productVariant.title`	string	`"Box - Small / Fruit & Vegetables / Imperfect"`	The variant title

Order Line Financials Summary (Deprecated)

Field	Type	Example	Description
`lines[].financials.linePriceBeforeDiscounts`	Money	—	(Deprecated) The total line price before any discounts
`lines[].financials.linePriceAfterDiscounts`	Money	—	(Deprecated) The total line price after discounts
`lines[].financials.unitPriceBeforeDiscounts`	Money	—	(Deprecated) The per-unit price before discounts
`lines[].financials.unitPriceAfterDiscounts`	Money	—	(Deprecated) The per-unit price after discounts
`lines[].financials.tax`	Tax Set	—	(Deprecated) Tax information for this line (uses Money for `total`, not MoneySet)

Order Line Financials (Detailed Set)

Field	Type	Example	Description
`lines[].financialsSet.presentmentCurrency`	string	`"AUD"`	The customer-facing currency code
`lines[].financialsSet.shopCurrency`	string	`"AUD"`	The shop's base currency code
`lines[].financialsSet.linePriceBeforeDiscounts`	MoneySet	—	The total line price before discounts in both currencies
`lines[].financialsSet.linePriceAfterDiscounts`	MoneySet	—	The total line price after discounts in both currencies
`lines[].financialsSet.unitPriceBeforeDiscounts`	MoneySet	—	The per-unit price before discounts in both currencies
`lines[].financialsSet.unitPriceAfterDiscounts`	MoneySet	—	The per-unit price after discounts in both currencies
`lines[].financialsSet.discounts`	Discount Set	—	Discount information for this line
`lines[].financialsSet.tax`	Tax Set	—	Tax information for this line
`lines[].financialsSet.shipping`	null	`null`	Shipping is not applicable at the line level

Flow Actions

Submarine currently does not expose any Shopify Flow actions.

Something you'd like added? Reach out!