Automation Reference - Alguna Docs

Automations are event-driven and scheduled workflows that run inside Alguna — dunning on a failed payment, a renewal quote when a contract nears its end, a CRM update when a quote is signed. This page is the reference for building them: every trigger event type and the payload it carries, the schedule shapes, the step types, an index of the twenty-six actions with their outputs, the template syntax for passing data between steps, the condition expression language, and the outcome reasons an action can report. For the narrative, start with the overview; each action’s parameters are documented on the Actions page. The objects the payloads refer to are described in How Alguna works. Automations are built in the dashboard, in the visual automation builder. There is no public automations API: the values on this page are the identifiers the builder and the engine use, and knowing them helps you read execution logs, write conditions, and reference data between steps. To react to the same events from your own systems, use webhooks instead.

Anatomy of an Automation

An automation is a named container. Each automation holds one or more versions, and each version holds:

exactly one trigger — what starts a run
a set of steps — what the run does
the paths between steps, each optionally guarded by a condition

Only one version is active at a time. Editing an active automation mints a new draft version rather than mutating the running one.

Object	States
Automation	`draft`, `active`, `archived`
Automation version	`draft`, `active`, `inactive`

Trigger Types

Every trigger is one of two types.

Type	Description
`event`	Runs when a platform event of a chosen event type occurs
`schedule`	Runs on a calendar or interval schedule

Both types accept an optional condition and an execution policy. See Trigger filtering below.

Event Trigger Types

There are twelve event trigger types.

Event type	Name	Category	Fires when
`payment_failed`	Payment Failed	payments	A payment attempt fails
`card_expiring`	Card Expiring	payments	A customer’s stored card enters its expiry month
`invoice_status_updated`	Invoice Status Updated	invoicing	An invoice status changes
`prepaid_usage_update`	Prepaid Usage Update	usage_metering	Prepaid usage is updated
`credits_depleted`	Credits Depleted	usage_metering	A customer’s credits balance is fully depleted
`subscription_sent_for_signature`	Subscription Sent for Signature	quotes	A subscription is sent for signature
`quote_signed`	Quote Signed	quotes	Every signer has signed a quote and its signature session completes
`subscription_status_updated`	Subscription Status Updated	subscriptions	A subscription status changes
`subscription_renewal_window_entered`	Subscription Renewal Window Entered	subscriptions	A subscription’s contract end date falls within the renewal window
`flow_session_completed`	Flow Session Completed	subscriptions	A hosted flow session is completed
`salesforce_opportunity_changed`	Salesforce Opportunity Changed	crm	A Salesforce opportunity is created or changed
`hubspot_deal_changed`	HubSpot Deal Changed	crm	A HubSpot deal is created or changed

These are not the same as webhook events. Webhook subscriptions use a separate, larger catalogue of events (invoice.paid, subscription.activated, and so on) and cannot be used as automation triggers. Automation triggers use the snake_case identifiers above.

Event payloads

The fields below are the trigger’s event data. Reference them from a step as {{trigger.inputs.<field>}}, and from a trigger condition by their bare field name.

payment_failed

Field	Type	Always present	Description
`paymentId`	string	Yes	The ID of the failed payment
`accountId`	string	Yes	The ID of the customer associated with the failed payment
`invoiceId`	string	No	The ID of the invoice if the payment was for an invoice
`paymentMethodId`	string	No	The ID of the payment method used for the failed payment
`amount`	decimal	Yes	The amount of the failed payment
`currency`	string	Yes	The currency code of the payment (3-letter ISO code)
`failureReason`	string	Yes	The reason why the payment failed

card_expiring

Field	Type	Always present	Description
`accountId`	string	Yes	The ID of the customer the expiring card belongs to
`paymentMethodId`	string	Yes	The ID of the expiring card payment method
`cardBrand`	string	No	The brand of the expiring card (e.g. visa)
`cardLastFour`	string	No	The last four digits of the expiring card
`cardExpiryMonth`	integer	Yes	The month (1-12) the card expires
`cardExpiryYear`	integer	Yes	The year the card expires
`isDefault`	boolean	No	Whether the expiring card is the account’s default payment method

invoice_status_updated

