The /api/optimize endpoint routes transactions to the highest-yielding card in a user’s wallet. It checks merchant network acceptance rules (such as warehouse clubs that accept only Visa at registers), matches co-branded cards, enforces category spend caps, and calculates the incremental dollar return if an unheld card would outperform the user’s current cards.

It operates in two distinct modes:

  1. Single Transaction Routing (mode: "transaction"): Selects the optimal card for a specific purchase amount at a given merchant.
  2. Monthly Spend Basket Optimizer (mode: "basket"): Evaluates a household or corporate monthly spending profile across categories to compute net annual rewards and discover the single card that delivers the highest net annual return after deducting its annual fee.

To test this endpoint interactively, use the API Explorer.


Request

GET  https://www.axetip.com/api/optimize?merchant={merchant}&amount={amount}&held_cards={cards}
POST https://www.axetip.com/api/optimize

Parameters

ParameterTypeInRequiredDescription
modestringQuery / BodyNoOperational mode: transaction (default) or basket.
merchantstringQuery / BodyYes (transaction)Merchant name, alias, or slug (e.g. doordash, costco, delta).
amountnumberQuery / BodyYes (transaction)Transaction amount in USD (e.g. 45.00 or 250).
held_cardsstring or arrayQuery / BodyYesComma-separated query string (GET) or string array (POST) of cards in the user’s wallet.
monthly_spendobject or stringQuery / BodyYes (basket)Category spend map (e.g. {"dining": 800, "grocery": 600, "general": 1200}) or serialized string (dining:800,grocery:600).

Request Headers

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

Point-of-Sale Register Acceptance Quirks

Certain retailers enforce payment network restrictions at checkout. For example, Costco Wholesale physical warehouses accept only Visa credit cards at register terminals.

When a transaction query targets a restricted merchant:

  • Ineligible held cards (e.g. Mastercard, American Express) are flagged with eligible_for_pos: false and the specific ineligibility reason.
  • The router excludes non-accepted cards from the recommended swipe decision.
  • A structured alert is added to pos_quirks describing the constraint.

Response Schema

Transaction Mode Schema

FieldTypeDescription
statusstringRequest status ("success" or "error").
modestringOperational mode ("transaction").
routing_summarystringHuman-readable transaction routing decision.
transactionobjectResolved transaction context (merchant, amount, MCC).
pos_quirksarrayPhysical checkout register acceptance rules and alerts.
optimal_held_cardobjectThe highest-earning eligible card currently in the wallet.
held_card_rankingarrayRanked list of all submitted held cards with eligibility status and expected return.
unheld_card_opportunityobject or nullThe best market card not in the user’s wallet and its marginal return.

Basket Mode Schema

FieldTypeDescription
statusstringRequest status ("success" or "error").
modestringOperational mode ("basket").
summarystringPortfolio performance summary.
annual_metricsobjectGross annual spend, gross annual rewards return, and blended yield across wallet.
optimal_card_opportunityobjectUnheld card delivering the highest net annual return after annual fees.

Example Responses

1. Single Transaction Routing with POS Quirk (GET /api/optimize)

GET https://www.axetip.com/api/optimize?merchant=costco&amount=250&held_cards=amex-gold,citi-double-cash,chase-freedom-unlimited
{
  "source": "AxeTip Autonomous Routing Engine",
  "status": "success",
  "mode": "transaction",
  "routing_summary": "Recommended swipe for $250.00 at Costco Wholesale: Chase Freedom Unlimited® (1.5% yield). Warning: Costco physical warehouses accept Visa cards only at point of sale.",
  "transaction": {
    "merchant": "Costco Wholesale",
    "amount": {
      "value": 250.0,
      "cents": 25000,
      "formatted": "$250.00",
      "currency": "USD"
    },
    "primary_mcc": "5300",
    "primary_mcc_title": "Wholesale Clubs"
  },
  "pos_quirks": [
    {
      "type": "network_acceptance",
      "severity": "warning",
      "accepted_networks": ["Visa"],
      "rejected_networks": ["Mastercard", "American Express", "Discover"],
      "message": "Physical warehouse registers accept Visa credit cards only. Non-Visa cards were filtered from point-of-sale routing."
    }
  ],
  "optimal_held_card": {
    "id": "chase-freedom-unlimited",
    "name": "Chase Freedom Unlimited®",
    "network": "Visa",
    "annual_fee": { "value": 0.0, "cents": 0, "formatted": "$0.00", "currency": "USD" },
    "reward_yield": { "value": 1.5, "unit": "%", "formatted": "1.5%", "basis_points": 150 },
    "expected_return": { "value": 3.75, "cents": 375, "formatted": "$3.75", "currency": "USD" }
  },
  "held_card_ranking": [
    {
      "id": "chase-freedom-unlimited",
      "name": "Chase Freedom Unlimited®",
      "network": "Visa",
      "eligible_for_pos": true,
      "expected_return": { "value": 3.75, "cents": 375, "formatted": "$3.75", "currency": "USD" }
    },
    {
      "id": "citi-double-cash",
      "name": "Citi Double Cash® Card",
      "network": "Mastercard",
      "eligible_for_pos": false,
      "ineligibility_reason": "Mastercard not accepted at physical warehouse registers"
    },
    {
      "id": "amex-gold",
      "name": "American Express® Gold Card",
      "network": "American Express",
      "eligible_for_pos": false,
      "ineligibility_reason": "American Express not accepted at physical warehouse registers"
    }
  ],
  "unheld_card_opportunity": {
    "id": "costco-anywhere-visa",
    "name": "Costco Anywhere Visa® Card by Citi",
    "reward_yield": { "value": 2.0, "unit": "%", "formatted": "2.0%", "basis_points": 200 },
    "marginal_alpha_return": { "value": 1.25, "cents": 125, "formatted": "$1.25", "currency": "USD" }
  }
}

