Skip to main content

​
Overview

Action triggers let you register rules that fire custom actions when enriched transactions match your criteria. When a match occurs, the enrichment response includes your custom action data — enabling real-time rewards, spending controls, and transaction routing without any post-processing. Spade supports two types of action triggers:

Merchant action triggers

Trigger actions when transactions match specific merchants. Supports location-level and corporation-level matching with up to 100,000 triggers per scope.

Category action triggers

Trigger actions when transactions match Spade categories such as Travel, Gambling, or Groceries. Up to 300 triggers per scope, processed synchronously.

​
Shared concepts

​
Scope hierarchy

Both trigger types support four registration scopes. Higher scopes cascade down to lower scopes:
ScopeApplies to
AccountAll transactions across your account
ProgramAll transactions where programId matches
UserAll transactions for all cards belonging to a user
CardOnly transactions for a specific card
When a transaction is enriched, Spade checks for matching triggers across all applicable scopes — card, user, program, then account. Multiple matches from different scopes can appear in a single response.

​
What is a program?

A program is a freeform identifier you define — it requires no upfront configuration. You supply a programId string on your enrichment requests to group transactions however makes sense for your business (e.g., by card product, customer, or business line).
programId, userId, and cardId each have a maximum length of 512 characters.

​
Action types

The action object on each trigger is your custom JSON payload. The type field supports reserved values with special behavior:
TypeBehavior
BLOCKAdds authRecommendation: "BLOCK" to the response
ALLOW_ONLYAdds authRecommendation: "ALLOW" when matched; "BLOCK" when unmatched (inverse semantics)
REWARDPassed through as-is
Any other valuePassed through as-is

​
Triggered actions in enrichment responses

Matched triggers appear in the actions array of the enrichment response. Each entry includes the trigger id, type, your custom action data, the scope it was registered at, and the source of the match. 
{
  "actions": [
    {
      "id": "trigger-1",
      "type": "merchant_trigger",
      "action": { "type": "REWARD", "rewardPercent": 5 },
      "scope": "account",
      "source": "counterparty"
    },
    {
      "id": "cat-trigger-1",
      "type": "category_trigger",
      "action": { "type": "REWARD", "rewardPercent": 3 },
      "scope": "account",
      "source": "counterparty",
      "categoryId": "020-001-000-000",
      "categoryName": "Travel"
    }
  ]
}
The actions field is null when no triggers match, and is omitted entirely if your account does not have the actions feature enabled.