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:
- Single Transaction Routing (
mode: "transaction"): Selects the optimal card for a specific purchase amount at a given merchant. - 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
| Parameter | Type | In | Required | Description |
|---|---|---|---|---|
mode | string | Query / Body | No | Operational mode: transaction (default) or basket. |
merchant | string | Query / Body | Yes (transaction) | Merchant name, alias, or slug (e.g. doordash, costco, delta). |
amount | number | Query / Body | Yes (transaction) | Transaction amount in USD (e.g. 45.00 or 250). |
held_cards | string or array | Query / Body | Yes | Comma-separated query string (GET) or string array (POST) of cards in the user’s wallet. |
monthly_spend | object or string | Query / Body | Yes (basket) | Category spend map (e.g. {"dining": 800, "grocery": 600, "general": 1200}) or serialized string (dining:800,grocery:600). |
Request Headers
| Header | Value | Description |
|---|---|---|
Accept | application/json | Expected response content type. |
Content-Type | application/json | Required 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: falseand the specific ineligibility reason. - The router excludes non-accepted cards from the recommended swipe decision.
- A structured alert is added to
pos_quirksdescribing the constraint.
Response Schema
Transaction Mode Schema
| Field | Type | Description |
|---|---|---|
status | string | Request status ("success" or "error"). |
mode | string | Operational mode ("transaction"). |
routing_summary | string | Human-readable transaction routing decision. |
transaction | object | Resolved transaction context (merchant, amount, MCC). |
pos_quirks | array | Physical checkout register acceptance rules and alerts. |
optimal_held_card | object | The highest-earning eligible card currently in the wallet. |
held_card_ranking | array | Ranked list of all submitted held cards with eligibility status and expected return. |
unheld_card_opportunity | object or null | The best market card not in the user’s wallet and its marginal return. |
Basket Mode Schema
| Field | Type | Description |
|---|---|---|
status | string | Request status ("success" or "error"). |
mode | string | Operational mode ("basket"). |
summary | string | Portfolio performance summary. |
annual_metrics | object | Gross annual spend, gross annual rewards return, and blended yield across wallet. |
optimal_card_opportunity | object | Unheld 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 Code | Description |
|---|---|
200 OK | Request succeeded. Optimal card routing or basket metrics returned. |
400 Bad Request | Missing required parameters (merchant/amount for transaction, or monthly_spend for basket). |
429 Too Many Requests | Rate limit exceeded (60 requests/minute). |