Our spend rule engine is immensely powerful and allows for an incalculable amount of unique rule combinations. Typically, customers use spend rules for actions like blocking transactions at specific merchants or limiting cards to only work at certain merchants. We also have velocity rules, where you're able to configure how much a card can spend in certain time intervals, which is particularly helpful for our commercial expense ('On Demand') card products.

First we'll talk through the general principles of our spend rule engine.

General Principles

ApplyTo levels

Spend rules can be applied at 3 different levels, decided by the ApplyTo field on the SpendRule:

cards
program
business

If ApplyTo is set to cards, the rule can be added directly to specific selected cards - if a cards rule has not been added to any specific cards, then the rule is effectively inactive and won't affect any card behavior. You can apply differentcards rules to different cards, and the rules will only affect the cards its applied to, so this level is perfect for more one-off restriction cases. If ApplyTo is set to program, then all cards within the given program will be affected by the rule. If ApplyTo is set to business, then all cards within all of the programs of your business will be affected by the rule - think of it as a globally active rule.

Stacking

Spend rules can be stacked, and so you can have multiple non-conflicting rules active at the same level.
For example: say you have two 'cards' level rules - one that blocks merchants with the MCC 'FAST_FOOD_RESTAURANTS' and different one that blocks merchants with the MCC 'FLORISTS'. You could apply both of those rules to the same card, and both, separate rules will be active on the card at the same time. In this example case, it'd mean that the specific cards these 2 rules have been applied to will decline at all fast food restaurants and florists - valentines day plans ruined 😢

Rules can also naturally be stacked at different levels: for example, you might have 1 cards level rule that blocks the MCC 'FASTFOOD_RESTAURANTS', 1_program level rule that blocks the MCC 'FLORISTS', and then one business level rule that blocks the MCC 'VETERINARYSERVICES'. If the_cards level rule is applied to a specific card within the given program, then all 3 rules (one from each level) are active on that card - the card will decline at all fast food restaurants, all florists and all veterinary clinics.

The principle of stacking is universal, so even merchantallow and velocity rules rules stack. As examples: if you have a_cards level merchantallow rule that only allows FLORISTS, and a_business level merchantallow rule that only allows VETERINARY_SERVICES, then for that card, it'd only be allowed at FLORISTS and VETERINARY_SERVICES. If you wanted the card to only work at Florists despite the_business level rule, see the Greenlighting and Redlighting section on how to use overrides. Similarly, with velocity rules, if you had one cards level rule that set the daily transaction limit to $500, and a program level rule that set the monthly transaction limit to $1000, then they would stack and so for that card, it has a daily limit of $500 and a monthly limit of $1000.

Conflicts can occur now that we allow stacking, for example: what happens when you have 1 cards rule that only allows a card to work at an ATM, and one cards rule that blocks ATMs, and you try to apply them both to the same card? Our APIs will automatically prevent conflicts from happening and will error if you try to add two conflicting rule at the same level, like in this case.

This being said, we do allow conflicts across different levels - intentionally.
For example: Imagine you have 1 rule that only allows a card to work at an ATM at the cards level, and you have another rule that blocks ATMs at the business level. Well, this is actually fine, because our spend rule engine has a priority order built into it, explained below.

Rule Prioritization

Not all rules are evaluated as equal. Rules are evaluated in a bottom-up format, where the lowest level rules take priority. This means that with our rule levels, cards > program > business. In the above example, where we have two conflicting rules at different levels, following this logic, the lowest level rule would win, so the cards rule will be the one our engine evaluates in this case. This means that for the specific cards that the cards rule is applied to, the card will work at an ATM, even though there is a business level rule that blocks ATMs. Another example of a conflict is if you have a cards level velocity rule that sets the daily limit for transactions to $100, and a program level velocity rule that sets the daily limit for transactions to $200 - the cards limit would win and so the daily limit for that card would be $100.

You can leverage this prioritization order to handle some tricky cases.
Here's a common example we see with customers, and how they can use our rule prioritization to handle this:
They are running a food assistance program where transactions are only allowed to be spent on groceries, so at the program level, they create a rule that only allows transactions at the MCCs: 'GROCERY_STORES_SUPERMARKETS' and 'DEPARTMENT_STORES' - all transactions at any other MCCs will be declined for all cards in the program.

However, now the customer wants to make some exceptions. For just a few cards in the program - lets say 5, they also want to help pay for people's gas, but with the program level restrictions, all transactions at gas stations will decline. To handle this, customer just needs to create a cards level spend rule that only allows transactions at the MCCs: 'GROCERY_STORES_SUPERMARKETS', 'DEPARTMENT_STORES' and 'AUTOMATED_FUEL_DISPENSERS', and then they add this new rule to the 5 'gas assistance' cards. So now they've solved their issue. For all cards in the program, the cards work only at at grocery stores + department stores, except for the 5 cards, where the cards also work at fuel dispensers.

You can leverage our rule prioritization to accomplish the opposite effect of the above example too: what if you wanted to make the program level more restrictive than the business level?
For example: across all of your programs, transactions are allowed only for food assistance, so you have a business level rule that only allows transactions at the MCCs: 'GROCERYSTORES_SUPERMARKETS' and 'DEPARTMENT_STORES'. However, for one specific program, you don't want to allow department stores, you want the cards to only work at grocery stores. This is easy, just add a_program level rule that only allows transactions at the MCC: 'GROCERY_STORES_SUPERMARKETS'. Then, for all programs within your business, transactions will only work at grocery stores and department stores, except for the 1 specific program, where cards only work at grocery stores.

There is one additional layer of prioritization: Greenlighting and Redlighting, which allows you to make override decisions that automatically approve or decline transactions under conditions no matter what the other rules affecting the card are saying. We recommend visiting that section once you've read the rest of our spend rule documentation.

Rule Types

In general, there are two types of spend rule:

Merchant Spend Rules
Velocity Spend Rules

We'll break down how to use each type of rule in their own pages.