Automation Reference

Complete reference guide for building automations in Alguna. This page documents all available triggers, actions, step types, template syntax, and condition expressions.

Trigger Types

Triggers define when an automation runs. Each trigger provides specific data that can be used in subsequent steps.

Payment Failed

Fires when a payment attempt fails.

Property	Type	Description
`trigger_type`	`PaymentFailed`	Trigger identifier
`invoice_id`	string	The invoice that failed to collect
`payment_method_id`	string	Payment method used
`failure_code`	string	Reason for failure
`failure_message`	string	Human-readable failure message
`attempt_number`	integer	Which retry attempt (1, 2, 3…)

Example trigger data:

{
  "trigger_type": "PaymentFailed",
  "invoice_id": "inv_abc123",
  "account_id": "acc_xyz789",
  "payment_method_id": "pm_card_visa",
  "failure_code": "card_declined",
  "failure_message": "Your card was declined",
  "attempt_number": 1,
  "amount": "99.00",
  "currency": "USD"
}

Invoice Status Updated

Fires when an invoice status changes.

Property	Type	Description
`trigger_type`	`InvoiceStatusUpdated`	Trigger identifier
`invoice_id`	string	The invoice
`previous_status`	string	Status before change
`new_status`	string	Current status
`status_changed_at`	timestamp	When the change occurred

Status values: draft, issued, paid, void, past_due, uncollectible Example trigger data:

{
  "trigger_type": "InvoiceStatusUpdated",
  "invoice_id": "inv_abc123",
  "account_id": "acc_xyz789",
  "previous_status": "issued",
  "new_status": "paid",
  "status_changed_at": "2024-01-20T10:30:00Z"
}

Prepaid Usage Update

Fires when prepaid credit usage changes significantly.

Property	Type	Description
`trigger_type`	`PrepaidUsageUpdate`	Trigger identifier
`wallet_id`	string	The wallet affected
`previous_balance`	decimal	Balance before update
`current_balance`	decimal	Current balance
`usage_amount`	decimal	Amount consumed
`threshold_crossed`	boolean	If a threshold was crossed

Example trigger data:

{
  "trigger_type": "PrepaidUsageUpdate",
  "wallet_id": "wal_abc123",
  "account_id": "acc_xyz789",
  "previous_balance": "1000.00",
  "current_balance": "150.00",
  "usage_amount": "850.00",
  "threshold_crossed": true,
  "threshold_percentage": 85
}

Subscription Sent for Signature

Fires when a subscription requires signature.

Property	Type	Description
`trigger_type`	`SubscriptionSentForSignature`	Trigger identifier
`subscription_id`	string	The subscription
`version_id`	string	Version requiring signature
`sent_to`	string	Email address
`sent_at`	timestamp	When sent

Example trigger data:

{
  "trigger_type": "SubscriptionSentForSignature",
  "subscription_id": "sub_abc123",
  "version_id": "ver_xyz789",
  "account_id": "acc_def456",
  "sent_to": "[email protected]",
  "sent_at": "2024-01-20T10:30:00Z",
  "expires_at": "2024-01-27T10:30:00Z"
}

Credits Depleted

Fires when credit balance reaches zero or a threshold.

Property	Type	Description
`trigger_type`	`CreditsDepleted`	Trigger identifier
`wallet_id`	string	The wallet
`depleted_at`	timestamp	When depleted
`last_grant_id`	string	Most recent credit grant

Example trigger data:

{
  "trigger_type": "CreditsDepleted",
  "wallet_id": "wal_abc123",
  "account_id": "acc_xyz789",
  "depleted_at": "2024-01-20T10:30:00Z",
  "final_balance": "0.00",
  "last_grant_id": "grant_def456"
}

Subscription Status Updated

Fires when a subscription status changes.

Property	Type	Description
`trigger_type`	`SubscriptionStatusUpdated`	Trigger identifier
`subscription_id`	string	The subscription
`previous_status`	string	Status before change
`new_status`	string	Current status

Status values: draft, pending, active, paused, canceled, expired Example trigger data:

{
  "trigger_type": "SubscriptionStatusUpdated",
  "subscription_id": "sub_abc123",
  "account_id": "acc_xyz789",
  "previous_status": "active",
  "new_status": "canceled",
  "status_changed_at": "2024-01-20T10:30:00Z",
  "cancellation_reason": "customer_requested"
}

Action Types