Field	Type	Always present	Description
`invoiceId`	string	Yes	The ID of the invoice whose status was updated
`accountId`	string	Yes	The ID of the customer associated with the invoice
`status`	string	Yes	The new status of the invoice
`externalReference`	string	No	Optional external reference associated with the invoice

status is one of: draft, upcoming, pending_approval, scheduled, processing, issued, void, paid, canceled, overdue.

prepaid_usage_update

Field	Type	Always present	Description
`priceId`	string	Yes	The ID of the prepaid price
`productId`	string	Yes	The ID of the product associated with the prepaid usage
`productName`	string	No	The name of the prepaid product
`subscriptionVersionId`	string	Yes	The ID of the subscription version
`accountId`	string	Yes	The ID of the customer with prepaid usage
`maxUsageBeforeOverages`	integer	Yes	The maximum prepaid usage before overages apply
`currentUsage`	number	Yes	The current usage amount
`usagePercentage`	number	Yes	The percentage of prepaid usage consumed, as a fraction (`0.8` is 80%)

credits_depleted

Field	Type	Always present	Description
`customerId`	string	Yes	The ID of the customer whose credits were depleted
`creditType`	string	Yes	The type of credits that were depleted (monetary or units)

subscription_sent_for_signature

Field	Type	Always present	Description
`customerId`	string	Yes	The ID of the customer
`subscriptionId`	string	Yes	The ID of the subscription
`recipients`	string[]	Yes	List of recipient email addresses
`isReminder`	boolean	Yes	Whether this is a reminder email
`recipientType`	string	Yes	The type of recipient: `customer` or `internal`

quote_signed

Field	Type	Always present	Description
`quoteID`	string	Yes	The ID of the signed quote
`subscriptionID`	string	Yes	The ID of the subscription the signed quote belongs to
`accountID`	string	Yes	The ID of the customer the quote belongs to

subscription_status_updated

Field	Type	Always present	Description
`subscriptionId`	string	Yes	The ID of the subscription whose status was updated
`status`	string	Yes	The new status of the subscription

status is one of: draft, sent, accepted, active, canceled, paused, pending_approval, rejected, withdrawn, expired.

subscription_renewal_window_entered

Field	Type	Always present	Description
`subscriptionID`	string	Yes	The ID of the subscription entering its renewal window
`accountID`	string	Yes	The ID of the customer the subscription belongs to
`termEnd`	string	Yes	The subscription’s contract end date (RFC3339)
`daysUntilRenewal`	integer	Yes	The number of days remaining until the term ends, as of this run
`renewalKey`	string	Yes	Stable dedup key for this term, formatted as `<subscriptionID>:<termEnd>`
`currency`	string	No	The subscription’s currency, when known
`currentACV`	string	No	The subscription’s current annual contract value, as a decimal string, when resolvable

flow_session_completed

Field	Type	Always present	Description
`flowSessionId`	string	Yes	The ID of the completed flow session
`hostedFlowId`	string	No	The ID of the hosted flow (absent for standalone views)
`accountId`	string	No	The account ID associated with the session

salesforce_opportunity_changed

Field	Type	Always present	Description
`provider`	string	Yes	The CRM provider the change came from (e.g. salesforce)
`integrationID`	string	Yes	The ID of the CRM integration connection
`recordID`	string	Yes	The opportunity’s id in Salesforce
`recordURL`	string	No	A link to the opportunity in Salesforce, if available
`stage`	string	No	The opportunity’s current StageName
`stageEntered`	boolean	Yes	True when this change moved the record into its current stage. False on first sight of a record.
`changedFields`	object	Yes	Field-level before/after values for every field that changed. May be empty.

hubspot_deal_changed

Field	Type	Always present	Description
`provider`	string	Yes	The CRM provider the change came from (e.g. hubspot)
`integrationID`	string	Yes	The ID of the CRM integration connection
`recordID`	string	Yes	The deal’s id in HubSpot
`recordURL`	string	No	A link to the deal in HubSpot, if available
`stage`	string	No	The deal’s current dealstage
`stageEntered`	boolean	Yes	True when this change moved the record into its current stage. False on first sight of a record.
`changedFields`	object	Yes	Field-level before/after values for every field that changed. May be empty.

Each entry in changedFields is keyed by the CRM field name and holds a before/after pair, so a condition can read changedFields.Amount.after.

Trigger Filtering

