Skip to main content
Rewards management dashboard powered by Spade

​
Overview

Managing a traditional merchant-based rewards program is hard. Attributing transactions to merchants using MIDs and pattern matching is fragile, expensive to maintain, and slow to update. Spade’s action triggers enable accurate rewards attribution by using ground truth enrichment—not guesswork.
  • Powered by Spade’s merchant database covering >99.9% of merchants in the US and Canada
  • Supports all forms of rewards — cash back, points, miles, and more
  • No more MIDs — match merchants by true identity, not fragile merchant IDs
  • No more regex — stop pattern-matching raw transaction strings
  • Responsive — set up rewards in minutes, not months

​
How it works

Merchant-based rewards flow: search, select, register, reward
  1. Search — Query Spade’s merchant database for autocomplete results
  2. Select — Pick one or more merchants and assign a reward value
  3. Register — Send selected merchants to Spade as REWARD action triggers
  4. Reward — Spade returns reward information with each enrichment

​
Step 1: Search Spade’s merchant database

Use GET /corporations to power a merchant autocomplete widget. The endpoint returns the merchant name, logo, and website for each match. 
{
  "corporations": [
    {
      "name": "Starbucks",
      "logo": "https://static.v2.spadeapi.com/logos/.../light.png",
      "website": "starbucks.com"
    },
    {
      "name": "Starlink",
      "logo": "https://static.v2.spadeapi.com/logos/.../light.png",
      "website": "starlink.com"
    },
    ...
  ]
}
Autocomplete UI powered by GET /corporations

​
Step 2: Select merchants

Select one or more merchants from the search results and assign a reward value (e.g., 3% cash back). The name and website from Step 1 are all you need for the next step.

​
Step 3: Register merchants with Spade

Send the selected merchants to Spade using the action triggers endpoint. Set each merchant’s action type to REWARD along with details about the reward. You decide what you need. 
PUT /merchant-action-triggers

{
  "merchantTriggers": [
    {
      "id": "trigger-1",
      "merchantName": "Starbucks",
      "website": "https://www.starbucks.com",
      "action": {
        "type": "REWARD",
        "rewardPercent": "5",
        "offerId": "coffee-cashback-q1"
      }
    },
    {
      "id": "trigger-2",
      "merchantName": "Whole Foods",
      "website": "https://www.wholefoodsmarket.com",
      "action": {
        "type": "REWARD",
        "rewardPercent": "5",
        "offerId": "grocery-cashback-q1"
      }
    }
  ]
}
You can also register triggers at the (card) program, user, or card level for more targeted rewards. For full integration details — including registration scopes, status polling, and batch processing — see the Realtime action triggers guide.

​
Step 4: Receive reward information in enrichments

When a transaction is enriched, Spade checks it against your registered triggers. If the merchant matches, the enrichment response includes an actions array with your reward data.

Matched merchant — reward returned

Transaction at a registered merchant (e.g., Starbucks):
{
  "actions": [
    {
      "id": "trigger-1",
      "type": "merchant_trigger",
      "action": {
        "type": "REWARD",
        "rewardPercent": "5",
        "offerId": "coffee-cashback-q1"
      },
      "scope": "account"
    }
  ]
}

Unmatched merchant — no action

Transaction at a non-registered merchant (e.g., Amazon):
{
  "actions": []
}
Your system reads the reward data and applies the appropriate reward — Spade handles the merchant matching, you handle the reward logic.

​
Use cases

  • Card-linked offers — Power merchant-specific cashback and points multipliers
  • Promotional campaigns — Run time-limited merchant reward promotions and swap merchants in minutes