Actions are the operations performed by your automation.

Communication Actions

send_email

Send an email using a template.

Parameter	Type	Required	Description
`template_id`	string	Yes	Email template to use
`to`	string	Yes	Recipient email (supports templates)
`cc`	string[]	No	CC recipients
`bcc`	string[]	No	BCC recipients
`variables`	object	No	Template variables

{
  "action": "send_email",
  "parameters": {
    "template_id": "tmpl_payment_failed",
    "to": "{{trigger.account.email}}",
    "variables": {
      "invoice_number": "{{trigger.invoice_id}}",
      "amount_due": "{{trigger.amount}}"
    }
  }
}

send_invoice_reminder

Send a payment reminder for an invoice.

Parameter	Type	Required	Description
`invoice_id`	string	Yes	Invoice to remind about
`reminder_type`	string	No	`gentle`, `firm`, `final`

{
  "action": "send_invoice_reminder",
  "parameters": {
    "invoice_id": "{{trigger.invoice_id}}",
    "reminder_type": "gentle"
  }
}

send_invoice_reminders_bulk

Send reminders for multiple invoices.

Parameter	Type	Required	Description
`invoice_ids`	string[]	Yes	Invoices to remind about
`reminder_type`	string	No	Reminder severity level

{
  "action": "send_invoice_reminders_bulk",
  "parameters": {
    "invoice_ids": "{{step_get_invoices.outputs.invoice_ids}}",
    "reminder_type": "firm"
  }
}

send_billing_info_request

Request updated billing information from customer.

Parameter	Type	Required	Description
`account_id`	string	Yes	Customer account
`reason`	string	No	Why info is needed

{
  "action": "send_billing_info_request",
  "parameters": {
    "account_id": "{{trigger.account_id}}",
    "reason": "Payment method expired"
  }
}

share_customer_portal_link

Send customer portal access link.

Parameter	Type	Required	Description
`account_id`	string	Yes	Customer account
`expires_in`	string	No	Link expiration (e.g., `7d`)

{
  "action": "share_customer_portal_link",
  "parameters": {
    "account_id": "{{trigger.account_id}}",
    "expires_in": "7d"
  }
}

send_subscription_signature_reminder

Remind customer to sign a pending subscription.

Parameter	Type	Required	Description
`subscription_id`	string	Yes	Subscription awaiting signature
`version_id`	string	No	Specific version

{
  "action": "send_subscription_signature_reminder",
  "parameters": {
    "subscription_id": "{{trigger.subscription_id}}",
    "version_id": "{{trigger.version_id}}"
  }
}

send_subscriptions_autorenewal_notification_bulk

Notify customers about upcoming auto-renewals.

Parameter	Type	Required	Description
`subscription_ids`	string[]	Yes	Subscriptions renewing
`days_before`	integer	No	Days before renewal

{
  "action": "send_subscriptions_autorenewal_notification_bulk",
  "parameters": {
    "subscription_ids": "{{step_get_subs.outputs.ids}}",
    "days_before": 30
  }
}

Data Retrieval Actions

get_invoice

Retrieve a single invoice.

Parameter	Type	Required	Description
`invoice_id`	string	Yes	Invoice to retrieve

Outputs: Full invoice object including line items, status, amounts.

{
  "action": "get_invoice",
  "parameters": {
    "invoice_id": "{{trigger.invoice_id}}"
  }
}

get_invoices

Retrieve multiple invoices with filters.

Parameter	Type	Required	Description
`account_id`	string	No	Filter by account
`status`	string[]	No	Filter by status
`due_before`	string	No	Filter by due date
`limit`	integer	No	Max results

Outputs: Array of invoice objects.

{
  "action": "get_invoices",
  "parameters": {
    "account_id": "{{trigger.account_id}}",
    "status": ["issued", "past_due"],
    "limit": 10
  }
}

get_subscription

Retrieve a single subscription.

Parameter	Type	Required	Description
`subscription_id`	string	Yes	Subscription to retrieve

Outputs: Full subscription object with current version.

{
  "action": "get_subscription",
  "parameters": {
    "subscription_id": "{{trigger.subscription_id}}"
  }
}

get_subscriptions

Retrieve multiple subscriptions with filters.

Parameter	Type	Required	Description
`account_id`	string	No	Filter by account
`status`	string[]	No	Filter by status
`renews_before`	string	No	Filter by renewal date

