Velocity rules allow you to set your own limits on how much a card can spend in specified time intervals. You can use them to configure logic like setting a maximum daily limit for cards, or in more complex use cases, setting merchant-specific limits like only allowing $100 in spend per month at Grocery Stores.

To create a Velocity rule, create a Spend Rule with the type "velocity".

General Principles

Velocity Rule Cycles

For Velocity Spend Rules, the main thing you have to think about are cycles - these are the time intervals that the rules are set against. There are 5 velocity cycles, each with their own reset criteria:

all_time: This interval never resets - an all_time velocity rule means the card can never spend more than the associated VelocityValue.
monthly: This is based on calendar month, where the interval resets on the 1st day of the calendar month at 00:00:00 in Pacific Time.
weekly: This is based on the calendar week, where the interval resets every Monday at 00:00:00 in Pacific Time
daily: This is based on the calendar day, where the interval resets every morning at 00:00:00 in Pacific Time
hourly: This is based on rolling windows, where the interval starts exactly 60 minutes before the current time - unlike all other velocity rules, this is not based on calendar time, but is relative.
single_transaction: The interval resets for every new transaction, so this cycle is basically just setting a spend limit on each individual transaction.

Note our use of calendar months for counting cycle intervals instead of using time-elapsed windows: we've found that this is far easier to explain to cardholders, and is much more predictable.

Velocity Rule Types

The VelocityType field on the SpendRule and the Restriction controls how velocity spend rules are evaluated. Today, velocity spend rules support both "currency_amount" (where rule restrictions match based on the currency amount of a transaction within that cycle) and "authorization_count" (where rule restrictions match based on the number of unique authorization events within the cycle). If no velocity type is provided, it will default to "currency_amount".

Velocity Rule Restrictions

Restrictions on Velocity Spend Rules work similarly to how they do for Merchant Spend Rules, with the difference being the fields we leverage. With velocity spend rules, the fields of importance would be: velocityValue and velocityCycle.

For example, If you wanted to set a card's maximum daily spending limit to be $100, you would set velocityValue: "100", and velocityCycle: "daily".

Examples

Example 1: Let's assume you have a commercial expense program and you're setting your velocity limits.

We'll need to call CreateSpendRuleV1 with the following:

{
	"name": "Commercial Expense Velocity Limits",
	"description": "This rule sets the spend limits for our commercial expense program",
	"type": "velocity",
	"applyTo": "program",
  "programId": "33c315e1-b20f-4d3c-beb6-07ac661121f9", // substitute with real programId
	"restrictions": [
		{
		  "type": "velocity",
		  "velocityValue": "2500",
  		"velocityCycle": "monthly"
		},
		{
		  "type": "velocity",
		  "velocityValue": "1000",
  		"velocityCycle": "weekly"
		},
		{
		  "type": "velocity",
		  "velocityValue": "500",
  		"velocityCycle": "daily"
		},
		{
		  "type": "velocity",
		  "velocityValue": "50",
  		"velocityCycle": "single_transaction"
		}
	]
}

Example 2: Let's say you have a more interesting use case: you want to limit spend to no more than $500 a month at ATMs or florists (i.e. the combined total of spend at either of those merchants cannot exceed $500/m). That's possible too! Note that in this case, the card has no limits at everywhere else - if you wanted to ensure that the cards also only worked at ATMs and Florists, pair this with a separate merchant_allow rule!

{
	"name": "Monthly ATM limit",
	"description": "This card can't spend more than $500/m at an ATM OR florists",
	"type": "velocity",
	"applyTo": "business",
  "velocityCycle": "monthly",
  "velocityValue": "500",
	"restrictions": [
		{
		  "type": "merchant_category",
  		"value": "AUTOMATED_CASH_DISBURSE"
		},
    {
		  "type": "merchant_category",
  		"value": "FLORISTS"
		}
	]
}

Example 3: Let's say you want to limit velocity with different amounts at different merchants. This sets the monthly limit to $500 at most merchants, except ATMs for which the limit is $150, and Florists for which it is $200.

{
	"name": "Monthly Merchant Velocity Limits",
	"description": "This sets our spend limits at different merchants",
	"type": "velocity",
	"applyTo": "business",
	"restrictions": [
		{
		  "type": "merchant_category",
  		"value": "AUTOMATED_CASH_DISBURSE",
      "velocityCycle": "monthly",
  		"velocityValue": "150"
		},
    {
		  "type": "merchant_category",
  		"value": "FLORISTS",
      "velocityCycle": "monthly",
  		"velocityValue": "200"
		},
    {
      "velocityCycle": "monthly",
  		"velocityValue": "500"
		}
	]
}

Example 4: Let's say you want to limit the number of transactions that a card can make in 1 hour. This sets it so that a card can only do 2 successful transactions in a given 60 minute period.

{
	"name": "Monthly Merchant Velocity Limits",
	"description": "This sets our hourly transaction count limit",
	"type": "velocity",
	"applyTo": "business",
	"restrictions": [
        {
            "type": "velocity",
            "velocityValue": "2",
            "velocityCycle": "hourly",
            "velocityType": "authorization_count"
	    }
    ]
}