Flow definition contract
Author complete nested Flow definitions with the actual schema and cross-field constraints.
On this page
What you need
Owner MCP access and the intended trigger, audience and app scope. Use list_flow_templates for complete implemented examples. Authoring a draft does not activate it.
Steps
- Use
create_flowwith a supported templateKey or a complete definition.update_flowreplaces the definition; it is not a partial nested patch. - Set executionScope explicitly to app for new app-scoped automation. Match the intended app name in filters when limiting a Flow to a particular app; this condition uses the app name, not an app UUID.
- Include trigger, filters, exit and steps. Use explicit null for filters/exit when absent. Review the field schema and business checks below.
- Save as a draft, inspect it with get_flow and preview content. Review current scope/version before any activation or send.
Expected result
A valid draft definition with the intended app execution scope. Live activation requires an email or Slack action and explicit approval; it can deliver externally.
Top-level fields
| Field | Contract |
|---|---|
| executionScope | Optional app or legacy_workspace. Set app explicitly for new definitions. Helpers treat omission as legacy; new creation fills app, while replacement/legacy handling must be reviewed. |
| audience | merchant by default, or partner for affiliate-event Flows. |
| trigger | Required supported lifecycle, trial, activity, custom or affiliate trigger. |
| filters | Required condition object or null; checked at entry. |
| exit | Required condition object or null; rechecked before steps. |
| steps | Required ordered step array; includes nested split branches. |
Complete example
This fictional app-name filter restricts the example. Replace it with the actual unique app name. Saving this template email as a draft does not call an AI provider.
{
"executionScope": "app",
"audience": "merchant",
"trigger": {
"type": "lifecycle",
"events": [
"installed"
]
},
"filters": {
"match": "all",
"checks": [
{
"field": "app",
"in": [
"Example Shopify app"
]
}
]
},
"exit": null,
"steps": [
{
"id": "welcome",
"type": "email",
"mode": "template",
"subject": "Welcome to {{app_name}}",
"body": "Hi {{ first_name | \"there\" }}, welcome to {{app_name}}."
}
]
}
Nested schema
The schema below is exported from the same FlowDefinitionSchema used by the editor and handlers. References in $defs describe recursive split steps. It covers all trigger variants, condition fields/operators and email/wait/Slack/split fields; the business checks below also apply.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"executionScope": {
"type": "string",
"enum": [
"app",
"legacy_workspace"
]
},
"audience": {
"default": "merchant",
"type": "string",
"enum": [
"merchant",
"partner"
]
},
"trigger": {
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "affiliate"
},
"events": {
"minItems": 1,
"maxItems": 20,
"type": "array",
"items": {
"type": "string",
"enum": [
"membership.application",
"membership.approved",
"membership.rejected",
"membership.suspended",
"membership.archived",
"referral.requested",
"referral.accepted",
"commission.updated",
"commission.refunded",
"commission.payable",
"commission.bonus",
"payout.requested",
"payment.reported",
"payment.confirmed",
"payment.disputed",
"payment.resolved",
"payment.reminder",
"payment.confirmation_reminder",
"program.terms_changed",
"membership.terms_proposed"
]
}
}
},
"required": [
"type",
"events"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "lifecycle"
},
"events": {
"minItems": 1,
"type": "array",
"items": {
"type": "string",
"enum": [
"installed",
"reinstalled",
"uninstalled",
"subscribed",
"resubscribed",
"upgraded",
"downgraded",
"unsubscribed",
"subscription_frozen",
"subscription_unfrozen",
"reactivated",
"deactivated"
]
}
}
},
"required": [
"type",
"events"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "trial"
},
"event": {
"type": "string",
"enum": [
"started",
"canceled"
]
}
},
"required": [
"type",
"event"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "trial"
},
"event": {
"type": "string",
"const": "ending"
},
"daysBefore": {
"type": "integer",
"minimum": 1,
"maximum": 14
}
},
"required": [
"type",
"event",
"daysBefore"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "activity"
},
"event": {
"type": "string",
"const": "inactive"
},
"days": {
"type": "integer",
"minimum": 3,
"maximum": 90
}
},
"required": [
"type",
"event",
"days"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "activity"
},
"event": {
"type": "string",
"const": "returned"
},
"afterDays": {
"type": "integer",
"minimum": 3,
"maximum": 90
}
},
"required": [
"type",
"event",
"afterDays"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "custom"
},
"name": {
"type": "string",
"pattern": "^[a-z0-9_.-]{1,64}$"
}
},
"required": [
"type",
"name"
],
"additionalProperties": false
}
]
},
"filters": {
"anyOf": [
{
"type": "object",
"properties": {
"match": {
"type": "string",
"enum": [
"all",
"any"
]
},
"checks": {
"minItems": 1,
"maxItems": 20,
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "partner_status"
},
"in": {
"minItems": 1,
"type": "array",
"items": {
"type": "string",
"enum": [
"requested",
"approved",
"rejected",
"suspended",
"archived"
]
}
}
},
"required": [
"field",
"in"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "partner_balance"
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"op": {
"type": "string",
"enum": [
"gt",
"gte",
"lt",
"lte",
"eq"
]
},
"amountMinor": {
"type": "string",
"pattern": "^-?\\d{1,38}$"
}
},
"required": [
"field",
"currency",
"op",
"amountMinor"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "has_referring_partner"
},
"value": {
"type": "boolean"
}
},
"required": [
"field",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "status"
},
"in": {
"minItems": 1,
"type": "array",
"items": {
"type": "string",
"enum": [
"trialing",
"paying",
"installed_free",
"frozen",
"uninstalled"
]
}
}
},
"required": [
"field",
"in"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "app"
},
"in": {
"minItems": 1,
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
},
"required": [
"field",
"in"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "mrr"
},
"op": {
"type": "string",
"enum": [
"gt",
"gte",
"lt",
"lte",
"eq"
]
},
"value": {
"type": "number"
}
},
"required": [
"field",
"op",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "mrr_before_event"
},
"op": {
"type": "string",
"enum": [
"gt",
"gte",
"lt",
"lte",
"eq"
]
},
"value": {
"type": "number"
}
},
"required": [
"field",
"op",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "install_age_days"
},
"op": {
"type": "string",
"enum": [
"gt",
"gte",
"lt",
"lte",
"eq"
]
},
"value": {
"type": "number"
}
},
"required": [
"field",
"op",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "days_since_last_seen"
},
"op": {
"type": "string",
"enum": [
"gt",
"gte",
"lt",
"lte",
"eq"
]
},
"value": {
"type": "number"
}
},
"required": [
"field",
"op",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "trial_days_left"
},
"op": {
"type": "string",
"enum": [
"gt",
"gte",
"lt",
"lte",
"eq"
]
},
"value": {
"type": "number"
}
},
"required": [
"field",
"op",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "has_email"
},
"value": {
"type": "boolean"
}
},
"required": [
"field",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "is_reinstall"
},
"value": {
"type": "boolean"
}
},
"required": [
"field",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "has_pixel_activity"
},
"value": {
"type": "boolean"
}
},
"required": [
"field",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "country"
},
"in": {
"minItems": 1,
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
},
"required": [
"field",
"in"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "shopify_plan"
},
"in": {
"minItems": 1,
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
},
"required": [
"field",
"in"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "churn_reason"
},
"in": {
"minItems": 1,
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
},
"required": [
"field",
"in"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "plan_name"
},
"contains": {
"type": "string",
"minLength": 1
}
},
"required": [
"field",
"contains"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "event"
},
"source": {
"type": "string",
"enum": [
"api",
"pixel",
"any"
]
},
"name": {
"type": "string",
"pattern": "^[a-z0-9_.-]{1,64}$"
},
"within": {
"anyOf": [
{
"type": "string",
"const": "since_entry"
},
{
"type": "integer",
"minimum": 1,
"maximum": 365
}
]
}
},
"required": [
"field",
"name",
"within"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "event_property"
},
"key": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"op": {
"type": "string",
"enum": [
"eq",
"neq",
"gt",
"lt",
"contains"
]
},
"value": {
"type": [
"string",
"number"
]
}
},
"required": [
"field",
"key",
"op",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "customer_status"
},
"in": {
"minItems": 1,
"type": "array",
"items": {
"type": "string",
"enum": [
"Subscribed",
"Installed",
"Uninstalled",
"Frozen"
]
}
}
},
"required": [
"field",
"in"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "plan"
},
"in": {
"minItems": 1,
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
},
"required": [
"field",
"in"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "churned_within_days"
},
"op": {
"type": "string",
"enum": [
"gt",
"gte",
"lt",
"lte",
"eq"
]
},
"value": {
"type": "number"
}
},
"required": [
"field",
"op",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "in_segment"
},
"segmentId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"required": [
"field",
"segmentId"
],
"additionalProperties": false
}
]
}
}
},
"required": [
"match",
"checks"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"exit": {
"anyOf": [
{
"type": "object",
"properties": {
"match": {
"type": "string",
"enum": [
"all",
"any"
]
},
"checks": {
"minItems": 1,
"maxItems": 20,
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "partner_status"
},
"in": {
"minItems": 1,
"type": "array",
"items": {
"type": "string",
"enum": [
"requested",
"approved",
"rejected",
"suspended",
"archived"
]
}
}
},
"required": [
"field",
"in"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "partner_balance"
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"op": {
"type": "string",
"enum": [
"gt",
"gte",
"lt",
"lte",
"eq"
]
},
"amountMinor": {
"type": "string",
"pattern": "^-?\\d{1,38}$"
}
},
"required": [
"field",
"currency",
"op",
"amountMinor"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "has_referring_partner"
},
"value": {
"type": "boolean"
}
},
"required": [
"field",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "status"
},
"in": {
"minItems": 1,
"type": "array",
"items": {
"type": "string",
"enum": [
"trialing",
"paying",
"installed_free",
"frozen",
"uninstalled"
]
}
}
},
"required": [
"field",
"in"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "app"
},
"in": {
"minItems": 1,
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
},
"required": [
"field",
"in"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "mrr"
},
"op": {
"type": "string",
"enum": [
"gt",
"gte",
"lt",
"lte",
"eq"
]
},
"value": {
"type": "number"
}
},
"required": [
"field",
"op",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "mrr_before_event"
},
"op": {
"type": "string",
"enum": [
"gt",
"gte",
"lt",
"lte",
"eq"
]
},
"value": {
"type": "number"
}
},
"required": [
"field",
"op",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "install_age_days"
},
"op": {
"type": "string",
"enum": [
"gt",
"gte",
"lt",
"lte",
"eq"
]
},
"value": {
"type": "number"
}
},
"required": [
"field",
"op",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "days_since_last_seen"
},
"op": {
"type": "string",
"enum": [
"gt",
"gte",
"lt",
"lte",
"eq"
]
},
"value": {
"type": "number"
}
},
"required": [
"field",
"op",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "trial_days_left"
},
"op": {
"type": "string",
"enum": [
"gt",
"gte",
"lt",
"lte",
"eq"
]
},
"value": {
"type": "number"
}
},
"required": [
"field",
"op",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "has_email"
},
"value": {
"type": "boolean"
}
},
"required": [
"field",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "is_reinstall"
},
"value": {
"type": "boolean"
}
},
"required": [
"field",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "has_pixel_activity"
},
"value": {
"type": "boolean"
}
},
"required": [
"field",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "country"
},
"in": {
"minItems": 1,
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
},
"required": [
"field",
"in"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "shopify_plan"
},
"in": {
"minItems": 1,
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
},
"required": [
"field",
"in"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "churn_reason"
},
"in": {
"minItems": 1,
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
},
"required": [
"field",
"in"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "plan_name"
},
"contains": {
"type": "string",
"minLength": 1
}
},
"required": [
"field",
"contains"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "event"
},
"source": {
"type": "string",
"enum": [
"api",
"pixel",
"any"
]
},
"name": {
"type": "string",
"pattern": "^[a-z0-9_.-]{1,64}$"
},
"within": {
"anyOf": [
{
"type": "string",
"const": "since_entry"
},
{
"type": "integer",
"minimum": 1,
"maximum": 365
}
]
}
},
"required": [
"field",
"name",
"within"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "event_property"
},
"key": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"op": {
"type": "string",
"enum": [
"eq",
"neq",
"gt",
"lt",
"contains"
]
},
"value": {
"type": [
"string",
"number"
]
}
},
"required": [
"field",
"key",
"op",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "customer_status"
},
"in": {
"minItems": 1,
"type": "array",
"items": {
"type": "string",
"enum": [
"Subscribed",
"Installed",
"Uninstalled",
"Frozen"
]
}
}
},
"required": [
"field",
"in"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "plan"
},
"in": {
"minItems": 1,
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
},
"required": [
"field",
"in"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "churned_within_days"
},
"op": {
"type": "string",
"enum": [
"gt",
"gte",
"lt",
"lte",
"eq"
]
},
"value": {
"type": "number"
}
},
"required": [
"field",
"op",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "in_segment"
},
"segmentId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"required": [
"field",
"segmentId"
],
"additionalProperties": false
}
]
}
}
},
"required": [
"match",
"checks"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"steps": {
"type": "array",
"items": {
"$ref": "#/$defs/__schema0"
}
}
},
"required": [
"audience",
"trigger",
"filters",
"exit",
"steps"
],
"additionalProperties": false,
"$defs": {
"__schema0": {
"anyOf": [
{
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 40
},
"type": {
"type": "string",
"const": "email"
},
"mode": {
"type": "string",
"const": "template"
},
"subject": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"body": {
"type": "string",
"minLength": 1,
"maxLength": 5000
}
},
"required": [
"id",
"type",
"mode",
"subject",
"body"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 40
},
"type": {
"type": "string",
"const": "email"
},
"mode": {
"type": "string",
"const": "ai"
},
"brief": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"review": {
"type": "boolean"
}
},
"required": [
"id",
"type",
"mode",
"brief",
"review"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 40
},
"type": {
"type": "string",
"const": "wait"
},
"amount": {
"type": "integer",
"minimum": 1,
"maximum": 90
},
"unit": {
"type": "string",
"enum": [
"hours",
"days"
]
}
},
"required": [
"id",
"type",
"amount",
"unit"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 40
},
"type": {
"type": "string",
"const": "slack"
},
"message": {
"type": "string",
"minLength": 1,
"maxLength": 2000
}
},
"required": [
"id",
"type",
"message"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 40
},
"type": {
"type": "string",
"const": "split"
},
"condition": {
"type": "object",
"properties": {
"match": {
"type": "string",
"enum": [
"all",
"any"
]
},
"checks": {
"minItems": 1,
"maxItems": 20,
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "partner_status"
},
"in": {
"minItems": 1,
"type": "array",
"items": {
"type": "string",
"enum": [
"requested",
"approved",
"rejected",
"suspended",
"archived"
]
}
}
},
"required": [
"field",
"in"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "partner_balance"
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$"
},
"op": {
"type": "string",
"enum": [
"gt",
"gte",
"lt",
"lte",
"eq"
]
},
"amountMinor": {
"type": "string",
"pattern": "^-?\\d{1,38}$"
}
},
"required": [
"field",
"currency",
"op",
"amountMinor"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "has_referring_partner"
},
"value": {
"type": "boolean"
}
},
"required": [
"field",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "status"
},
"in": {
"minItems": 1,
"type": "array",
"items": {
"type": "string",
"enum": [
"trialing",
"paying",
"installed_free",
"frozen",
"uninstalled"
]
}
}
},
"required": [
"field",
"in"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "app"
},
"in": {
"minItems": 1,
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
},
"required": [
"field",
"in"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "mrr"
},
"op": {
"type": "string",
"enum": [
"gt",
"gte",
"lt",
"lte",
"eq"
]
},
"value": {
"type": "number"
}
},
"required": [
"field",
"op",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "mrr_before_event"
},
"op": {
"type": "string",
"enum": [
"gt",
"gte",
"lt",
"lte",
"eq"
]
},
"value": {
"type": "number"
}
},
"required": [
"field",
"op",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "install_age_days"
},
"op": {
"type": "string",
"enum": [
"gt",
"gte",
"lt",
"lte",
"eq"
]
},
"value": {
"type": "number"
}
},
"required": [
"field",
"op",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "days_since_last_seen"
},
"op": {
"type": "string",
"enum": [
"gt",
"gte",
"lt",
"lte",
"eq"
]
},
"value": {
"type": "number"
}
},
"required": [
"field",
"op",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "trial_days_left"
},
"op": {
"type": "string",
"enum": [
"gt",
"gte",
"lt",
"lte",
"eq"
]
},
"value": {
"type": "number"
}
},
"required": [
"field",
"op",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "has_email"
},
"value": {
"type": "boolean"
}
},
"required": [
"field",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "is_reinstall"
},
"value": {
"type": "boolean"
}
},
"required": [
"field",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "has_pixel_activity"
},
"value": {
"type": "boolean"
}
},
"required": [
"field",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "country"
},
"in": {
"minItems": 1,
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
},
"required": [
"field",
"in"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "shopify_plan"
},
"in": {
"minItems": 1,
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
},
"required": [
"field",
"in"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "churn_reason"
},
"in": {
"minItems": 1,
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
},
"required": [
"field",
"in"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "plan_name"
},
"contains": {
"type": "string",
"minLength": 1
}
},
"required": [
"field",
"contains"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "event"
},
"source": {
"type": "string",
"enum": [
"api",
"pixel",
"any"
]
},
"name": {
"type": "string",
"pattern": "^[a-z0-9_.-]{1,64}$"
},
"within": {
"anyOf": [
{
"type": "string",
"const": "since_entry"
},
{
"type": "integer",
"minimum": 1,
"maximum": 365
}
]
}
},
"required": [
"field",
"name",
"within"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "event_property"
},
"key": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"op": {
"type": "string",
"enum": [
"eq",
"neq",
"gt",
"lt",
"contains"
]
},
"value": {
"type": [
"string",
"number"
]
}
},
"required": [
"field",
"key",
"op",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "customer_status"
},
"in": {
"minItems": 1,
"type": "array",
"items": {
"type": "string",
"enum": [
"Subscribed",
"Installed",
"Uninstalled",
"Frozen"
]
}
}
},
"required": [
"field",
"in"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "plan"
},
"in": {
"minItems": 1,
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
},
"required": [
"field",
"in"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "churned_within_days"
},
"op": {
"type": "string",
"enum": [
"gt",
"gte",
"lt",
"lte",
"eq"
]
},
"value": {
"type": "number"
}
},
"required": [
"field",
"op",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"negate": {
"type": "boolean"
},
"field": {
"type": "string",
"const": "in_segment"
},
"segmentId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"required": [
"field",
"segmentId"
],
"additionalProperties": false
}
]
}
}
},
"required": [
"match",
"checks"
],
"additionalProperties": false
},
"yes": {
"type": "array",
"items": {
"$ref": "#/$defs/__schema0"
}
},
"no": {
"type": "array",
"items": {
"$ref": "#/$defs/__schema0"
}
}
},
"required": [
"id",
"type",
"condition",
"yes",
"no"
],
"additionalProperties": false
}
]
}
}
}
Business checks
At most 40 steps across the complete tree, split depth at most four, and unique step IDs. IDs contain 1–40 characters. Templates and AI briefs must use known audience/trigger merge tags. A partner audience requires an affiliate trigger; merchant audiences require merchant triggers.
Condition objects have match all/any and 1–20 checks. Affiliate conditions permit the supported partner fields, app and email checks; merchant flows cannot use partner-only fields. Event-property checks need a custom trigger; trial_days_left needs a trial trigger; mrr_before_event/churn_reason need lifecycle triggers. Choose API event evidence explicitly for consequential backend-event automation; missing coverage remains unknown.
Template emails need subject (1–200) and body (1–5000). AI emails need brief (1–1000) and review boolean; live AI drafting can call Gemini. Waits use 1–90 hours/days; Slack text is 1–2000. Split branches contain steps and a valid condition. The schema lists each variant exactly.
Troubleshooting
Read validation errors with their JSON paths. Unknown merge tags, duplicate IDs, incompatible audience/trigger/checks, excess steps/depth and missing required null fields can reject a definition. Scope-sensitive replacement can pause a Flow and require a new revision acknowledgement. Do not bypass it by omitting scope.
See Build and review Flows, create_flow, update_flow and list_flow_templates.