A trigger has no separate filter language. Narrowing happens in two places.

Condition

An optional condition attached to the trigger. It is a set of expr expressions combined with and, or, or not, evaluated directly against the event payload’s top-level fields.

usagePercentage >= 0.8
status == "overdue"
stageEntered && stage == "Closed Won"

If the condition is not satisfied, no run starts.

Execution policy

Policy	Behavior
`always`	Run every time the trigger fires and its condition passes
`once`	Run only once per unique value of a chosen event field

With once, you also pick an event field key — a field from the event payload, either a top-level key (accountId) or a dot path into a nested object (changedFields.Amount.after). The first event carrying a given value runs the automation; later events carrying the same value are suppressed. Suppression is scoped to the automation, not to the version, so editing an automation does not reset its history and re-fire values it has already handled. Some event types refine the slot further — prepaid_usage_update scopes suppression to the commitment period and the prepaid price, so a customer can be alerted again in the next period.

Schedule Triggers

A schedule trigger carries one of two shapes.

Calendar

The shape the builder writes. Each field is a list of { start, end, step } ranges; the schedule fires at every point matching all of them.

Field	Description
`year`	Years to run in
`month`	Months (1-12)
`dayOfMonth`	Days of the month (1-31)
`dayOfWeek`	Days of the week (1 = Monday … 7 = Sunday)
`hour`	Hours (0-23)
`minute`	Minutes (0-59)
`second`	Seconds (0-59)
`comment`	Free-text note describing the schedule

Interval

Field	Description
`every`	A duration — `{ duration, unit }` — between runs
`offset`	Optional duration shifting the phase of the interval

Automations do not accept cron expressions. A schedule is either a calendar or an interval shape; there is no cron field anywhere in the trigger model.

Duration units are seconds, minutes, hours, days, weeks, months, quarters, years.

Step Types

Type	Description
`action`	Executes one action
`condition`	Splits the graph; each outgoing path carries its own condition
`delay`	Waits for a duration before continuing
`for_each`	Runs a sub-flow once per item of an array from a previous step’s output
`do_until`	Repeats a sub-flow until an exit condition is met

The automation builder currently offers action, condition, and delay steps. for_each and do_until are executed by the engine and appear in automations that use them, but are not yet offered as choices in the builder.

Delay steps

A delay carries a duration and a unit — seconds, minutes, hours, days, weeks, months, years in the builder.

Condition steps

A condition step has no “then” and “else” fields of its own. Instead it fans out into branches, and each outgoing path carries its own condition expression. A path with no condition is the fall-through.

for_each steps

Field	Description
Array source	The previous step output to iterate over
Wait mode	`all` (wait for every iteration) or `first_to_complete`
Max parallel	Optional cap on concurrent iterations

do_until steps

Field	Description
Iteration interval	Duration to wait between iterations
Exit condition	Condition evaluated before each iteration, optionally against the output of a data-source action
Max iterations	Optional safety cap

Actions

There are twenty-six actions, grouped by category. The list is a closed set — you cannot register a custom action; use send_webhook to reach anything Alguna does not cover. Every action’s parameters, with types and descriptions, are documented once on the Actions page; this table is the index, with the outputs each action makes available to later steps as {{<stepId>.outputs.<field>}}. Parameter names are exactly as the engine serializes them. A few CRM parameters end in a capitalised ID (recordID, integrationID, planID); the rest use Id.

