Time windows

Time window policies restrict payments by hour and day. Set an IANA timezone in the value of every policy rule. Without one, the rule is evaluated in UTC, not your local time. Wallet-level time windows use the agent-wallet link’s own timezone.

Configuration (API)

Create a complete TIME_WINDOW policy with its rules in one request:

curl -X POST https://conto.finance/api/policies \
  -H "Authorization: Bearer $CONTO_ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Business Hours",
    "policyType": "TIME_WINDOW",
    "priority": 50,
    "isActive": true,
    "rules": [
      {
        "ruleType": "TIME_WINDOW",
        "operator": "BETWEEN",
        "value": "{\"start\": \"09:00\", \"end\": \"17:00\", \"timezone\": \"America/New_York\"}",
        "action": "ALLOW"
      },
      {
        "ruleType": "DAY_OF_WEEK",
        "operator": "IN_LIST",
        "value": "{\"days\": [\"Mon\", \"Tue\", \"Wed\", \"Thu\", \"Fri\"], \"timezone\": \"America/New_York\"}",
        "action": "ALLOW"
      }
    ]
  }'

Rule types

TIME_WINDOW (hours)

Restrict transactions to specific hours of the day:

Property	Description
`ruleType`	`TIME_WINDOW`
`operator`	`BETWEEN` matches inside the window, including the end minute. `NOT_BETWEEN` matches outside it.
`value`	JSON string: `{"start": "HH:MM", "end": "HH:MM", "timezone": "Area/Location"}`
`action`	`ALLOW`, `DENY`, or `REQUIRE_APPROVAL`

09:00 to 17:00 matches through 17:00 and stops matching at 17:01. Wallet-level hours work differently: their end hour is excluded. See Wallet-level time windows.

DAY_OF_WEEK (days)

Restrict transactions to specific days of the week:

Property	Description
`ruleType`	`DAY_OF_WEEK`
`operator`	`IN_LIST` matches the listed days. `NOT_IN_LIST` matches every other day.
`value`	JSON string: `{"days": ["Mon", "Tue"], "timezone": "Area/Location"}`
`action`	`ALLOW`, `DENY`, or `REQUIRE_APPROVAL`

Valid day values: Mon, Tue, Wed, Thu, Fri, Sat, Sun

BLACKOUT_PERIOD

Block transactions during maintenance windows or holidays:

curl -X POST https://conto.finance/api/policies \
  -H "Authorization: Bearer $CONTO_ORG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maintenance Windows",
    "policyType": "BLACKOUT_PERIOD",
    "priority": 50,
    "isActive": true,
    "rules": [{
      "ruleType": "BLACKOUT_PERIOD",
      "operator": "BETWEEN",
      "value": "{\"timezone\": \"America/New_York\", \"windows\": [{\"start\": \"02:00\", \"end\": \"06:00\", \"reason\": \"Maintenance\", \"recurring\": true}]}",
      "action": "DENY"
    }]
  }'

For a date range such as a holiday, give each window full timestamps, for example {"windows":[{"start":"2026-12-24T00:00:00Z","end":"2026-12-26T23:59:59Z"}]} with operator BETWEEN and action DENY.

Wallet-level time windows

Time windows can also be set on the agent-wallet link. Send this body to POST /api/agents/{id}/wallets when linking, or the same fields without walletId to PATCH /api/agents/{id}/wallets/{walletId}:

{
  "walletId": "cmm5b2wal002n49h7ckrtb33r",
  "allowedHoursStart": 9,
  "allowedHoursEnd": 17,
  "allowedDays": ["Mon", "Tue", "Wed", "Thu", "Fri"],
  "timezone": "America/New_York"
}

allowedHoursStart, allowedHoursEnd, and allowedDays are evaluated in the link’s IANA timezone, which defaults to UTC. Invalid IANA names are rejected with a 400. Hours are whole numbers on a 24-hour clock, with allowedHoursStart inclusive and allowedHoursEnd exclusive: 9 to 18 allows 09:00 through 17:59 and blocks 18:00 onward. Midnight is hour 0, so 0 to 24 covers the full day, which is the default. This differs from a TIME_WINDOW rule, where the end minute is included.

Use cases

Business hours

Only allow transactions during working hours

{
  "allowedHoursStart": 9,
  "allowedHoursEnd": 18,
  "allowedDays": ["Mon", "Tue", "Wed", "Thu", "Fri"]
}

Extended hours

Allow transactions in extended support hours

{
  "allowedHoursStart": 7,
  "allowedHoursEnd": 22,
  "allowedDays": ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat"]
}

Weekends only

For agents that operate on weekends

{
  "allowedHoursStart": 0,
  "allowedHoursEnd": 24,
  "allowedDays": ["Sat", "Sun"]
}

Error response

When a transaction is blocked by time window:

{
  "status": "DENIED",
  "reasons": ["This payment is outside the permitted schedule."]
}

Best practices

Set the wallet timezone

Set the link’s timezone to your organization’s operating timezone (for example, America/New_York) instead of converting hours to UTC by hand. With the timezone set, allowedHoursStart and allowedHoursEnd read as local business hours, Conto applies daylight saving time, and allowedDays matches the local calendar day.

Require approval after hours

{
  "ruleType": "TIME_WINDOW",
  "operator": "NOT_BETWEEN",
  "value": "{\"start\": \"09:00\", \"end\": \"17:00\", \"timezone\": \"America/New_York\"}",
  "action": "REQUIRE_APPROVAL"
}

Every payment outside 09:00 to 17:00 New York time waits for review. Payments inside the window follow your other limits.

Get started

Integrate

Payments

Conto Commerce

Spending controls

Operate

Conto Pay

Time windows

Configuration (API)

Rule types

TIME_WINDOW (hours)

DAY_OF_WEEK (days)

BLACKOUT_PERIOD

Wallet-level time windows

Use cases

Business hours

Extended hours

Weekends only

Error response

Best practices

​Configuration (API)

​Rule types

​TIME_WINDOW (hours)

​DAY_OF_WEEK (days)

​BLACKOUT_PERIOD

​Wallet-level time windows

​Use cases

Business hours

Extended hours

Weekends only

​Error response

​Best practices

Configuration (API)

Rule types

TIME_WINDOW (hours)

DAY_OF_WEEK (days)

BLACKOUT_PERIOD

Wallet-level time windows

Use cases

Error response

Best practices