Skip to content
Pidgely Docs

API reference · Automations

Update an automation

PATCHhttps://api.pidgely.com/automations/{id}
View as Markdown

Changes the name, trigger (organization automations: event, contact_added, contact_date, inactivity), trigger_options, entry filter, goal, exit_events, settings or steps. steps replaces the whole list (1 to 20 steps, at least one e-mail; pass the id of steps you keep so their metrics follow them). Waits go from 5 minutes to 90 days; a wait_event step waits up to wait_seconds (5 minutes to 30 days) for event_name, then continues or exits (on_event, on_timeout). Changes to an active automation apply to customers from their next step on.

Changes the name, trigger options, settings or steps (steps replaces the list: 1 to 20 steps with at least one e-mail; waits from AUTOMATION_MIN_WAIT, 5 minutes by default, to 90 days). Steps edited while it is active apply to customers from their next step on. Admins and owners. Needs a plan with automations (Scale or custom; 403 plan_required otherwise).

Authorization: Bearer pdg_…. An API key with full_access. A sending_access key gets 401 restricted_api_key.

Path parameters

Name Type Required Description
id string Yes Automation id. UUID.

Body parameters

JSON object.

Name Type Required Description
name string No Display name.
trigger string No Organization automations only (store automations keep their trigger). Applies to new enrollments. One of event, contact_added, contact_date, inactivity.
trigger_options object No methods (payment_pending: pix, boleto), delivery_fallback_days (post_purchase: an order paid this many days ago without a delivery event counts as delivered, 1-60), inactive_days (winback: days since the last paid order, 14-730; inactivity: days without the event, 1-365), event_name (event, inactivity), segment_id and sources (contact_added), property, offset_seconds, send_hour and yearly (contact_date).
trigger_options.methods string[] No —
trigger_options.delivery_fallback_days integer No —
trigger_options.inactive_days integer No winback: 14-730; inactivity: 1-365.
trigger_options.event_name string No event: the event that enrolls; inactivity: the event whose absence counts (empty = any event).
trigger_options.segment_id string | null No contact_added: only contacts added to this segment (null = every new contact). UUID.
trigger_options.sources string[] No contact_added: sources of new contacts that count (empty = any).
trigger_options.property string No contact_date: contact property holding the date (YYYY-MM-DD or RFC 3339).
trigger_options.offset_seconds integer No contact_date: signed offset from the date (-259200 = 3 days before).
trigger_options.send_hour integer No contact_date: hour of the day for dates without a time, in the automation's time zone (default 9). Between 0 and 23.
trigger_options.yearly boolean No contact_date: every year on the date (birthdays).
filter object No Entry filter. Only contacts in segment_id (when set) whose properties match every condition enter.
filter.segment_id string | null Yes Segment the broadcast is sent to. UUID.
filter.properties object[] Yes Custom properties: up to 100 keys matching ^[A-Za-z_][A-Za-z0-9_]{0,49}$, values string (up to 2,000 characters), number, boolean, or null to delete.
filter.properties[].key string Yes —
filter.properties[].op string Yes One of eq, neq, exists, not_exists.
filter.properties[].value string No Compared as text (numbers and booleans as written in JSON).
goal object No The event that ends the enrollment as a success (exit reason goal). It counts as a conversion when an e-mail of the automation went out within the attribution window; value_property (major units, e.g. 49.90) is summed as revenue.
goal.event_name string Yes Empty = no goal event (store automations use their orders and payments).
goal.value_property string Yes —
exit_events string[] No —
settings object No Optional behaviours. Quiet hours hold e-mails between start and end o'clock in the store's time zone (from its currency; timezone overrides it) and send them at end. The frequency cap allows one automation e-mail per address per 24 hours across every automation of the organization (later ones wait). Orders placed up to attribution_days after an automation e-mail count as recovered revenue.
settings.quiet_hours object Yes —
settings.quiet_hours.enabled boolean Yes —
settings.quiet_hours.start integer Yes Between 0 and 23.
settings.quiet_hours.end integer Yes Between 0 and 23.
settings.quiet_hours.timezone string No IANA time zone; empty = the store's (organization automations default to America/Sao_Paulo).
settings.frequency_cap boolean Yes —
settings.attribution_days integer Yes Between 1 and 30.
settings.from string No Default sender of an organization automation's e-mails (a step's sender wins; empty = the template's).
settings.currency string No ISO 4217 currency of an organization automation's revenue (default BRL).
steps object[] No —
steps[].id string No An existing step to keep (its metrics follow it); omit for a new step. UUID.
steps[].kind string Yes One of wait, email, wait_event.
steps[].wait_seconds integer No —
steps[].template_id string No A new e-mail step without one gets a copy of the trigger's first default e-mail. UUID.
steps[].subject string No Subject line, up to 998 bytes. Required unless a template provides it.
steps[].from string No —
steps[].coupon_code string No Pattern: ^[A-Za-z0-9_-]{0,64}$.
steps[].event_name string No wait_event: the event to wait for.
steps[].on_event string No One of continue, exit.
steps[].on_timeout string No One of continue, exit.

