> ## 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.
# Merchant-based rewards
> Use Spade to power merchant-based rewards programs
## 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
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.
```json theme={null}
{
"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"
},
...
]
}
```
## 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.
```json theme={null}
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 [Merchant action triggers guide](/reference/merchant-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.
Transaction at a registered merchant (e.g., Starbucks):
```json theme={null}
{
"actions": [
{
"id": "trigger-1",
"type": "merchant_trigger",
"action": {
"type": "REWARD",
"rewardPercent": "5",
"offerId": "coffee-cashback-q1"
},
"scope": "account"
}
]
}
```
Transaction at a non-registered merchant (e.g., Amazon):
```json theme={null}
{
"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