2. Monthly Spend Basket Optimizer (POST /api/optimize)

POST https://www.axetip.com/api/optimize
Content-Type: application/json

{
  "mode": "basket",
  "monthly_spend": {
    "dining": 800,
    "grocery": 600,
    "travel": 500,
    "general": 1200
  },
  "held_cards": ["citi-double-cash", "chase-freedom-unlimited"]
}
{
  "status": "success",
  "mode": "basket",
  "summary": "Monthly spend of $3,100.00 across 4 categories generates $1,116.00 in gross annual rewards across current wallet. Acquiring American Express® Gold Card would yield +$284.00 net annual alpha after annual fee.",
  "annual_metrics": {
    "gross_annual_spend": { "value": 37200.0, "cents": 3720000, "formatted": "$37,200.00", "currency": "USD" },
    "gross_annual_return": { "value": 1116.0, "cents": 111600, "formatted": "$1,116.00", "currency": "USD" },
    "blended_effective_yield": { "value": 3.0, "unit": "%", "formatted": "3.00%", "basis_points": 300 }
  },
  "optimal_card_opportunity": {
    "card_id": "amex-gold",
    "card_name": "American Express® Gold Card",
    "annual_fee": { "value": 325.0, "cents": 32500, "formatted": "$325.00", "currency": "USD" },
    "gross_annual_alpha": { "value": 609.0, "cents": 60900, "formatted": "$609.00", "currency": "USD" },
    "net_annual_alpha": { "value": 284.0, "cents": 28400, "formatted": "$284.00", "currency": "USD" }
  }
}

Code Samples

cURL

curl -s "https://www.axetip.com/api/optimize?merchant=doordash&amount=45&held_cards=amex-gold,citi-double-cash"

TypeScript / Node.js

interface OptimizeResponse {
  routing_summary: string;
  optimal_held_card: {
    id: string;
    name: string;
    reward_yield: { formatted: string };
    expected_return: { formatted: string };
  };
  unheld_card_opportunity?: {
    name: string;
    marginal_alpha_return: { formatted: string };
  };
}

const res = await fetch("https://www.axetip.com/api/optimize?merchant=doordash&amount=45&held_cards=amex-gold,citi-double-cash");
const data: OptimizeResponse = await res.json();

console.log(data.routing_summary);
console.log(`Optimal Swipe: ${data.optimal_held_card.name} (${data.optimal_held_card.expected_return.formatted})`);
if (data.unheld_card_opportunity) {
  console.log(`Incremental Opportunity: ${data.unheld_card_opportunity.name} (+${data.unheld_card_opportunity.marginal_alpha_return.formatted})`);
}

Python

import httpx

url = "https://www.axetip.com/api/optimize"
params = {
    "merchant": "doordash",
    "amount": "45",
    "held_cards": "amex-gold,citi-double-cash"
}

response = httpx.get(url, params=params, timeout=10.0)
data = response.json()

print(data["routing_summary"])
top = data["optimal_held_card"]
print(f"Optimal Swipe: {top['name']} ({top['expected_return']['formatted']})")
if data.get("unheld_card_opportunity"):
    opp = data["unheld_card_opportunity"]
    print(f"Incremental Opportunity: {opp['name']} (+{opp['marginal_alpha_return']['formatted']})")

Go

package main

import (
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

type OptimizeResponse struct {
	RoutingSummary  string `json:"routing_summary"`
	OptimalHeldCard struct {
		Name           string `json:"name"`
		ExpectedReturn struct {
			Formatted string `json:"formatted"`
		} `json:"expected_return"`
	} `json:"optimal_held_card"`
	UnheldCardOpportunity *struct {
		Name                string `json:"name"`
		MarginalAlphaReturn struct {
			Formatted string `json:"formatted"`
		} `json:"marginal_alpha_return"`
	} `json:"unheld_card_opportunity"`
}

func main() {
	url := "https://www.axetip.com/api/optimize?merchant=doordash&amount=45&held_cards=amex-gold,citi-double-cash"
	resp, _ := http.Get(url)
	defer resp.Body.Close()

	body, _ := io.ReadAll(resp.Body)
	var res OptimizeResponse
	json.Unmarshal(body, &res)

	fmt.Println(res.RoutingSummary)
	fmt.Printf("Optimal Swipe: %s (%s)\n", res.OptimalHeldCard.Name, res.OptimalHeldCard.ExpectedReturn.Formatted)
	if res.UnheldCardOpportunity != nil {
		fmt.Printf("Opportunity: %s (+%s)\n", res.UnheldCardOpportunity.Name, res.UnheldCardOpportunity.MarginalAlphaReturn.Formatted)
	}
}

Status Codes

Status CodeDescription
200 OKRequest succeeded. Optimal card routing or basket metrics returned.
400 Bad RequestMissing required parameters (merchant/amount for transaction, or monthly_spend for basket).
429 Too Many RequestsRate limit exceeded (60 requests/minute).