Realtime action triggers guide

Overview

Spade’s realtime action triggers allow you to register rules that trigger custom actions when transactions match your criteria. When a transaction matches one of your registered triggers, the enrichment response includes your custom action data. Common use cases:

Merchant rewards: Identify transactions at specific merchants to trigger reward multipliers
Transaction flagging: Flag transactions for review based on merchant or category

Coming soon: Category-based triggers will allow you to trigger actions based on Spade categories (e.g., “Crypto”, “Gambling”).

Quick Start

Ensure the actions feature is enabled - Contact your Spade representative if you need access
Register your triggers using the PUT endpoint with your trigger configuration
Wait for registration to complete - Check the GET endpoint until status is succeeded
Enrich transactions - Matched triggers appear in the actions field

Registration Scopes

Action triggers can be registered at three different scopes, with higher scopes cascading down to lower scopes:

Scope	Endpoint	Applies To	Limit
Account	`/merchant-action-triggers`	All transactions for all users in your account	100,000 triggers per request
User	`/users/{userId}/merchant-action-triggers`	All transactions for all cards belonging to that user	100 triggers per request
Card	`/users/{userId}/cards/{cardId}/merchant-action-triggers`	Only transactions for that specific card	100 triggers per request

Scope inheritance: When a transaction is enriched, Spade checks for matching triggers across all applicable scopes. For example, a transaction on a specific card will check:

Card-level triggers (for that card)
User-level triggers (for that user)
Account-level triggers (for your account)

Multiple matches from different scopes can be returned in a single enrichment response.

Registering Merchant Triggers

Use the PUT endpoint to register merchant triggers for action matching.

Two matching modes for merchant triggers:

Location-based: Provide merchantName + location fields (address, city, etc.)
Website-based: Provide merchantName + website when location data is unavailable

Example: Register Merchant Triggers

curl --request PUT \
  --url https://east.api.spade.com/merchant-action-triggers \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --data '{
    "merchantTriggers": [
      {
        "id": "merchant-1",
        "merchantName": "Starbucks",
        "website": "https://www.starbucks.com",
        "action": {
          "type": "REWARD",
          "rewardPercent": 5,
          "offerId": "summer-2024-promo"
        }
      },
      {
        "id": "merchant-002",
        "merchantName": "Target",
        "address": "1000 Nicollet Mall",
        "city": "Minneapolis",
        "region": "MN",
        "country": "USA",
        "postalCode": "55403",
        "action": {
          "type": "REWARD",
          "rewardPercent": 3,
          "offerId": "target-cashback"
        }
      }
    ]
  }'

Response

{
  "status": "succeeded",
  "version": 1
}

Checking Registration Status

Use the GET endpoint to check the status of your action trigger registration.

Status Values

Status	Description
`pending`	Registration received, processing not yet started
`running`	Registration is being processed (for batch registrations)
`succeeded`	Registration complete, triggers are now active
`failed`	Registration failed, check your request and retry
`deleted`	Trigger scope has been cleared via DELETE

Important: Triggers are only applied to enrichment responses when the status is succeeded. Transactions enriched while status is pending or running will NOT include the new triggers.

Example: Check Status

curl --request GET \
  --url https://east.api.spade.com/merchant-action-triggers \
  --header 'X-Api-Key: YOUR_API_KEY'

Batch Registrations (Account Scope Only)

Account-scope registrations with more than 100 merchant triggers are processed asynchronously as a batch job.

Per-request limits: User-scope and card-scope registrations are limited to 100 merchant triggers per request. Requests exceeding this limit will receive a 400 error. This does not limit the total number of users or cards you can register triggers for — you can make as many requests as needed across different scopes.

Batch processing workflow:

Submit your account-scope registration via PUT - returns immediately with status: "pending"
Poll the GET endpoint to monitor progress
Status changes from pending → running → succeeded (or failed)
Once succeeded, triggers are active for new enrichment requests

For large account-scope trigger lists, we recommend implementing a polling loop with exponential backoff. Most batch registrations complete within a few minutes.

Example: Polling for Completion

python

import requests
import time

def wait_for_trigger_success(api_key, max_attempts=30, base_delay=2):
    """Poll until action trigger status is succeeded or failed."""
    for attempt in range(max_attempts):
        response = requests.get(
            "https://east.api.spade.com/merchant-action-triggers",
            headers={"X-Api-Key": api_key}
        )

        data = response.json()
        status = data.get("status")

        if status == "succeeded":
            print(f"Registration complete! Version: {data.get('version')}")
            return True
        elif status == "failed":
            print("Registration failed. Please check your request and retry.")
            return False
        else:
            # Exponential backoff
            delay = base_delay * (2 ** min(attempt, 5))
            print(f"Status: {status}. Checking again in {delay}s...")
            time.sleep(delay)

    print("Timed out waiting for registration to complete")
    return False

