> ## Documentation Index
> Fetch the complete documentation index at: https://app.docs.circuly.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Trigger reference

> All 15 Shopify Flow triggers Circuly emits, grouped by domain, with payload fields.

## 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.

<Note>
  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.
</Note>

## 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`

<Warning>
  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.
</Warning>

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              |             |