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

ParameterTypeInRequiredDescription
qstringQuery (GET)No*Search term matched against merchant names and aliases (e.g. doordash, starbucks, amazon, trader joe's).
idstringQuery (GET)No*Exact canonical merchant slug (e.g. costco, delta, apple).
mccstringQuery (GET)No*Filter merchants classified under a specific 4-digit MCC (e.g. 5812, 5411).
qstring or arrayBody (POST)No*Search term or array of merchant queries for batch lookup.
idstring or arrayBody (POST)No*Exact merchant slug or array of slugs.

* At least one parameter (q, id, or mcc) must be provided.

Request Headers

HeaderValueDescription
Acceptapplication/jsonExpected response content type.
Content-Typeapplication/jsonRequired for POST requests.

Point-of-Sale Network Rules & Co-Brand Detection

The merchant engine automatically handles payment network acceptance constraints and co-branded partnerships:

  1. 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.
  2. 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: true and the specific partnership match reason.

Response Schema

FieldTypeDescription
statusstringRequest status ("success" or "error").
dataobject or arraySingle merchant record or array of matched records.
data.idstringCanonical merchant identifier slug.
data.namestringOfficial merchant name.
data.tickerstring or nullPublic equity ticker symbol (e.g. DASH, COST, DAL).
data.exchangestring or nullStock exchange (e.g. NASDAQ, NYSE).
data.categorystringHigh-level business category.
data.primary_mccstringPrimary 4-digit ISO 18245 MCC.
data.primary_mcc_titlestringIndustry description of primary MCC.
data.secondary_mccsarrayAdditional MCCs used by the merchant across different POS terminals.
data.documentation_urlstringCanonical documentation URL on AxeTip.
data.optimal_cardobjectThe highest-yielding credit card for this merchant.
data.optimal_card.idstringCard slug.
data.optimal_card.namestringCard product name.
data.optimal_card.reward_yieldRewardYieldValue object containing multiplier, units, and basis points.
data.optimal_card.is_co_brandbooleanWhether 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 CodeDescription
200 OKRequest succeeded. Matching merchant records returned.
400 Bad RequestMissing search query or slug parameter.
404 Not FoundNo matching merchant resolved for query.
429 Too Many RequestsRate limit exceeded (60 requests/minute).