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

# Automation Triggers

> Configure event and schedule-based triggers for your automations

# Automation Triggers

Triggers define when an automation runs. Alguna supports event-based triggers that respond to billing events and schedule-based triggers for time-based workflows.

***

## Configuring Triggers

### Create an Automation with Triggers

1. Navigate to **Automations** in the dashboard
2. Click **Create Automation**
3. In the **Trigger** section, choose:
   * **Event-based**: Run when a billing event occurs
   * **Schedule-based**: Run at specific times
4. Configure trigger settings
5. Add actions and conditions
6. Click **Save**

***

## Event Triggers

Event triggers fire when specific actions occur in your billing system.

### Available Events

#### Subscription Events

| Event                                | Description                            |
| ------------------------------------ | -------------------------------------- |
| `subscription.activated`             | Subscription became active             |
| `subscription.started`               | Subscription started                   |
| `subscription.cancelation_scheduled` | Cancellation scheduled for future date |
| `subscription.canceled`              | Subscription canceled                  |

#### Invoice Events

| Event            | Description                |
| ---------------- | -------------------------- |
| `invoice.issued` | Invoice issued to customer |
| `invoice.paid`   | Invoice fully paid         |

#### Payment Events

| Event             | Description            |
| ----------------- | ---------------------- |
| `payment.created` | Payment initiated      |
| `payment.updated` | Payment status changed |

#### Other Events

| Event                              | Description                          |
| ---------------------------------- | ------------------------------------ |
| `checkout.session.completed`       | Checkout completed successfully      |
| `refund.updated`                   | Refund status changed                |
| `account.credits.granted`          | Credits manually granted to customer |
| `account.credits.balance_depleted` | Credit balance reached zero          |
| `line_item.deleted`                | Invoice line item deleted            |

### Configuring Event Triggers

1. Select **Event-based trigger**
2. Choose the event type from the dropdown
3. Optionally add filters to narrow which events trigger the automation

### Filters

Filter which events trigger the automation:

| Filter           | Description                 | Example              |
| ---------------- | --------------------------- | -------------------- |
| Invoice amount   | Filter by invoice total     | Greater than \$1,000 |
| Customer segment | Filter by customer segment  | Enterprise customers |
| Plan             | Filter by subscription plan | Pro plan only        |

***

## Schedule Triggers

Schedule triggers run automations at specified times.

### Interval-Based

Run at regular intervals:

| Interval        | Description           |
| --------------- | --------------------- |
| Every 5 minutes | High-frequency checks |
| Every hour      | Regular monitoring    |
| Every day       | Daily reports         |
| Every week      | Weekly summaries      |

### Cron-Based

Use cron expressions for precise scheduling:

| Expression    | Description                |
| ------------- | -------------------------- |
| `0 9 * * *`   | Daily at 9 AM              |
| `0 9 * * 1`   | Mondays at 9 AM            |
| `0 0 1 * *`   | First of month at midnight |
| `0 */6 * * *` | Every 6 hours              |
| `0 9 * * 1-5` | Weekdays at 9 AM           |

**Cron format:** `minute hour day-of-month month day-of-week`

### Calendar-Based

Human-readable calendar triggers:

| Option         | Description                 |
| -------------- | --------------------------- |
| First of month | First day of each month     |
| Last of month  | Last day of each month      |
| Specific day   | A specific day (e.g., 15th) |
| Weekday        | Monday, Tuesday, etc.       |

***

## Trigger Context

Each trigger provides context data accessible in automation steps:

### Event Trigger Context

When an event triggers the automation, you can access:

* Event type and timestamp
* Related object data (invoice, subscription, payment, etc.)
* Customer information
* Associated metadata

### Schedule Trigger Context

For scheduled triggers:

* Scheduled run time
* Actual run time
* Run number (for tracking)

***

## Common Trigger Patterns

### Send Reminder on Invoice Issued

1. **Trigger**: `invoice.issued`
2. **Action**: Send email to customer with invoice details

### Update CRM on Subscription Activated

1. **Trigger**: `subscription.activated`
2. **Action**: Send webhook to CRM with subscription details

### Weekly Revenue Report

1. **Trigger**: Schedule - Every Monday at 9 AM
2. **Action**: Send report email to finance team

### Notify Sales on Large Payment

1. **Trigger**: `payment.created`
2. **Filter**: Amount > \$10,000
3. **Action**: Send Slack notification to sales channel

***

## Best Practices

<CardGroup cols={2}>
  <Card title="Use Filters" icon="filter">
    Filter events to avoid unnecessary executions.
  </Card>

  <Card title="Test First" icon="vial">
    Test automations in sandbox before activating in production.
  </Card>

  <Card title="Consider Timing" icon="clock">
    Schedule triggers at appropriate times for your audience.
  </Card>

  <Card title="Monitor Executions" icon="chart-line">
    Review automation logs to ensure triggers fire as expected.
  </Card>
</CardGroup>

***

## Viewing Trigger History

1. Navigate to **Automations → \[Automation Name]**
2. Click the **History** tab
3. View recent executions:
   * Trigger event/schedule
   * Execution status
   * Timestamp
   * Actions performed

***

## Troubleshooting

### Trigger Not Firing

1. Verify the automation is **Active**
2. Check that the event type matches exactly
3. Review filters - they may be too restrictive
4. Confirm the event is actually occurring in your account

### Automation Runs Too Often

1. Add filters to narrow the trigger conditions
2. Consider using debouncing for rapid-fire events
3. Review if multiple automations overlap

### Schedule Not Running

1. Verify the cron expression is correct
2. Check timezone settings
3. Confirm the automation is active

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Actions" icon="play" href="/automations/actions">
    Learn about automation actions.
  </Card>

  <Card title="Conditions" icon="code-branch" href="/automations/conditions">
    Add conditional logic.
  </Card>
</CardGroup>