Trigger reference

Reference

Every trigger ships an event payload merchants can use as conditions or template variables in Shopify Flow. Reference fields (customer_reference, order_reference, product_reference) resolve to full Shopify resources inside Flow — you can branch on {{customer.amountSpent}}, {{order.totalPrice}}, etc.

Trigger handles are stable — once a workflow uses a handle, renaming it would break the workflow. Circuly will only add new handles, never modify existing ones.

Invoice triggers

`invoice-created`

Fires when Circuly creates a new invoice for a subscription billing cycle.

Field	Type	Description
Customer	`customer_reference`	The customer the invoice belongs to.
Invoice number	string	Circuly’s human-readable invoice number.
Total amount	decimal	Total invoice amount in shop currency.
Currency	string	ISO currency code (EUR, USD, etc.).
Contract handle	string	Identifier of the subscription contract.

`invoice-paid`

Fires when an invoice is marked as paid following a successful billing attempt.

Field	Type	Description
Customer	`customer_reference`	The customer who paid.
Order	`order_reference`	The Shopify order created from the renewal.
Invoice number	string
Total amount	decimal
Currency	string	ISO currency code.
Contract handle	string

`invoice-dunning`

Fires when an invoice enters dunning — overdue with a retry scheduled — after a failed billing attempt.

Field	Type	Description
Customer	`customer_reference`
Invoice number	string
Total amount	decimal
Attempt count	integer	Number of failed billing attempts so far.
Contract handle	string

Subscription triggers

`subscription-created`

Fires when a new subscription or rental contract is created.

Field	Type	Description
Customer	`customer_reference`
Order	`order_reference`	The origin order.
Contract handle	string
Contract type	string	Subscription, Rental, Digital, or Consumable.

`subscription-updated`

Fires when a subscription contract is changed — frequency, quantity, address, or next billing date. Use the Changed fields property to filter.

Field	Type	Description
Customer	`customer_reference`
Contract handle	string
Changed fields	string	Comma-separated list of changed fields.

`subscription-paused`

Fires when a subscription contract is paused.

Field	Type	Description
Customer	`customer_reference`
Contract handle	string
Reason	string	Empty if no reason given.

`subscription-cancelled`

Fires when a contract is cancelled (early termination).

Field	Type	Description
Customer	`customer_reference`
Contract handle	string
Termination fee	decimal	Zero if none.
Cancelled by	string	`merchant` or `customer`.

`subscription-ended`

Declared but not yet emitted — the fixed-term completion path will be wired in a follow-up. Configuring a workflow on this handle today won’t trigger anything.

Will fire when a fixed-term contract reaches its natural end. Use this for renewal-offer workflows — distinct from subscription-cancelled.

Field	Type	Description
Customer	`customer_reference`
Contract handle	string

`subscription-swapped`

Fires when a product or variant is swapped on a subscription contract.

Field	Type	Description
Customer	`customer_reference`
Product	`product_reference`	The new product.
Contract handle	string
Old variant id	string
New variant id	string

`subscription-bought-out`

Fires when a customer buys out a rental subscription.

Field	Type	Description
Customer	`customer_reference`
Contract handle	string
Buyout price	decimal
Cycles completed	integer	Billing cycles completed before buyout.

Asset triggers

Asset is a Circuly-specific concept — a rental inventory unit. Asset id is a string (Shopify Flow has no native asset reference type).

`asset-created`

Fires when a new asset record is created.

Field	Type	Description
Product	`product_reference`
Asset id	string	Circuly identifier.
Serial number	string

`asset-updated`

Fires when an asset record is updated — condition, location, status, etc.

Field	Type	Description
Asset id	string
Changed fields	string	Comma-separated list.

`asset-assigned`

Fires when an asset is assigned to a contract.

Field	Type	Description
Customer	`customer_reference`
Asset id	string
Contract handle	string

`asset-returned`

Fires when an asset is returned by the customer.

Field	Type	Description
Customer	`customer_reference`
Asset id	string
Contract handle	string
Condition	string	Empty if not captured.

`asset-bought-out`

Fires when a customer buys out a specific asset.

Field	Type	Description
Customer	`customer_reference`
Asset id	string
Contract handle	string
Buyout price	decimal

Getting Started

Rental Engine

Extensions

Integrations

Migration

Resources

Reference

Invoice triggers

`invoice-created`

`invoice-paid`

`invoice-dunning`

Subscription triggers

`subscription-created`

`subscription-updated`

`subscription-paused`

`subscription-cancelled`

`subscription-ended`

`subscription-swapped`

`subscription-bought-out`

Asset triggers

`asset-created`

`asset-updated`

`asset-assigned`

`asset-returned`

`asset-bought-out`

​Reference

​Invoice triggers

​invoice-created

​invoice-paid

​invoice-dunning

​Subscription triggers

​subscription-created

​subscription-updated

​subscription-paused

​subscription-cancelled

​subscription-ended

​subscription-swapped

​subscription-bought-out

​Asset triggers

​asset-created

​asset-updated

​asset-assigned

​asset-returned

​asset-bought-out

Reference

Invoice triggers

`invoice-created`

`invoice-paid`

`invoice-dunning`

Subscription triggers

`subscription-created`

`subscription-updated`

`subscription-paused`

`subscription-cancelled`

`subscription-ended`

`subscription-swapped`

`subscription-bought-out`

Asset triggers

`asset-created`

`asset-updated`

`asset-assigned`

`asset-returned`

`asset-bought-out`