Apply an action to a payout intent's schedule

Applies a pause, resume, or skip-next action to the active schedule on a single type payout intent, and returns the full, current representation of the intent afterward. The entity_id is always resolved from the authenticated caller and cannot be supplied in the request body.

Three actions are supported via action:

pause — only valid while the intent's status is scheduled or recurring. Moves the intent to paused and stops any further automatic occurrences from firing until it is resumed.

resume — only valid while the intent's status is paused. Moves the intent back to scheduled (for a once schedule) or recurring (for a recurring schedule), and re-arms the next occurrence at the next_run_at timestamp that was already pending when the schedule was paused.

skip-next — only valid while the intent's status is recurring (a once schedule has no next occurrence to skip). Advances next_run_at to the occurrence after the upcoming one, using the same cadence rules (interval_ms or cron) the scheduler itself uses, without dispatching a payout intent action for the skipped occurrence. If no further occurrence remains after skipping (the schedule's end_at or max_occurrences bound is reached), the intent's status transitions to completed and next_run_at is cleared instead.

Each action is validated against the intent's current status before it is applied; sending an action that doesn't match the intent's current state returns a 400 error instead of silently no-op'ing. The underlying update is applied with an optimistic status guard, so a request that loses a race against the scheduler firing the occurrence concurrently also fails with a 400 rather than corrupting the schedule state.

Request

Authorization

JWT Bearer

Add the parameter

Authorization

to Headers

Example:

Authorization: ********************

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Path Params

Body Params application/jsonRequired

Examples

application/json

The action was applied successfully. The full, current representation of the intent is returned, reflecting the new status, status_reason, and (for resume/skip-next) an updated next_run_at.

Bodyapplication/json

curl --location --request PATCH '/payout-intent-schedule-actions/01J3KQZM0000000000000000AB' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "action": "pause", "action_reason": "Vendor requested a temporary hold on payments" }'

{ "message": "Payout intent schedule action applied successfully", "status": "success", "data": { "id": "01J3KQZM0000000000000000AB", "entity_id": "01J3KQ0000000000000000ENTT", "account_id": "01J3KQABC0000000000000000X", "currency": "NGN", "amount": 500000, "client_reference": "payout_ref_20250805_0091", "status": "paused", "status_reason": "Vendor requested a temporary hold on payments", "type": "single", "schedule": { "type": "recurring", "start_at": 1754500000000, "max_occurrences": 12, "interval_ms": 2592000000 }, "action_template": { "type": "payout", "currency": "NGN", "amount": 500000, "counterparty": { "email": "vendor@example.com", "account_number": "0123456789", "bank_code": "058" } }, "next_run_at": 1754500000000, "occurrence_count": 3, "last_fired_at": 1759233600000, "created": 1754388720000, "updated": 1759320000000 } }

Apply an action to a payout intent's schedule

Request

Responses