Configure scheduled payments

Configure scheduled payments in root.config.json so the platform knows when to create and submit due payments.

Add billing settings

Add a billingSettings block to your root.config.json. Submission settings live under a batching object; retry settings live under retry.

{
  "billingSettings": {
    "batching": {
      "enabled": true,
      "submitPaymentsFunction": "submitPayments",
      "submitBatchSize": 100,
      "scheduleTimeUtc": "05:00",
      "submissionLeadTime": 2,
      "latestSubmissionTimeUtc": "20:00"
    },
    "retry": { "maxAttempts": 3, "backoffDays": 1, "backoffMultiplier": 2 }
  }
}

`batching`

Controls how and when your module submits payments to an API provider. Leave enabled off to keep using a file-based debit provider through the platform batcher.

Field	Type	Description
`enabled`	`boolean`	Set to `true` to have your module submit payments through its own hook (an API payment provider). Leave it `false` to use a file-based debit provider through the platform batcher. Defaults to `false`.
`submitPaymentsFunction`	`string`	The name of your submission hook. Required when `enabled` is `true`; ignored otherwise. See Submit scheduled payments.
`submitBatchSize`	`number`	The largest number of payments passed to your submission hook in one call, between `1` and `500`. Defaults to `100`. The platform splits a larger batch into chunks of this size. Choose a size your provider's rate limits can absorb.
`scheduleTimeUtc`	`string`	The UTC time of day (`HH:MM`) at which the platform submits your due payments. Despite the name, this controls submission time, not when the schedule or payment is created. Defaults to `"05:00"`.
`submissionLeadTime`	`number`	How many days before the due date the platform may create the payment. Defaults to `0` (create on the due date). Capped at 7; larger values are clamped to 7.
`latestSubmissionTimeUtc`	`string`	The UTC time of day (`HH:MM`) after which the platform stops submitting until the next day. The default `"00:00"` is treated specially as midnight end-of-day, so submission is never deferred. Set a real time, for example `"20:00"`, to stop submitting after that point, and keep it comfortably before your provider's cutoff so there is room to retry.

`retry` Optional

Controls how the platform retries a payment after it fails. Omit the block to use the defaults below, which disable retries.

Field	Type	Description
`maxAttempts`	`number`	How many times a failed payment is retried. Defaults to `0`.
`backoffDays`	`number`	Days to wait before the first retry. Defaults to `0`.
`backoffMultiplier`	`number`	Multiplier applied to the wait after each attempt. Defaults to `1`.

Dates and amounts

Use calendar dates without times for scheduled_for, billing_period_start, and billing_period_end. The examples use ISO calendar date strings such as "2026-08-01". Keep submission times in UTC HH:MM.
Set expected_amount in the smallest currency unit, for example cents.

Next step

Create and manage schedules by returning scheduling actions from lifecycle hooks.

Add billing settings

batching

retry Optional

Dates and amounts

Next step

`batching`

`retry` Optional