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
Program-scoped triggers: Register different trigger rules per program — for example, an issuer with both corporate and consumer cards can register distinct merchant action triggers for each program without duplicating them across every user or card

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 four 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
Program	`/programs/{programId}/merchant-action-triggers`	All enrichment requests where `programId` matches this program	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 with a programId, userId, and cardId will check:

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

Multiple matches from different scopes can be returned in a single enrichment 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.

Registering merchant action triggers

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

PUT replaces your entire trigger list. Every PUT request overwrites all previously registered triggers at that scope. If you have 50,000 registered merchants and need to add or remove a handful, use the PATCH endpoint instead — sending the full list via PUT to change a few entries is inefficient and unnecessarily slow.See the API reference for PATCH endpoint details.

Two matching modes for merchant action triggers:

Location-level: (default) Applies triggers to a specific physical location (e.g. one specific Costco location)
Corporation-level: Applies triggers to a whole brand (e.g. Costco in general)

Example: Register Merchant Action Triggers at the Account Scope

The example below registers triggers at the account scope. To register at other scopes, replace the URL path accordingly — for example, use /programs/{programId}/merchant-action-triggers for program scope.See the API reference for full endpoint details.

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": "trigger-1",
        "merchantName": "Starbucks",
        "website": "https://www.starbucks.com",
        "level": "corporation",
        "action": {
          "type": "REWARD",
          "rewardPercent": 5,
          "offerId": "summer-2024-promo"
        }
      },
      {
        "id": "trigger-2",
        "merchantName": "Target",
        "address": "1000 Nicollet Mall",
        "city": "Minneapolis",
        "region": "MN",
        "country": "USA",
        "postalCode": "55403",
        "level": "location",
        "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

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 and Program Scope)

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

Per-request limits: User-scope and card-scope registrations are limited to 100 merchant action 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 or program-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 or program-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. The version number is incremented, not reset.

Example: Clear an Account-Scoped Trigger

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`, `program`, `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": "trigger-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

Trigger IDs must be unique within each scope. A scope is defined by the URL path you register against (account, program, user, or card level).

Within a single request: All trigger IDs must be unique. Duplicate IDs in the same request will return a 400 error.
Across requests in the same scope: Submitting a trigger with an ID that already exists in that scope will replace the previous registration (upsert). This applies to both PUT (full replacement) and PATCH add operations.
Across different scopes: The same trigger ID can be used independently in different scopes. For example, "starbucks-reward" can exist in both a user-level and a program-level scope without conflict.

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 program scope for triggers scoped to a specific program (e.g., a subset of customers or product line)
Use user scope for user-specific preferences
Use card scope for card-specific rules (e.g., category-specific rewards cards)
Triggers cascade downward — for example, an account-level trigger will match transactions for all programs, users, and cards. A program-level trigger will match all users and cards that send enrichments with that programId, but won’t affect other programs

Choosing PUT vs. PATCH

Use PUT when replacing your full set of triggers (e.g., initial setup or a periodic full sync)
Use PATCH when adding or removing a small number of merchants relative to your total trigger list
A PATCH add with 10 merchants against a list of 50,000 only processes those 10 — a PUT with the same intent would reprocess all 50,000

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

What is a program?

Registering merchant action triggers

Example: Register Merchant Action Triggers at the Account Scope

Response

Checking Registration Status

Status Values

Example: Check Status

Batch Registrations (Account and Program Scope)

Example: Polling for Completion

Clearing Triggers

Example: Clear an Account-Scoped Trigger

Receiving Triggered Actions

Triggered Action Response Fields

Example: Enrichment Response with Triggered Actions

Best Practices

Unique Trigger IDs

Action Structure

Scope Selection

Choosing PUT vs. PATCH

Error Handling

Welcome

Enrichment Guides

Tooling Guides

More

​Overview

​Quick Start

​Registration Scopes

​What is a program?

​Registering merchant action triggers

​Example: Register Merchant Action Triggers at the Account Scope

​Response

​Checking Registration Status

​Status Values

​Example: Check Status

​Batch Registrations (Account and Program Scope)

​Example: Polling for Completion

​Clearing Triggers

​Example: Clear an Account-Scoped Trigger

​Receiving Triggered Actions

​Triggered Action Response Fields

​Example: Enrichment Response with Triggered Actions

​Best Practices

​Unique Trigger IDs

​Action Structure

​Scope Selection

​Choosing PUT vs. PATCH

​Error Handling

Overview

Quick Start

Registration Scopes

What is a program?

Registering merchant action triggers

Example: Register Merchant Action Triggers at the Account Scope

Response

Checking Registration Status

Status Values

Example: Check Status

Batch Registrations (Account and Program Scope)

Example: Polling for Completion

Clearing Triggers

Example: Clear an Account-Scoped Trigger

Receiving Triggered Actions

Triggered Action Response Fields

Example: Enrichment Response with Triggered Actions

Best Practices

Unique Trigger IDs

Action Structure

Scope Selection

Choosing PUT vs. PATCH

Error Handling