PayMongo HomeGuidesAPI ReferenceStart Building
Guides

Schedule-Based Triggers

Use schedule-based triggers to run workflows on cron schedules, predefined macros, or interval-based recurrence.


A schedule-based trigger runs a workflow on a cron schedule. The cron expression is evaluated by our workflow engine. Every supported cron form, predefined macro, and time zone clause works the same way.

Cron format

The Workflow API accepts standard 5-field cron expressions, predefined macros, and an optional time-zone prefix.

FormExampleDescription
5-field cron0 2 * * *Minute, hour, day of month, month, day of week. Whitespace-separated.
Predefined macro@dailyOne of @yearly, @monthly, @weekly, @daily, @hourly.
Interval shorthand@every 1h30mFires repeatedly at the given Go-style duration interval. Useful for sub-hourly recurrence.
Time-zone prefixCRON_TZ=Asia/Manila 0 9 * * *Evaluates the rest of the expression in the named time zone. Without a prefix, the schedule runs in UTC.
⚠️

Time zone defaults to UTC. If your business runs on Asia/Manila or another local time zone, prefix the cron with CRON_TZ=Asia/Manila or you may run a daily job 8 hours later than expected.

Common patterns

PatternCron expressionDescription
Every minute (testing)* * * * *Fires every minute. Delete the trigger after testing.
Every 30 minutes@every 30mSub-hourly recurrence.
Every hour at minute 55 * * * *Fires at HH:05.
Daily at 02:00 (UTC)0 2 * * *Fires once per day at 02:00 UTC.
Daily at 09:00 (Manila)CRON_TZ=Asia/Manila 0 9 * * *Fires once per day at 09:00 PHT.
Every Monday at 09:00 (Manila)CRON_TZ=Asia/Manila 0 9 * * 1Day-of-week 1 = Monday.
Monthly on the 1st at midnight0 0 1 * *First day of every month, 00:00 UTC.

Examples

Daily settlement

Run the workflow every day at 09:00 Manila time:

curl --request POST 'https:/api.paymongo.com/v1/workflows/triggers' \
  --header 'Authorization: Basic ${YOUR_BASIC_TOKEN}' \
  --header 'Organization-Id: ${YOUR_ORG_ID}' \
  --header 'Content-Type: application/json' \
  --data '{
    "workflow_id": "wf_abc123",
    "condition": {
      "schedule": "CRON_TZ=Asia/Manila 0 9 * * *"
    }
  }'

Response:

{
  "id": "trg_xyz",
  "workflow_id": "wf_abc123",
  "state": "active",
  "condition": {"schedule": "CRON_TZ=Asia/Manila 0 9 * * *"},
  "livemode": true,
  "created_at": "...",
  "updated_at": "..."
}

Weekly sweep

Sweep wallets every Monday at 09:00 Manila time:

curl --request POST 'https://api.paymongo.com/v1/workflows/triggers' \
  --header 'Authorization: Basic ${YOUR_BASIC_TOKEN}' \
  --header 'Organization-Id: ${YOUR_ORG_ID}' \
  --header 'Content-Type: application/json' \
  --data '{
    "workflow_id": "wf_sweep",
    "condition": {
      "schedule": "CRON_TZ=Asia/Manila 0 9 * * 1"
    }
  }'

What the workflow sees

When a schedule fires, the workflow input is empty ({}). Schedule-based workflows must rely on data they read at runtime (for example, with get_wallet_balance ) rather than data passed in by the trigger.

One-shot scheduling

The Workflow API does not currently support one-shot schedules (a single cron fire at a specific timestamp). For one-shot behaviour, create a recurring trigger and delete it after the first instance fires:

# Step 1: create the trigger
# (see Quickstart for the full payload)

# Step 2: delete after the first fire
curl --request DELETE 'https://api.paymongo.com/v1/workflows/triggers/${TRIGGER_ID}' \
  --header 'Authorization: Basic ${YOUR_BASIC_TOKEN}' \
  --header 'Organization-Id: ${YOUR_ORG_ID}'

See Also

Updated about 1 month ago

Did this page help you?