Outputs: Array of subscription objects.

{
  "action": "get_subscriptions",
  "parameters": {
    "status": ["active"],
    "renews_before": "{{now | date_add: '30d'}}"
  }
}

Billing Actions

retry_invoice_payment

Retry payment collection for an invoice.

Parameter	Type	Required	Description
`invoice_id`	string	Yes	Invoice to retry
`payment_method_id`	string	No	Specific payment method

{
  "action": "retry_invoice_payment",
  "parameters": {
    "invoice_id": "{{trigger.invoice_id}}"
  }
}

cancel_subscription

Cancel a subscription.

Parameter	Type	Required	Description
`subscription_id`	string	Yes	Subscription to cancel
`cancel_at`	string	No	`immediate` or `end_of_period`
`reason`	string	No	Cancellation reason

{
  "action": "cancel_subscription",
  "parameters": {
    "subscription_id": "{{trigger.subscription_id}}",
    "cancel_at": "end_of_period",
    "reason": "Non-payment after multiple attempts"
  }
}

Integration Actions

send_webhook

Send data to an external webhook.

Parameter	Type	Required	Description
`url`	string	Yes	Webhook endpoint
`method`	string	No	HTTP method (default: POST)
`headers`	object	No	Custom headers
`body`	object	Yes	Request payload

{
  "action": "send_webhook",
  "parameters": {
    "url": "https://api.yourapp.com/billing-events",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer {{secrets.WEBHOOK_TOKEN}}"
    },
    "body": {
      "event": "payment_failed",
      "account_id": "{{trigger.account_id}}",
      "invoice_id": "{{trigger.invoice_id}}"
    }
  }
}

Step Types

Automations are composed of steps that execute in sequence.

Action Step

Execute a single action.

{
  "id": "send_reminder",
  "type": "Action",
  "action": "send_email",
  "parameters": {...}
}

Condition Step

Branch based on a condition.

{
  "id": "check_attempts",
  "type": "Condition",
  "condition": "trigger.attempt_number > 2",
  "then": [...],
  "else": [...]
}

Delay Step

Wait before continuing.

{
  "id": "wait_24h",
  "type": "Delay",
  "duration": "24h"
}

Duration formats: 30m (minutes), 24h (hours), 7d (days)

ForEach Step

Iterate over a collection.

{
  "id": "process_invoices",
  "type": "ForEach",
  "collection": "{{step_get_invoices.outputs.invoices}}",
  "item_variable": "invoice",
  "steps": [
    {
      "id": "send_reminder",
      "type": "Action",
      "action": "send_invoice_reminder",
      "parameters": {
        "invoice_id": "{{invoice.id}}"
      }
    }
  ]
}

DoUntil Step

Repeat until a condition is met.

{
  "id": "retry_payment",
  "type": "DoUntil",
  "condition": "step_check_status.outputs.status == 'paid' || iteration > 3",
  "steps": [
    {
      "id": "attempt_payment",
      "type": "Action",
      "action": "retry_invoice_payment",
      "parameters": {...}
    },
    {
      "id": "wait",
      "type": "Delay",
      "duration": "24h"
    }
  ]
}

Template Syntax

Use templates to reference dynamic data in your automation.

Basic Syntax

Access data using double curly braces:

{{trigger.account_id}}
{{step_id.outputs.field}}
{{variable_name}}

Accessing Trigger Data

{{trigger.invoice_id}}        // Direct field
{{trigger.account.name}}      // Nested field
{{trigger.account.email}}     // Customer email

Accessing Step Outputs

Reference outputs from previous steps:

{{step_get_invoice.outputs.total}}
{{step_get_subscription.outputs.plan_id}}
{{step_get_invoices.outputs.invoices[0].id}}

Built-in Variables

Variable	Description
`{{now}}`	Current timestamp
`{{today}}`	Current date
`{{iteration}}`	Current loop iteration (in ForEach/DoUntil)
`{{secrets.KEY}}`	Access stored secrets

Filters

Transform values with filters:

{{trigger.amount | currency}}           // Format as currency
{{trigger.due_date | date: 'MMM D'}}   // Format date
{{trigger.name | uppercase}}            // Convert to uppercase
{{trigger.name | lowercase}}            // Convert to lowercase
{{trigger.items | length}}              // Array length
{{now | date_add: '7d'}}                // Add to date
{{now | date_subtract: '30d'}}          // Subtract from date

