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.

{
  "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 to cap a single purchase. Use velocity for a shared running budget. See Setting Spend Controls for creation and assignment.