> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.thepennyinc.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.thepennyinc.com/_mcp/server.

# Velocity Rules

Use `velocity` for a cumulative budget, such as no more than five transactions a day or \$2,000 in a week. Penny evaluates every configured window against the transaction's base amount, which is always USD. Configure `velocity_controls` under `USD`; entries under other currency codes never match a transaction.

**`Velocity rule config`**

```json title="Velocity rule config"
{
  "rule_type": "velocity",
  "applicable_transaction_authorizations": ["debit"],
  "applicable_card_issuance_modes": ["managed"],
  "configuration": {
    "velocity_controls": {
      "USD": {
        "day": { "usage_limit": 5 },
        "week": { "amount_limit": "2000.00" }
      }
    }
  }
}
```

Available windows are `hour`, `day`, `week`, `month`, `quarter`, `year`, and `lifetime`. Windows are calendar periods aligned to UTC, not rolling periods: `hour` resets at the top of each UTC hour, `day` resets at 00:00 UTC, `week` starts on Monday at 00:00 UTC, `month`, `quarter`, and `year` start on the first day of the period, and `lifetime` never resets. Each window must set `usage_limit`, `amount_limit`, or both. Usage counts each authorization as one; the amount check uses its base amount. Approved transactions update the counters.

The counters belong to the rule, so every object assigned the same spend control draws from one shared budget. To give each card its own budget, assign each card its own spend control. Responses return each window's current `usage` (`count`, `count_limit`) and `balance` (`available_balance`, `amount_limit`) with its `last_reset_time`.

Choose a [Transaction Amount Rule](/spend-controls/transaction-amount-rules) to cap a single purchase. Use velocity for a shared running budget. See [Setting Spend Controls](/spend-controls/setting-spend-controls) for creation and assignment.