Condition Syntax

Conditions use the Expr expression language.

Comparison Operators

Operator	Description	Example
`==`	Equal	`trigger.status == 'paid'`
`!=`	Not equal	`trigger.status != 'draft'`
`>`	Greater than	`trigger.amount > 100`
`>=`	Greater or equal	`trigger.attempt_number >= 3`
`<`	Less than	`trigger.balance < 50`
`<=`	Less or equal	`trigger.days_overdue <= 30`

Logical Operators

Operator	Description	Example
`&&`	AND	`trigger.status == 'past_due' && trigger.amount > 100`
`\|\|`	OR	`trigger.status == 'paid' \|\| trigger.status == 'void'`
`!`	NOT	`!trigger.is_test`

String Operations

trigger.email contains '@gmail.com'
trigger.name startsWith 'Acme'
trigger.description endsWith 'trial'
trigger.plan_id in ['plan_basic', 'plan_pro']

Array Operations

len(trigger.line_items) > 0
trigger.tags contains 'enterprise'
any(trigger.invoices, {.status == 'past_due'})
all(trigger.payments, {.status == 'succeeded'})

Null Checks

trigger.discount != nil
trigger.coupon_code ?? 'NONE'

Complete Examples

Dunning Automation

Progressive payment failure handling:

{
  "name": "Payment Dunning Workflow",
  "trigger": {
    "type": "PaymentFailed"
  },
  "steps": [
    {
      "id": "check_attempt",
      "type": "Condition",
      "condition": "trigger.attempt_number == 1",
      "then": [
        {
          "id": "gentle_reminder",
          "type": "Action",
          "action": "send_email",
          "parameters": {
            "template_id": "tmpl_payment_failed_gentle",
            "to": "{{trigger.account.email}}"
          }
        },
        {
          "id": "wait_3_days",
          "type": "Delay",
          "duration": "3d"
        },
        {
          "id": "retry_1",
          "type": "Action",
          "action": "retry_invoice_payment",
          "parameters": {
            "invoice_id": "{{trigger.invoice_id}}"
          }
        }
      ],
      "else": [
        {
          "id": "check_final",
          "type": "Condition",
          "condition": "trigger.attempt_number >= 3",
          "then": [
            {
              "id": "final_notice",
              "type": "Action",
              "action": "send_email",
              "parameters": {
                "template_id": "tmpl_payment_failed_final",
                "to": "{{trigger.account.email}}"
              }
            },
            {
              "id": "cancel_sub",
              "type": "Action",
              "action": "cancel_subscription",
              "parameters": {
                "subscription_id": "{{trigger.subscription_id}}",
                "cancel_at": "immediate",
                "reason": "Payment failed after 3 attempts"
              }
            }
          ]
        }
      ]
    }
  ]
}

Renewal Notification Automation

Notify customers before renewal:

{
  "name": "Renewal Notifications",
  "trigger": {
    "type": "SubscriptionStatusUpdated",
    "filters": {
      "new_status": "active"
    }
  },
  "schedule": {
    "cron": "0 9 * * *"
  },
  "steps": [
    {
      "id": "get_renewing_subs",
      "type": "Action",
      "action": "get_subscriptions",
      "parameters": {
        "status": ["active"],
        "renews_before": "{{now | date_add: '30d'}}"
      }
    },
    {
      "id": "filter_annual",
      "type": "Condition",
      "condition": "len(step_get_renewing_subs.outputs.subscriptions) > 0",
      "then": [
        {
          "id": "notify_customers",
          "type": "Action",
          "action": "send_subscriptions_autorenewal_notification_bulk",
          "parameters": {
            "subscription_ids": "{{step_get_renewing_subs.outputs.subscriptions | map: 'id'}}"
          }
        }
      ]
    }
  ]
}

Low Credit Balance Alert

Alert when credits are running low:

{
  "name": "Low Credit Alert",
  "trigger": {
    "type": "PrepaidUsageUpdate"
  },
  "steps": [
    {
      "id": "check_threshold",
      "type": "Condition",
      "condition": "trigger.threshold_crossed && trigger.threshold_percentage >= 80",
      "then": [
        {
          "id": "alert_customer",
          "type": "Action",
          "action": "send_email",
          "parameters": {
            "template_id": "tmpl_low_credits",
            "to": "{{trigger.account.email}}",
            "variables": {
              "remaining_balance": "{{trigger.current_balance}}",
              "usage_percentage": "{{trigger.threshold_percentage}}"
            }
          }
        },
        {
          "id": "notify_webhook",
          "type": "Action",
          "action": "send_webhook",
          "parameters": {
            "url": "{{secrets.SLACK_WEBHOOK}}",
            "body": {
              "text": "Low credit alert: {{trigger.account.name}} at {{trigger.threshold_percentage}}% usage"
            }
          }
        }
      ]
    }
  ]
}