Action	Category	Required parameters	Outputs
`send_email`	notifications	`accountId`, `from`, `subject`, `body`	—
`send_slack_message`	notifications	`integrationId`, `channelId`, `messageBody`	—
`send_webhook`	notifications	`url`, `body`	—
`send_billing_info_request`	notifications	`accountId`	—
`share_customer_portal_link`	notifications	`accountId`	—
`send_card_expiration_reminder`	payments	`accountId`, `paymentMethodId`	—
`retry_invoice_payment`	invoicing	`previousPaymentId`, `invoiceId`	`invoiceId`, `paymentMethodId`, `paymentId`, `status`, `failureReason`
`send_invoice_reminder`	invoicing	`invoiceId`	—
`send_invoice_reminders_bulk`	invoicing	`invoices`	`sentInvoices`, `failedInvoices`, `skippedInvoices`
`cancel_subscription`	subscriptions	`subscriptionId`	`subscriptionId`
`send_subscriptions_autorenewal_notification_bulk`	subscriptions	`subscriptions`	`sentSubscriptions`, `failedSubscriptions`, `skippedSubscriptions`
`send_subscription_signature_reminder`	quotes	`subscriptionId`	—
`create_quote`	quotes	`kind`, `accountId`	`created`, `quoteId`, `subscriptionId`, `opportunityId`, `reason`
`activate_quote`	quotes	`quoteId`	`activated`, `quoteId`, `subscriptionId`, `reason`
`get_crm_opportunity`	crm	one of `recordID` / `quoteId`	`opportunityId`, `externalId`, `name`, `stage`, `amount`, `currency`, `closeDate`, `ownerName`, `url`, `accountId`, `externalAccountId`, `quoteId`, `linkedQuoteIds`
`create_crm_record`	crm	`objectType`	`created`, `updated`, `skipped`, `externalId`, `opportunityId`, `reason`
`update_crm_record`	crm	`quoteId`	`updated`, `skipped`, `opportunityId`, `reason`
`set_opportunity_stage`	crm	`stage` + one of `subscriptionId` / `quoteId` / `recordID`	`updated`, `skipped`, `opportunityExternalId`, `reason`
`create_quote_from_opportunity`	crm	`recordID`, `integrationID`	`created`, `quoteId`, `subscriptionId`, `opportunityId`, `accountId`, `reason`
`void_open_quotes_for_opportunity`	crm	one of `recordID` / `quoteId`	`opportunityId`, `quotesVoided`, `quotesSkipped`, `reason`
`cancel_renewal_for_lost_opportunity`	crm	one of `recordID` / `quoteId`	`scheduled`, `subscriptionId`, `effectiveDate`, `reason`
`get_invoice`	general	`invoiceId`	the invoice shape
`get_invoices`	general	—	`invoices`, an array of the invoice shape
`get_subscription`	general	`subscriptionId`	the subscription shape
`get_subscriptions`	general	—	`subscriptions`, an array of the subscription shape
`set_tags_on_entity`	general	`entityType`, `entityId`, `tagIds`	`entityType`, `entityId`, `tagIds`

Where an action lists “one of” several parameters, provide exactly one. integrationID is only meaningful together with recordID and defaults to the organization’s connected CRM.

Object Shapes

The lookup and bulk actions pass around reduced invoice and subscription shapes. These are the fields available on step outputs.

Invoice shape

id, accountId, subscriptionId, currency, status, amount, amountPaid, amountDue, issueDate, dueDate, overdueDays, dueInDays, autoPay, paidDate, voidDate, tagIds.

Subscription shape

id, name, accountId, status, currency, contractPeriodType, contractDuration, contractStartDate, contractEndDate, activatedAt, endedAt, autoRenew, renewalPeriodType, renewalDuration, cancelationReason, daysUntilRenewal, signedByCustomer, customerName, acv, arr, mrr, tagIds.

Template Syntax

Action inputs and path conditions can reference values produced earlier in the run. A reference is a dotted path in double braces, and it always has at least three segments: the source, inputs or outputs, and the field.

{{trigger.inputs.invoiceId}}
{{trigger.inputs.changedFields.Amount.after}}
{{get_invoice_step.outputs.amountDue}}
{{get_invoices_step.outputs.invoices}}

Source	Meaning
`trigger.inputs.<field>`	A field from the triggering event’s payload
`<stepId>.inputs.<field>`	An input that was passed to an earlier step
`<stepId>.outputs.<field>`	A value produced by an earlier step

A value that is entirely one reference resolves to that value with its type preserved — an array stays an array, a number stays a number. A reference embedded inside a longer string is substituted into the string:

Invoice {{trigger.inputs.invoiceId}} is overdue

References also work inside nested objects and arrays, such as the cta object on send_email.

There is no filter pipeline. {{ amount | currency }}, {{ now }}, and {{ secrets.KEY }} are not supported — a reference is a path into the run’s data and nothing else. Secrets belong in the connected integration, not in an automation input.

Condition Syntax

Conditions use the expr expression language. A condition is a list of expressions plus a logical operator that joins them.

Operator	Meaning
`and`	Every expression must be true
`or`	At least one expression must be true
`not`	Every expression must be false

