# Custom triggers

Source: https://gokarla.io/docs/guides/notify/custom-triggers

# Custom triggers

Custom triggers watch your shipments over time and raise a hand when
something takes too long — an order created but not fulfilled for six days, a
parcel sitting in transit for a week. When a shipment has been stuck in a
state you chose for longer than your threshold, the trigger fires an event
into Klaviyo, where you build the follow-up flow.

In the [Karla Portal](https://portal.gokarla.io), go to
**Notify → Custom triggers**.

:::important Custom triggers are not email flows
[Email flows](/docs/guides/notify/email-flows) are the content of emails
Karla itself sends. **Custom triggers** don't send any email — each one
delivers a metric into Klaviyo when its time condition is met, and your
Klaviyo flow decides what happens next. Custom triggers are currently only
available for Klaviyo; native Notify support is coming soon.
:::

## Prerequisites

- A connected [Klaviyo integration](/docs/guides/notify/integrations/klaviyo).
  Without one, the page shows a **Connect Klaviyo first** prompt that links
  you to the integration settings.
- The **editor** role (or above) in the portal to create or delete triggers.

## How a trigger works

- A trigger watches shipments in the events or phases you select. Karla
  periodically evaluates your triggers against your recent shipments.
- When a shipment has been stuck longer than the time threshold, Karla sends
  an event to Klaviyo under the metric
  `karla_<trigger_name>_internal_trigger`.
- Threshold hours **skip Sundays and German public holidays** — a 144-hour
  threshold reaches further back than six calendar days when a Sunday or
  holiday falls in between.
- Only shipments **created in the last 30 days** are checked.
- A trigger fires **at most once per order** — once it has fired, it stays
  quiet for that order's shipments.

## Create a trigger

Click **Create new trigger**. The form reminds you that custom triggers
currently work with Klaviyo-powered stores, then asks for:

### Trigger name

Names both the trigger and its Klaviyo metric. The recommended format is
`order_status_condition_timeframe`, for example
`order_created_not_fulfilled_6_days`. Spaces and special characters convert
to underscores automatically, and the final name is lowercase. That example
produces the Klaviyo metric
`karla_order_created_not_fulfilled_6_days_internal_trigger`.

### Events

Pick individual events, or select a whole phase — phases automatically
include new carrier events added to them later. The picker groups events
under the shipment phases: Order created, Order processed, Order cancelled,
Collect, In transit, In delivery, Delivered, Delivery failed, Return created,
Return transit, Return received, Return failed, and Returned. See the
[shipment events reference](/docs/platform/events/shipments) for what each
phase covers.

### Time threshold type

When should the timer start?

| Option                            | The timer counts from               |
| --------------------------------- | ----------------------------------- |
| **After latest update** (default) | The shipment's most recent event    |
| **From creation**                 | The moment the shipment was created |

### Set time threshold (hours)

How long the shipment must be stuck before the trigger fires. Whole hours
only, from 1 to 600 (25 days); the default is 144 (6 days). For thresholds
of 480 hours or more the portal shows a heads-up: since only the last 30
days of shipments are checked, very high thresholds leave little room to
match.

As you fill in the form, a live preview spells out exactly what will fire —
for example: "Shipments stuck in any In transit state since before Tue, Aug 4
at 09:00 will fire this trigger — that's 144 hours back, skipping Sundays and
German public holidays."

Click **Create Trigger** to save. The trigger is live immediately.

## Find the metric in Klaviyo

As soon as you create a trigger, Karla seeds its metric with a single test
event so it shows up in Klaviyo right away — Klaviyo only offers a metric to
flow builders after receiving at least one event of it, so you don't have to
wait for a real shipment to match.

In Klaviyo, create a flow triggered by the metric
`karla_<trigger_name>_internal_trigger` and build your follow-up — an apology
email, a support ticket, an internal alert. See
[Building Klaviyo flows](/docs/guides/notify/integrations/klaviyo#building-klaviyo-flows)
for the general pattern.

## Manage your triggers

The **Your triggers** list shows every trigger, with a search box to filter:

| Column           | What it shows                                                                                                                        |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **Trigger name** | The slugified name, as it appears in the Klaviyo metric                                                                              |
| **Watching**     | The selected events or phases ("3 events", "2 phases", "Any event"), any excluded events, and a **Return** chip for return shipments |
| **Threshold**    | The time threshold (e.g. "6 days") and its type                                                                                      |

Click a trigger to open its details:

- The conditions — event type, events or phases, exceptions, and threshold
  type — are read-only.
- Only **Set time threshold (hours)** can be edited and saved.
- To change anything else, open **More actions → Duplicate trigger**, which
  prefills the create form with the trigger's conditions — adjust them, save
  the new trigger, then delete the old one.
- **Delete** removes the trigger permanently; this cannot be undone. There is
  no enable/disable switch — a trigger fires as long as it exists.