Error Handling

Retry Configuration

Configure retry behavior for actions:

{
  "action": "send_webhook",
  "parameters": {...},
  "retry": {
    "max_attempts": 3,
    "backoff": "exponential",
    "initial_delay": "30s"
  }
}

On Error Handling

Define behavior when a step fails:

{
  "id": "risky_action",
  "type": "Action",
  "action": "retry_invoice_payment",
  "parameters": {...},
  "on_error": {
    "action": "continue",
    "notify": "{{secrets.ALERT_EMAIL}}"
  }
}

Error actions:

stop - Halt automation
continue - Skip and continue
goto - Jump to specific step

Best Practices

Use Descriptive IDs

Name steps clearly: send_gentle_reminder not step_1.

Test with Small Batches

Test automations with filtered triggers before going live.

Add Delays Thoughtfully

Avoid overwhelming customers with rapid-fire communications.

Log External Calls

Use webhooks to log automation events for debugging.

Next Steps

Automation Overview

Getting started with automations.

Triggers

Learn about trigger types.

Actions

Explore available actions.

Conditions

Build conditional logic.

Overview

Guides

Getting Started

Customers

Pricing & Packaging

Quotes (CPQ)

Subscriptions

Entitlements

Invoices

Credits & Wallets

Usage Metering

Approval Workflows

Automations

Tax Management

Hosted Pages

Revenue & Accounting

Multi-Currency

Data & Exports

AI

​Automation Reference

​Trigger Types

​Payment Failed

​Invoice Status Updated

​Prepaid Usage Update

​Subscription Sent for Signature

​Credits Depleted

​Subscription Status Updated

​Action Types

​Communication Actions

​send_email

​send_invoice_reminder

​send_invoice_reminders_bulk

​send_billing_info_request

​share_customer_portal_link

​send_subscription_signature_reminder

​send_subscriptions_autorenewal_notification_bulk

​Data Retrieval Actions

​get_invoice

​get_invoices

​get_subscription

​get_subscriptions

​Billing Actions

​retry_invoice_payment

​cancel_subscription

​Integration Actions

​send_webhook

​Step Types

​Action Step

​Condition Step

​Delay Step

​ForEach Step

​DoUntil Step

​Template Syntax

​Basic Syntax

​Accessing Trigger Data

​Accessing Step Outputs

​Built-in Variables

​Filters

​Condition Syntax

​Comparison Operators

​Logical Operators

​String Operations

​Array Operations

​Null Checks

​Complete Examples

​Dunning Automation

​Renewal Notification Automation

​Low Credit Balance Alert

​Error Handling

​Retry Configuration

​On Error Handling

​Best Practices

Use Descriptive IDs

Test with Small Batches

Add Delays Thoughtfully

Log External Calls

​Next Steps

Automation Overview

Triggers

Actions

Automation Reference

Trigger Types

Payment Failed

Invoice Status Updated

Prepaid Usage Update

Subscription Sent for Signature

Credits Depleted

Subscription Status Updated

Action Types

Communication Actions

send_email

send_invoice_reminder

send_invoice_reminders_bulk

send_billing_info_request

share_customer_portal_link

send_subscription_signature_reminder

send_subscriptions_autorenewal_notification_bulk

Data Retrieval Actions

get_invoice

get_invoices

get_subscription

get_subscriptions

Billing Actions

retry_invoice_payment

cancel_subscription

Integration Actions

send_webhook

Step Types

Action Step

Condition Step

Delay Step

ForEach Step

DoUntil Step

Template Syntax

Basic Syntax

Accessing Trigger Data

Accessing Step Outputs

Built-in Variables

Filters

Condition Syntax

Comparison Operators

Logical Operators

String Operations

Array Operations

Null Checks

Complete Examples

Dunning Automation

Renewal Notification Automation

Low Credit Balance Alert

Error Handling

Retry Configuration

On Error Handling

Best Practices

Next Steps