> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spade.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Action triggers guide

> Register rules that trigger custom actions when transactions match your criteria

## 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:

<CardGroup cols={2}>
  <Card title="Merchant action triggers" icon="store" href="/reference/merchant-action-triggers-guide">
    Trigger actions when transactions match specific merchants. Supports location-level and corporation-level matching with up to 100,000 triggers per scope.
  </Card>

  <Card title="Category action triggers" icon="tags" href="/reference/category-action-triggers-guide">
    Trigger actions when transactions match Spade categories such as Travel, Gambling, or Groceries. Up to 300 triggers per scope, processed synchronously.
  </Card>
</CardGroup>

## Shared concepts

### Scope hierarchy

Both trigger types support four registration scopes. Higher scopes cascade down to lower scopes:

| Scope       | Applies to                                         |
| ----------- | -------------------------------------------------- |
| **Account** | All transactions across your account               |
| **Program** | All transactions where `programId` matches         |
| **User**    | All transactions for all cards belonging to a user |
| **Card**    | Only 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).

<Note>
  `programId`, `userId`, and `cardId` each have a maximum length of 512 characters.
</Note>

### Action types

The `action` object on each trigger is your custom JSON payload. The `type` field supports reserved values with special behavior:

| Type            | Behavior                                                                                      |
| --------------- | --------------------------------------------------------------------------------------------- |
| `BLOCK`         | Adds `authRecommendation: "BLOCK"` to the response                                            |
| `ALLOW_ONLY`    | Adds `authRecommendation: "ALLOW"` when matched; `"BLOCK"` when unmatched (inverse semantics) |
| `REWARD`        | Passed through as-is                                                                          |
| Any other value | Passed 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.

```json theme={null}
{
  "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.