Clearing Triggers

Use the DELETE endpoint to clear all triggers at a given scope.

DELETE creates a new version with an empty trigger list and sets the status to deleted. The version number is incremented, not reset.

Example: Clear Triggers

curl --request DELETE \
  --url https://east.api.spade.com/merchant-action-triggers \
  --header 'X-Api-Key: YOUR_API_KEY'

Receiving Triggered Actions

When a transaction matches one or more of your registered triggers, the enrichment response includes the actions field.

Triggered Action Response Fields

Field	Description
`id`	Your trigger ID (as provided during registration)
`type`	The type of trigger that matched (e.g., `merchant_trigger`)
`action`	Your custom action data from registration
`scope`	The scope at which this trigger was registered (`account`, `user`, or `card`)

Example: Enrichment Response with Triggered Actions

{
  "enrichmentId": "d1f7490c-719e-4c75-8bfa-535c8a32b936",
  "transactionInfo": {
    "type": "spending",
    "display": {
      "name": "Starbucks",
      "categoryName": "Coffee Shop"
    }
  },
  "counterparty": [
    {
      "id": "abc123-def456",
      "name": "Starbucks",
      "matchScore": 95.2
    }
  ],
  "actions": [
    {
      "id": "merchant-1",
      "type": "merchant_trigger",
      "action": {
        "type": "REWARD",
        "rewardPercent": 5,
        "offerId": "summer-2024-promo"
      },
      "scope": "account"
    }
  ]
}

The actions field is null when no triggers match, and is omitted entirely if your account does not have the actions feature enabled.

Best Practices

Unique Trigger IDs

Always use unique IDs for each trigger. If duplicate IDs are submitted in a single request, the registration will fail.

Action Structure

Design your action schema upfront. This is your custom data - use it to store reward amounts, offer IDs, or any information you need when processing matched transactions. The type field is required. There is currently one reserved keyword:

REWARD - For reward-based actions (e.g., cashback, points multipliers)

Spade will execute pre-defined behavior on any reserved type. You may also use custom type values for your own categorization needs.

Scope Selection

Use account scope for triggers that apply to all users (e.g., card-linked offer partners)
Use user scope for user-specific preferences
Use card scope for card-specific programs (e.g., category-specific rewards cards)
All higher scope triggers will apply to lower scopes

Error Handling

Implement retry logic for 5xx errors
Handle 409 Conflict by waiting for the in-progress registration to complete
Validate your trigger data before submission to avoid 400 errors

Welcome

Enrichment Guides

Tooling Guides

More

Realtime action triggers guide

Overview

Quick Start

Registration Scopes

Registering Merchant Triggers

Example: Register Merchant Triggers

Response

Checking Registration Status

Status Values

Example: Check Status

Batch Registrations (Account Scope Only)

Example: Polling for Completion

Clearing Triggers

Example: Clear Triggers

Receiving Triggered Actions

Triggered Action Response Fields

Example: Enrichment Response with Triggered Actions

Best Practices

Unique Trigger IDs

Action Structure

Scope Selection

Error Handling

Welcome

Enrichment Guides

Tooling Guides

More

​Overview

​Quick Start

​Registration Scopes

​Registering Merchant Triggers

​Example: Register Merchant Triggers

​Response

​Checking Registration Status

​Status Values

​Example: Check Status

​Batch Registrations (Account Scope Only)

​Example: Polling for Completion

​Clearing Triggers

​Example: Clear Triggers

​Receiving Triggered Actions

​Triggered Action Response Fields

​Example: Enrichment Response with Triggered Actions

​Best Practices

​Unique Trigger IDs

​Action Structure

​Scope Selection

​Error Handling

Overview

Quick Start

Registration Scopes

Registering Merchant Triggers

Example: Register Merchant Triggers

Response

Checking Registration Status

Status Values

Example: Check Status

Batch Registrations (Account Scope Only)

Example: Polling for Completion

Clearing Triggers

Example: Clear Triggers

Receiving Triggered Actions

Triggered Action Response Fields

Example: Enrichment Response with Triggered Actions

Best Practices

Unique Trigger IDs

Action Structure

Scope Selection

Error Handling