Request

This endpoint is not in the SDKs yet; call it over HTTP.

cURL
curl -X PATCH 'https://api.pidgely.com/automations/0199e1a0-2b4c-7d6e-8f01-2a3b4c5d6e7f' \
  -H "Authorization: Bearer $PIDGELY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "settings": {
    "quiet_hours": {
      "enabled": true,
      "start": 21,
      "end": 9
    },
    "frequency_cap": true,
    "attribution_days": 5
  },
  "steps": [
    {
      "id": "0199e1a0-2b4d-7a11-8b22-3c4d5e6f7a81",
      "kind": "wait",
      "wait_seconds": 7200
    },
    {
      "id": "0199e1a0-2b4d-7a12-8b23-3c4d5e6f7a82",
      "kind": "email",
      "template_id": "0199e1a0-2b40-7b01-9c02-4d5e6f7a8b91"
    },
    {
      "id": "0199e1a0-2b4d-7a13-8b24-3c4d5e6f7a83",
      "kind": "wait",
      "wait_seconds": 86400
    },
    {
      "id": "0199e1a0-2b4d-7a14-8b25-3c4d5e6f7a84",
      "kind": "email",
      "template_id": "0199e1a0-2b40-7b02-9c03-4d5e6f7a8b92",
      "coupon_code": "VOLTA10"
    }
  ]
}'

Response

200 OK

JSON
{
  "object": "automation",
  "id": "0199e1a0-2b4c-7d6e-8f01-2a3b4c5d6e7f",
  "store_id": "0199e0f2-1a2b-7c3d-9e4f-5a6b7c8d9e01",
  "preset": "cart_abandoned",
  "name": "Carrinho abandonado",
  "trigger": "cart_abandoned",
  "status": "active",
  "status_reason": "",
  "trigger_options": {
    "methods": []
  },
  "filter": {
    "segment_id": null,
    "properties": []
  },
  "goal": {
    "event_name": "",
    "value_property": ""
  },
  "exit_events": [],
  "settings": {
    "quiet_hours": {
      "enabled": true,
      "start": 22,
      "end": 8
    },
    "frequency_cap": true,
    "attribution_days": 7,
    "from": "",
    "currency": ""
  },
  "steps": [
    {
      "id": "0199e1a0-2b4d-7a11-8b22-3c4d5e6f7a81",
      "position": 0,
      "kind": "wait",
      "wait_seconds": 3600,
      "template_id": null,
      "template_name": "",
      "template_subject": "",
      "subject": "",
      "from": "",
      "coupon_code": "",
      "event_name": "",
      "on_event": "",
      "on_timeout": ""
    },
    {
      "id": "0199e1a0-2b4d-7a12-8b23-3c4d5e6f7a82",
      "position": 1,
      "kind": "email",
      "wait_seconds": 0,
      "template_id": "0199e1a0-2b40-7b01-9c02-4d5e6f7a8b91",
      "template_name": "Aurora Moda · Carrinho abandonado · 1",
      "template_subject": "Você esqueceu algo no carrinho",
      "subject": "",
      "from": "",
      "coupon_code": "",
      "event_name": "",
      "on_event": "",
      "on_timeout": ""
    },
    {
      "id": "0199e1a0-2b4d-7a13-8b24-3c4d5e6f7a83",
      "position": 2,
      "kind": "wait",
      "wait_seconds": 82800,
      "template_id": null,
      "template_name": "",
      "template_subject": "",
      "subject": "",
      "from": "",
      "coupon_code": "",
      "event_name": "",
      "on_event": "",
      "on_timeout": ""
    },
    {
      "id": "0199e1a0-2b4d-7a14-8b25-3c4d5e6f7a84",
      "position": 3,
      "kind": "email",
      "wait_seconds": 0,
      "template_id": "0199e1a0-2b40-7b02-9c03-4d5e6f7a8b92",
      "template_name": "Aurora Moda · Carrinho abandonado · 2",
      "template_subject": "Seu carrinho continua salvo",
      "subject": "",
      "from": "",
      "coupon_code": "",
      "event_name": "",
      "on_event": "",
      "on_timeout": ""
    }
  ],
  "currency": "BRL",
  "last_30_days": {
    "enrolled": 412,
    "active": 57,
    "sent": 374,
    "skipped": 2,
    "opened": 198,
    "clicked": 73,
    "exited_goal": 34,
    "exited_other": 7,
    "conversions": 34,
    "revenue": 811190
  },
  "activated_at": "2026-10-12 16:44:41.000000+00",
  "created_at": "2026-10-12 16:44:41.000000+00",
  "updated_at": "2026-10-12 16:44:41.000000+00"
}

