Scheduled Runs

A scheduled run calls your hosted app on a cron instead of in response to a request. Use one for work that no Whop event triggers, such as pulling new orders from another system every 15 minutes or reconciling payouts overnight.

Set a schedule

An app has two schedules. Set either or both with Update app:

curl -X PATCH "https://api.whop.com/api/v1/apps/app_XXXXXXXX" \
  -H "Authorization: Bearer $WHOP_DEVELOPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule": "0 3 * * *",
    "per_install_schedule": "*/15 * * * *"
  }'

Field	Runs
`schedule`	Once per slot, for the app as a whole.
`per_install_schedule`	Once per slot for every account that has the app installed. Each run carries that installation. Can’t fire more often than every 15 minutes.

Both take a five-field cron expression, read in UTC, of at most 64 characters. The expression has to fire at least once. schedule has no minimum interval. Send null or an empty string to clear a schedule. An invalid expression returns a 400. The key needs developer:update_app on the account that owns the app.

Handle the run

Export scheduled() next to fetch() in your build’s server entry:

src/server.ts

export default {
  async fetch(request, env, ctx) {
    /* ... */
  },

  async scheduled(controller, env, ctx) {
    const { kind, app_installation } = ctx.props;

    if (kind === "global") {
      await reconcilePayouts();
      return;
    }

    await syncOrders(app_installation.external_id, app_installation.metadata.orders_cursor);
  },
};

ctx.props says which run this is:

Prop	Value
`kind`	`global` for a `schedule` run, `install` for a `per_install_schedule` run.
`app_installation`	The installation, as the app installation object. `null` on a `global` run.
`run_id`	ID of this slot’s run. Every installation’s run in the same slot shares it.
`scheduled_at`	The slot the run is for, as an ISO 8601 timestamp.
`attempt`	`1` on the first try, `2` on the retry.

controller.cron is the expression that scheduled the run, and controller.scheduledTime is the slot in milliseconds since the epoch. A run uses the same isolate as your request handlers, so secrets and the injected API key work the same way. A run can last up to 15 minutes, where a request handler gets 30 seconds.

Keep a per-installation sync cursor in the installation’s metadata, as described in App installations. Each run reads it from ctx.props.app_installation.metadata and writes the new value back when it finishes.

Retries and repeated runs

If a run fails, Whop retries it one time, a minute later, then drops it. To skip the retry, call controller.noRetry() before you throw. On the retry, attempt is 2 and scheduled_at is still the original slot. The same slot can reach your app more than once, and a retry can start while the next slot’s run is already going. If your work must not happen twice, record each run you finish under run_id plus app_installation.id, and skip a run you’ve already recorded.

Skipped slots

No run happens while the app has no production web build with a server entry. Whop doesn’t queue a slot it skipped or make it up later, so build each run to carry on from whatever the last one saved.

Logs

A run’s console output and uncaught errors appear in your app’s logs, next to its requests.

Set a schedule

Handle the run

Retries and repeated runs

Skipped slots

Logs

Next steps

App installations

Hosting

​Set a schedule

​Handle the run

​Retries and repeated runs

​Skipped slots

​Logs

​Next steps

App installations

Hosting

Set a schedule

Handle the run

Retries and repeated runs

Skipped slots

Logs

Next steps