Trigger conditions are evaluated against the event payload, so fields are referenced by bare name. Path conditions are evaluated after template references are resolved, so they reference step data with {{...}} paths.

Comparison operators

Operator	Description	Example
`==`	Equal	`status == "overdue"`
`!=`	Not equal	`status != "draft"`
`>`	Greater than	`amount > 100`
`>=`	Greater or equal	`usagePercentage >= 0.8`
`<`	Less than	`daysUntilRenewal < 30`
`<=`	Less or equal	`overdueDays <= 30`
`in`	Member of a list	`status in ["issued", "overdue"]`
`not in`	Not a member of a list	`status not in ["void", "canceled"]`

The builder also offers is null / is not null for scalar fields, and contains, does not contain, is empty, is not empty for array fields.

Logical operators inside an expression

Operator	Description	Example
`&&`	AND	`stageEntered && stage == "Closed Won"`
`\|\|`	OR	`status == "paid" \|\| status == "void"`
`!`	NOT	`!autoPay`

Collections and null

len(linkedQuoteIds) > 0
any(invoices, .status == "overdue")
all(subscriptions, .autoRenew)
invoiceId != nil

An identifier that is absent from a sparse change payload resolves to nil rather than failing to compile, which is what makes changedFields.Amount.after safe to write against CRM change events that carry only the fields that changed. An expression that cannot be evaluated against the payload is treated as not satisfied.

Execution Outcome Reasons

Actions that may legitimately write nothing report a reason on their output instead of failing. Reading these in the execution log tells you why a run did less than you expected. already_active, already_automated, no_linked_opportunity, no_crm_integration, already_created, already_signed, already_void, already_expired, already_rejected, subscription_active, not_a_renewal_opportunity, already_cancelled, cancellation_already_scheduled, already_renewed, expansion_already_open, no_active_subscription, ambiguous_subscription, no_opportunity_link, stage_already_set, stage_owned_inbound.

Failure Handling

Automations have no per-step retry or fallback configuration. Behavior on failure is fixed:

Invalid inputs — a required parameter missing, or a template reference that cannot be resolved — fail the step permanently. There is no retry.
Execution failures — a downstream service being briefly unavailable, for instance — are retried automatically by the workflow engine.
Outcome reasons are not failures. An action that reports skipped with a reason has succeeded; the run continues.

To branch on an action’s result, read its outputs in a following condition step rather than reaching for an error handler.

Next Steps

Automation Overview

Getting started with automations.

Triggers

Learn about trigger types.

Actions

Explore available actions.

Conditions

Build conditional logic.

​Anatomy of an Automation

​Trigger Types

​Event Trigger Types

​Event payloads

​payment_failed

​card_expiring

​invoice_status_updated

​prepaid_usage_update

​credits_depleted

​subscription_sent_for_signature

​quote_signed

​subscription_status_updated

​subscription_renewal_window_entered

​flow_session_completed

​salesforce_opportunity_changed

​hubspot_deal_changed

​Trigger Filtering

​Condition

​Execution policy

​Schedule Triggers

​Calendar

​Interval

​Step Types

​Delay steps

​Condition steps

​for_each steps

​do_until steps

​Actions

​Object Shapes

​Invoice shape

​Subscription shape

​Template Syntax

​Condition Syntax

​Comparison operators

​Logical operators inside an expression

​Collections and null

​Execution Outcome Reasons

​Failure Handling

​Next Steps

Automation Overview

Triggers

Actions

Conditions

Anatomy of an Automation

Trigger Types

Event Trigger Types

Event payloads

payment_failed

card_expiring

invoice_status_updated

prepaid_usage_update

credits_depleted

subscription_sent_for_signature

quote_signed

subscription_status_updated

subscription_renewal_window_entered

flow_session_completed

salesforce_opportunity_changed

hubspot_deal_changed

Trigger Filtering

Condition

Execution policy

Schedule Triggers

Calendar

Interval

Step Types

Delay steps

Condition steps

for_each steps

do_until steps

Actions

Object Shapes

Invoice shape

Subscription shape

Template Syntax

Condition Syntax

Comparison operators

Logical operators inside an expression

Collections and null

Execution Outcome Reasons

Failure Handling

Next Steps