Response fields

Name Type Required Description
object string Yes Object type. One of automation.
id string Yes Unique id (UUID). UUID.
store_id string | null Yes Store of a store automation; null for an organization automation (SaaS and apps). UUID.
preset string Yes Preset it was created from (onboarding, trial_ending, dunning, reengagement, saas_checkout, cart_abandoned, payment_pending, post_purchase, winback), or lifecycle_onboarding, lifecycle_first_send, lifecycle_upgrade and lifecycle_reengagement for the lifecycle automations of the platform organization (provisioned by the bootstrap).
name string Yes Display name.
trigger string Yes One of cart_abandoned, payment_pending, post_purchase, winback, event, contact_added, contact_date, inactivity.
status string Yes Current status. One of draft, active, paused.
status_reason string Yes Why it is paused: plan = the organization's plan no longer includes automations. One of ``, manual, plan, store.
trigger_options object Yes methods (payment_pending: pix, boleto), delivery_fallback_days (post_purchase: an order paid this many days ago without a delivery event counts as delivered, 1-60), inactive_days (winback: days since the last paid order, 14-730; inactivity: days without the event, 1-365), event_name (event, inactivity), segment_id and sources (contact_added), property, offset_seconds, send_hour and yearly (contact_date).
trigger_options.methods string[] No —
trigger_options.delivery_fallback_days integer No —
trigger_options.inactive_days integer No winback: 14-730; inactivity: 1-365.
trigger_options.event_name string No event: the event that enrolls; inactivity: the event whose absence counts (empty = any event).
trigger_options.segment_id string | null No contact_added: only contacts added to this segment (null = every new contact). UUID.
trigger_options.sources string[] No contact_added: sources of new contacts that count (empty = any).
trigger_options.property string No contact_date: contact property holding the date (YYYY-MM-DD or RFC 3339).
trigger_options.offset_seconds integer No contact_date: signed offset from the date (-259200 = 3 days before).
trigger_options.send_hour integer No contact_date: hour of the day for dates without a time, in the automation's time zone (default 9). Between 0 and 23.
trigger_options.yearly boolean No contact_date: every year on the date (birthdays).
filter object Yes Entry filter. Only contacts in segment_id (when set) whose properties match every condition enter.
filter.segment_id string | null Yes Segment the broadcast is sent to. UUID.
filter.properties object[] Yes Custom properties: up to 100 keys matching ^[A-Za-z_][A-Za-z0-9_]{0,49}$, values string (up to 2,000 characters), number, boolean, or null to delete.
filter.properties[].key string Yes —
filter.properties[].op string Yes One of eq, neq, exists, not_exists.
filter.properties[].value string No Compared as text (numbers and booleans as written in JSON).
goal object Yes The event that ends the enrollment as a success (exit reason goal). It counts as a conversion when an e-mail of the automation went out within the attribution window; value_property (major units, e.g. 49.90) is summed as revenue.
goal.event_name string Yes Empty = no goal event (store automations use their orders and payments).
goal.value_property string Yes —
exit_events string[] Yes —
settings object Yes Optional behaviours. Quiet hours hold e-mails between start and end o'clock in the store's time zone (from its currency; timezone overrides it) and send them at end. The frequency cap allows one automation e-mail per address per 24 hours across every automation of the organization (later ones wait). Orders placed up to attribution_days after an automation e-mail count as recovered revenue.
settings.quiet_hours object Yes —
settings.quiet_hours.enabled boolean Yes —
settings.quiet_hours.start integer Yes Between 0 and 23.
settings.quiet_hours.end integer Yes Between 0 and 23.
settings.quiet_hours.timezone string No IANA time zone; empty = the store's (organization automations default to America/Sao_Paulo).
settings.frequency_cap boolean Yes —
settings.attribution_days integer Yes Between 1 and 30.
settings.from string No Default sender of an organization automation's e-mails (a step's sender wins; empty = the template's).
settings.currency string No ISO 4217 currency of an organization automation's revenue (default BRL).
steps object[] Yes —
steps[].id string Yes Unique id (UUID). UUID.
steps[].position integer Yes —
steps[].kind string Yes One of wait, email, wait_event.
steps[].wait_seconds integer Yes wait: duration.
steps[].template_id string | null Yes email: builder template (edit it in the template builder). UUID.
steps[].template_name string Yes —
steps[].template_subject string Yes The template's subject in the store's language.
steps[].subject string Yes Subject override; empty = the template's (per language).
steps[].from string Yes Sender; empty = the store's sender address.
steps[].coupon_code string Yes {{{COUPON_CODE}}}; empty = blocks mentioning the coupon are left out.
steps[].event_name string Yes wait_event: the event waited for (up to wait_seconds).
steps[].on_event string Yes wait_event: go on (continue) or end the enrollment (exit, reason event_received) when the event happens. One of ``, continue, exit.
steps[].on_timeout string Yes wait_event: go on or end the enrollment (reason timeout) when the wait runs out. One of ``, continue, exit.
currency string Yes —
last_30_days object Yes Counters over a period: customers enrolled, live (active: active or held now), e-mails sent and skipped, unique opens and clicks (tracked domains), exits by goal (an order, a payment) and for other reasons, conversions and recovered revenue (minor units of the store currency).
last_30_days.enrolled integer Yes —
last_30_days.active integer Yes —
last_30_days.sent integer Yes —
last_30_days.skipped integer Yes —
last_30_days.opened integer Yes —
last_30_days.clicked integer Yes —
last_30_days.exited_goal integer Yes —
last_30_days.exited_other integer Yes —
last_30_days.conversions integer Yes —
last_30_days.revenue integer Yes Format: int64.
activated_at string | null Yes Format: date-time.
created_at string Yes Creation time, YYYY-MM-DD HH:MM:SS.ffffff+00 (UTC). Format: date-time.
updated_at string Yes Format: date-time.

Errors

Errors have the shape {"statusCode", "name", "message"}. See Errors for the full list.

Status Name When
401 missing_api_key, restricted_api_key No Authorization: Bearer header, or a sending_access key called an endpoint that needs full_access.
403 invalid_api_key, validation_error The API key is invalid or revoked, or the request is not allowed for this account (unverified domain, plan limit, paused account).
404 not_found The resource does not exist in this account (or the id is not a valid UUID).
422 validation_error A field is missing or invalid; message names it.
429 rate_limit_exceeded Too many requests per second. Wait for Retry-After seconds.
403 plan_required The organization is below the Scale plan (field is automations).
422 validation_error A step is invalid (field names it, e.g. steps[2].wait_seconds), or the settings are out of range.