API Documentation

Need an API Key?

Generate your API keys from your profile page to get started.

Get API Key

Endpoint

POST/api/v1/calculate-reward

Base URL: https://www.thecardcaddie.com

Authentication

Include your API key in the Authorization header as a Bearer token:

Authorization: Bearer cc_your_api_key_here

Request

Parameters

cardrequiredstring

Name of the credit card in your wallet (e.g., "Chase Sapphire Preferred")

merchantrequiredstring

Merchant domain or name (e.g., "Starbucks", "Amazon.com")

amountrequirednumber

Transaction amount in dollars (e.g., 25.00)

categoryoptionalstring

Transaction category if known (e.g., "Dining", "Travel", "Groceries"). If provided, uses category-based lookup instead of domain lookup.

Example Request

curl -X POST https://www.thecardcaddie.com/api/v1/calculate-reward \
  -H "Authorization: Bearer cc_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "card": "Chase Sapphire Preferred",
    "merchant": "Starbucks",
    "amount": 25.00
  }'

Response

Response Fields

success

Boolean indicating if the request was successful

reward.value

Reward value in dollars (e.g., 0.75 for 75 cents)

reward.rate

Reward rate as percentage string (e.g., "3%")

reward.category

Transaction category (e.g., "Dining", "Travel")

reward.categorySource

How category was determined: "provided", "domain_lookup", "domain_specific", or "default"

Example Response

{
  "success": true,
  "reward": {
    "value": 0.75,
    "rate": "3%",
    "category": "Dining",
    "cardName": "Chase Sapphire Preferred",
    "merchant": "Starbucks",
    "amount": 25.00,
    "categorySource": "domain_lookup"
  }
}

Rate Limiting

API requests are limited to:

100 requests per day

Rate limit headers are included in responses:

  • • X-RateLimit-Remaining
  • • X-RateLimit-Reset
  • • Retry-After (if rate limited)

Error Codes

400

Bad Request

Invalid or missing parameters

401

Unauthorized

Missing or invalid API key

404

Not Found

Card not found in your wallet or no active cards

429

Too Many Requests

Rate limit exceeded

500

Internal Server Error

Server-side error

Important Notes

  • •Cards must be added to your wallet at thecardcaddie.com before they can be used in API requests
  • •Category field is optional - if omitted, category is looked up from domain database
  • •Domain-specific rewards (configured per card) take precedence over category-based rewards
  • •Merchant names are normalized (e.g., "https://www.amazon.com" becomes "amazon.com")
  • •Category names support variations and synonyms (e.g., "restaurant" maps to "Dining")

Use Cases

Micro-Investing Apps

Automatically invest credit card rewards into ETFs and stocks

Expense Trackers

Show users their actual rewards earned per transaction

Financial Dashboards

Aggregate and visualize total rewards across all cards

Card Optimizers

Suggest which card to use for maximum rewards

Ready to integrate?

Generate your API keys and start building today.

Get Started