The /api/merchant endpoint resolves raw merchant names, transaction strings, and brand aliases to canonical merchant records across 2,417 tracked merchants and 4,939 inverted alias patterns. It returns primary and secondary ISO 18245 MCC classifications, corporate ticker symbols, physical point-of-sale network acceptance rules, and co-branded reward pairings.
To test this endpoint interactively, use the API Explorer.
Request
GET https://www.axetip.com/api/merchant?q={query}
GET https://www.axetip.com/api/merchant?id={id}
GET https://www.axetip.com/api/merchant?mcc={mcc}
POST https://www.axetip.com/api/merchant
Parameters
| Parameter | Type | In | Required | Description |
|---|---|---|---|---|
q | string | Query (GET) | No* | Search term matched against merchant names and aliases (e.g. doordash, starbucks, amazon, trader joe's). |
id | string | Query (GET) | No* | Exact canonical merchant slug (e.g. costco, delta, apple). |
mcc | string | Query (GET) | No* | Filter merchants classified under a specific 4-digit MCC (e.g. 5812, 5411). |
q | string or array | Body (POST) | No* | Search term or array of merchant queries for batch lookup. |
id | string or array | Body (POST) | No* | Exact merchant slug or array of slugs. |
* At least one parameter (q, id, or mcc) must be provided.
Request Headers
| Header | Value | Description |
|---|---|---|
Accept | application/json | Expected response content type. |
Content-Type | application/json | Required for POST requests. |
Point-of-Sale Network Rules & Co-Brand Detection
The merchant engine automatically handles payment network acceptance constraints and co-branded partnerships:
- Physical Register Acceptance Quirks: For merchants with network exclusivity (e.g., Costco Wholesale accepting only Visa credit cards at warehouse registers), the response includes explicit warning metadata detailing accepted vs. rejected networks.
- Co-Brand Priority Matching: When a merchant maintains an active co-branded card partnership (e.g., DoorDash & Chase DoorDash Rewards Mastercard, Costco & Citi Costco Anywhere Visa, Delta & Amex Delta SkyMiles), the co-branded card is identified with
is_co_brand: trueand the specific partnership match reason.
Response Schema
| Field | Type | Description |
|---|---|---|
status | string | Request status ("success" or "error"). |
data | object or array | Single merchant record or array of matched records. |
data.id | string | Canonical merchant identifier slug. |
data.name | string | Official merchant name. |
data.ticker | string or null | Public equity ticker symbol (e.g. DASH, COST, DAL). |
data.exchange | string or null | Stock exchange (e.g. NASDAQ, NYSE). |
data.category | string | High-level business category. |
data.primary_mcc | string | Primary 4-digit ISO 18245 MCC. |
data.primary_mcc_title | string | Industry description of primary MCC. |
data.secondary_mccs | array | Additional MCCs used by the merchant across different POS terminals. |
data.documentation_url | string | Canonical documentation URL on AxeTip. |
data.optimal_card | object | The highest-yielding credit card for this merchant. |
data.optimal_card.id | string | Card slug. |
data.optimal_card.name | string | Card product name. |
data.optimal_card.reward_yield | RewardYield | Value object containing multiplier, units, and basis points. |
data.optimal_card.is_co_brand | boolean | Whether the recommendation is an official co-branded partnership card. |
Example Responses
1. Co-Brand Match (GET /api/merchant?q=doordash)
{
"status": "success",
"data": {
"id": "doordash",
"name": "DoorDash",
"ticker": "DASH",
"exchange": "NASDAQ",
"industry": "Food Delivery / Logistics",
"category": "Dining",
"primary_mcc": "5812",
"primary_mcc_title": "Eating Places And Restaurants",
"secondary_mccs": ["5814"],
"documentation_url": "https://www.axetip.com/merchant/doordash/",
"optimal_card": {
"id": "doordash-rewards-mastercard",
"name": "DoorDash Rewards Mastercard",
"issuer": "Chase",
"annual_fee": {
"value": 0.0,
"cents": 0,
"formatted": "$0.00",
"currency": "USD"
},
"reward_yield": {
"value": 4.0,
"unit": "%",
"formatted": "4.0%",
"basis_points": 400
},
"canonical_url": "https://www.axetip.com/card/doordash-rewards-mastercard/",
"match_reason": "Co-brand partnership match",
"is_co_brand": true
}
}
}
2. Exact Slug Lookup (GET /api/merchant?id=costco)
Returns Costco Wholesale record with primary MCC 5300 (Wholesale Clubs) and top co-brand card (Costco Anywhere Visa® Card by Citi).
3. Batch POST Lookup
POST https://www.axetip.com/api/merchant
Content-Type: application/json
{
"q": ["uber", "starbucks", "delta"]
}
Code Samples
cURL
curl -s "https://www.axetip.com/api/merchant?q=doordash"
TypeScript / Node.js
interface MerchantRecord {
id: string;
name: string;
primary_mcc: string;
optimal_card: {
name: string;
annual_fee: { formatted: string };
reward_yield: { formatted: string };
match_reason: string;
} | null;
}
const res = await fetch("https://www.axetip.com/api/merchant?q=doordash");
const data = await res.json();
const m: MerchantRecord = data.data;
console.log(`Merchant: ${m.name} (MCC ${m.primary_mcc})`);
if (m.optimal_card) {
console.log(` Top Card: ${m.optimal_card.name} (${m.optimal_card.reward_yield.formatted}) - ${m.optimal_card.match_reason}`);
}
Python
import httpx
url = "https://www.axetip.com/api/merchant"
params = {"q": "doordash"}
response = httpx.get(url, params=params, timeout=10.0)
m = response.json()["data"]
print(f"Merchant: {m['name']} [MCC {m['primary_mcc']}]")
if m.get("optimal_card"):
opt = m["optimal_card"]
print(f" Top Card: {opt['name']} ({opt['reward_yield']['formatted']}) - {opt['match_reason']}")
Go
package main
import (
"encoding/json"
"fmt"
"io"
"net/http"
)
type MerchantResponse struct {
Data struct {
Name string `json:"name"`
PrimaryMCC string `json:"primary_mcc"`
OptimalCard *struct {
Name string `json:"name"`
RewardYield struct {
Formatted string `json:"formatted"`
} `json:"reward_yield"`
MatchReason string `json:"match_reason"`
} `json:"optimal_card"`
} `json:"data"`
}
func main() {
resp, _ := http.Get("https://www.axetip.com/api/merchant?q=doordash")
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
var res MerchantResponse
json.Unmarshal(body, &res)
m := res.Data
fmt.Printf("Merchant: %s (MCC %s)\n", m.Name, m.PrimaryMCC)
if m.OptimalCard != nil {
fmt.Printf(" Optimal Card: %s (%s via %s)\n",
m.OptimalCard.Name, m.OptimalCard.RewardYield.Formatted, m.OptimalCard.MatchReason)
}
}
Status Codes
| Status Code | Description |
|---|---|
200 OK | Request succeeded. Matching merchant records returned. |
400 Bad Request | Missing search query or slug parameter. |
404 Not Found | No matching merchant resolved for query. |
429 Too Many Requests | Rate limit exceeded (60 requests/minute). |