API Documentation

REST API v1 for CreditSync Pro subscribers

Authentication

All requests require a Bearer token in the Authorization header. Generate an API key in Settings > API (Pro subscription required).

Authorization: Bearer cs_your_key_here

Tokens are hashed (SHA-256) on our end. The raw key is shown once at creation. If you lose it, revoke and create a new one.

Base URL

https://www.creditsync.pro/api/v1

Errors

All errors return JSON with an error field:

401 — Invalid or missing API key

404 — Resource not found (or not in your household)

400 — Invalid request body or parameters

GET/api/v1/benefits

List all tracked benefits with current period status, amounts, and expiry dates.

Parameter	Type	Required	Description
status	string	No	Filter by usage status: unused, partial, or used
card	string	No	Filter by card nickname (partial match)
card_id	string	No	Filter by exact card ID. Takes precedence over `card` nickname filter when both are passed.
expiring_within_days	integer	No	Only return benefits expiring within N days. Response includes total_at_risk summary.

Example request

curl -H "Authorization: Bearer cs_your_key" \
  "https://www.creditsync.pro/api/v1/benefits?expiring_within_days=7"

Example response

{
  "total_at_risk": 292.00,
  "credit_count": 6,
  "credits": [
    {
      "benefit_id": "clm...",
      "period_id": "clm...",
      "credit_name": "Quarterly Hilton credit",
      "card_display_name": "1006 · Amex Business Platinum",
      "owner": "Matt",
      "period_type": "quarterly",
      "period_label": "Q1 2026",
      "credit_amount": 50,
      "amount_used": 8,
      "amount_remaining": 42,
      "unit": "dollars",
      "period_start": "2026-01-01",
      "period_end": "2026-03-31",
      "days_remaining": 1,
      "status": "partial",
      "category": "hotel"
    }
  ]
}

GET/api/v1/benefits/:id

Get detailed information about a specific benefit including all historical periods.

Parameter	Type	Required	Description
id	string	Yes	The benefit_id from the list endpoint

Example request

curl -H "Authorization: Bearer cs_your_key" \
  "https://www.creditsync.pro/api/v1/benefits/clm..."

Example response

{
  "benefit_id": "clm...",
  "credit_name": "Uber Cash",
  "card_display_name": "1007 · Amex Platinum",
  "owner": "Matt",
  "category": "rideshare",
  "schedule_type": "monthly",
  "description": "$15 monthly Uber Cash.",
  "periods": [
    {
      "period_id": "clm...",
      "period_start": "2026-03-01",
      "period_end": "2026-03-31",
      "amount": 15,
      "amount_used": 15,
      "amount_remaining": 0,
      "unit": "dollars",
      "status": "used",
      "used_at": "2026-03-15T00:00:00.000Z",
      "notes": null
    }
  ]
}

PATCH/api/v1/benefits/:id/use

Mark a benefit period as used, partially used, or unused. Use the period_id from the list or detail endpoints.

Parameter	Type	Required	Description
id	string	Yes	The period_id to update (in URL path)
usageStatus	string	Yes	New status: unused, partial, or used
usedAmount	number	No	Dollar amount used (required for partial status)
notes	string	No	Optional note about usage

Example request

curl -X PATCH -H "Authorization: Bearer cs_your_key" \
  -H "Content-Type: application/json" \
  -d '{"usageStatus": "partial", "usedAmount": 8}' \
  "https://www.creditsync.pro/api/v1/benefits/clm.../use"

Example response

{
  "period_id": "clm...",
  "status": "partial",
  "amount": 50,
  "amount_used": 8,
  "amount_remaining": 42,
  "used_at": "2026-03-31T00:00:00.000Z",
  "success": true
}

GET/api/v1/dashboard

Get dashboard metrics: benefits expiring in 30 days, captured this month, total available, and net ROI value. As of Phase 8, once-per-household benefits (CLEAR) and once-per-owner benefits (Global Entry, TSA PreCheck) are deduplicated — only the winning card's period contributes to total_available and expiring counts. Sibling cards' entries still exist and are visible via /api/v1/benefits with benefit_group metadata.

Example request

curl -H "Authorization: Bearer cs_your_key" \
  "https://www.creditsync.pro/api/v1/dashboard"

Example response

{
  "expiring_in_30_days": {
    "amount": 429.00,
    "count": 16
  },
  "captured_this_month": 2516.97,
  "total_available": 8450.00,
  "net_value_ytd": {
    "total_fees": 5724,
    "total_captured": 2516.97,
    "net_value": -3207.03
  },
  "card_count": 14
}

GET/api/v1/cards

List all credit cards with issuer, annual fee, renewal month, owner, and benefit count. For full card detail including ROI and benefit status, use GET /api/v1/cards/:id.

Example request

curl -H "Authorization: Bearer cs_your_key" \
  "https://www.creditsync.pro/api/v1/cards"

Example response

[
  {
    "card_id": "clm...",
    "card_display_name": "1007 · Amex Platinum",
    "issuer": "Amex",
    "issuing_bank": "Amex",
    "card_name": "Platinum",
    "nickname": "1007",
    "last_four": "1007",
    "owner": "Matt",
    "annual_fee": 895,
    "renewal_month": "April",
    "benefit_count": 12,
    "added_at": "2026-01-15"
  }
]

GET/api/v1/cards/:id

Get a single card's complete picture: all benefits with current period status, captured vs annual fee ROI, renewal timeline, and total value at risk.

Parameter	Type	Required	Description
id	string	Yes	The card_id from the list endpoint

Example request

curl -H "Authorization: Bearer cs_your_key" \
  "https://www.creditsync.pro/api/v1/cards/clm..."

Example response

{
  "card_id": "clm...",
  "card_display_name": "1007 · Amex Platinum",
  "issuer": "Amex",
  "card_name": "Platinum",
  "nickname": "1007",
  "owner": "Matt",
  "annual_fee": 895,
  "renewal_month": "April",
  "roi": {
    "captured_value": 1250.00,
    "net_value": 355.00,
    "roi_percent": 139.7,
    "fee_year_start": "2026-04-01",
    "fee_year_end": "2027-03-31"
  },
  "benefits": [
    {
      "benefit_id": "clm...",
      "credit_name": "Uber Cash",
      "schedule_type": "monthly",
      "category": "rideshare",
      "current_period": {
        "period_id": "clm...",
        "period_start": "2026-04-01",
        "period_end": "2026-04-30",
        "amount": 15,
        "amount_used": 0,
        "amount_remaining": 15,
        "unit": "dollars",
        "days_remaining": 28,
        "status": "unused"
      }
    }
  ],
  "total_available": 1850.00,
  "total_at_risk_30d": 265.00
}

GET/api/v1/action-items

Get prioritized action items ranked by value at risk. Includes expiring benefits, at_risk_this_period (pattern-backed leakage signal), missed prior period credits, upcoming fee renewals, negative ROI cards, and welcome offers at risk.

Parameter	Type	Required	Description
days_ahead	integer	No	Look-ahead window for expiring benefits (default 30)
action_types	string	No	Comma-separated filter. Accepts both category names AND response-type names. Categories: expiring (emits benefit_expiring + at_risk_this_period), renewal_approaching (emits fee_renewal), unused_prior_period, negative_roi, welcome_offer_at_risk. Response-type names (for precise filtering): benefit_expiring, at_risk_this_period, fee_renewal. Default: all categories. Example: action_types=at_risk_this_period returns ONLY pattern-backed alerts; action_types=expiring returns both benefit_expiring AND at_risk_this_period.

Example request

curl -H "Authorization: Bearer cs_your_key" \
  "https://www.creditsync.pro/api/v1/action-items?days_ahead=7&action_types=expiring,renewal_approaching"

Example response

{
  "generated_at": "2026-04-16T14:30:00.000Z",
  "action_items": [
    {
      "priority": "critical",
      "type": "fee_renewal",
      "title": "$895 annual fee posted 11 days ago — retention window open",
      "detail": "1007 · Amex Platinum · Captured $820 of $895 (92% ROI)",
      "value_at_risk": 75.00,
      "days_remaining": -11,
      "card_display_name": "1007 · Amex Platinum",
      "card_id": "clm...",
      "benefit_id": null,
      "period_id": null,
      "fee_amount": 895,
      "recommended_action": "hold",
      "retention_leverage": "weak",
      "historical_offers": [
        {
          "event_id": "clm...",
          "date": "2025-04-12",
          "description": "Accepted: $200 statement credit",
          "offer_type": "statement_credit",
          "offer_value_dollars": 200,
          "offer_points": null,
          "offer_currency": null,
          "outcome": "accepted"
        }
      ]
    }
  ],
  "total_items": 8,
  "summary": {
    "critical_count": 2,
    "total_value_at_risk": 180.00,
    "items_by_type": {
      "benefit_expiring": 5,
      "at_risk_this_period": 0,
      "unused_prior_period": 0,
      "fee_renewal": 1,
      "negative_roi": 2,
      "welcome_offer_at_risk": 0
    }
  },
  "suppressed_fees": [
    {
      "card_id": "clm...",
      "card_display_name": "Amex Hilton Honors Business",
      "annual_fee": 195,
      "days_since_posted": 5,
      "reason": "new_card_with_issuer"
    }
  ]
}

Priority scoring: score = value_at_risk × urgency_factor.
Urgency factor: null→1.0, <0 && |d|≤30→1.5, <0 && |d|>30→0.4, ≤7→2.0, ≤30→1.5, ≤60→1.2, ≤90→1.0, ≤180→0.7, >180→0.4.
Buckets: ≥500 critical, ≥100 high, ≥25 medium, <25 low.

fee_renewal-only fields:
- fee_amount: annual fee in dollars
- recommended_action: cancel | retention_call | hold
- retention_leverage: weak | moderate | strong (omitted when card has <60 days in CreditSync — unreliable capture signal)
- historical_offers: up to 3 prior retention_offer events on this card, most-recent first. Empty array when none logged. Per-card, not aggregated — useful at N=1 as "last call" context for the next renewal.

at_risk_this_period + benefit_expiring (Phase 8 D):
- historical_rate: dollar-weighted historical capture ratio ∈ [0, 1]. Σ(amount_used)/Σ(amount_allocated) over min(4, N) most-recent completed periods of this benefit + owner. Populated on both types when the benefit is dollar-denominated.
- historical_rate_n: number of periods in the sample (post min(4, N) windowing).
- historical_rate_confidence: "high" (n ≥ 3) or "low". at_risk_this_period only fires at high confidence; low-confidence rates appear on benefit_expiring items as informational context.
- Firing criteria for at_risk_this_period: (days_remaining < 30) AND (historical_rate < 0.7) AND (amount_remaining > $25) AND (confidence === "high"). The same period will never fire both benefit_expiring and at_risk_this_period — at_risk promotes, benefit_expiring is the fallback.

suppressed_fees: fees that posted recently but were suppressed because the card is <30 days old with the issuer. Dashboard renders as a muted footer line.

GET/api/v1/calendar-events

Get benefit deadlines, credit resets, fee renewals, and expiry windows as structured calendar-ready event objects for intelligent agent orchestration. welcome_offer_deadline events carry `origin` ("signup" | "retention") and `source_event_id` fields — retention-origin deadlines are also marked with a [Retention] title prefix so both humans and agents can distinguish retention bonuses from signup SUBs.

Parameter	Type	Required	Description
start_date	string	No	Start of date range, YYYY-MM-DD (default: today)
end_date	string	No	End of date range, YYYY-MM-DD (default: start + 30 days, max 365 days)
event_types	string	No	Comma-separated: expiry, credit_reset, annual_fee_due, benefit_available, welcome_offer_deadline, loyalty_program_expiry, reward_expiry (default: all)
card	string	No	Filter by card nickname (partial match)
include_used	boolean	No	Include events for already-used benefits (default: false)

Example request

curl -H "Authorization: Bearer cs_your_key" \
  "https://www.creditsync.pro/api/v1/calendar-events?start_date=2026-04-01&end_date=2026-04-30&event_types=expiry,annual_fee_due"

Example response

{
  "events": [
    {
      "event_type": "expiry",
      "title": "1007 · Amex Platinum: $15 Uber Cash expires today",
      "date": "2026-04-30",
      "end_date": null,
      "all_day": true,
      "description": "$15 Uber Cash · 1007 · Amex Platinum · Matt\nStatus: unused · $15 remaining\nPeriod: 2026-04-01 – 2026-04-30",
      "recurrence": null,
      "alert_days_before": 1,
      "value_at_risk": 15.00,
      "benefit_id": "clm...",
      "period_id": "clm...",
      "card_id": "clm...",
      "card_display_name": "1007 · Amex Platinum",
      "status": "unused",
      "unit": "dollars"
    }
  ],
  "event_count": 1,
  "date_range": {
    "start": "2026-04-01",
    "end": "2026-04-30"
  }
}

GET/api/v1/catalog?q=

Search the card catalog by issuer or card name. Supports multi-word queries like 'Amex Platinum' (matches across issuer + name). Returns matching templates with IDs, fees, and benefit counts. Use the card_template_id in POST /api/v1/cards to add a card.

Parameter	Type	Required	Description
q	string	Yes	Search term — issuer, card name, or combined (e.g., 'Amex Platinum'). Min 2 chars. Each word must match in either issuer or name.

Example request

curl -H "Authorization: Bearer cs_your_key" \
  "https://www.creditsync.pro/api/v1/catalog?q=hilton"

Example response

[
  {
    "card_template_id": "clm...",
    "issuer": "Hilton",
    "name": "Aspire",
    "annual_fee": 550,
    "is_premium": true,
    "benefit_count": 6
  },
  {
    "card_template_id": "clm...",
    "issuer": "Hilton",
    "name": "Surpass",
    "annual_fee": 150,
    "is_premium": false,
    "benefit_count": 2
  }
]

POST/api/v1/cards

Add a card to the portfolio with full metadata in a single call. Pass a fuzzy 'name' or exact 'card_template_id'. If multiple cards match the name, returns candidates (status 300) — call again with the confirmed card_template_id. All metadata fields (last_four, open date, business flag, 5/24, notes) can be set at creation — no follow-up update_card call needed.

Parameter	Type	Required	Description
name	string	No	Card name to fuzzy match (e.g., 'Amex Gold'). Required unless card_template_id is provided.
card_template_id	string	No	Exact template ID from catalog search (bypasses fuzzy match)
owner	string	Yes	Owner profile name (must match existing)
nickname	string	No	Nickname to distinguish duplicate cards (defaults to last_four if omitted)
last_four	string	No	Last 4 digits of the card number
original_open_date	string	No	Account open date (YYYY-MM-DD). Used for 5/24 tracking and fee_month inference.
fee_month	integer	No	Month annual fee posts (1-12). Auto-inferred from original_open_date if omitted.
is_business	boolean	No	Whether this is a business card (excluded from 5/24 by default)
counts_toward_524	boolean	No	Override default 5/24 inclusion (business cards default to false)
product_changed_from	string	No	Previous card name if this was a product change
notes	string	No	Freeform notes about the card

Example request

curl -X POST -H "Authorization: Bearer cs_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Amex Hilton Business", "owner": "Matt", "last_four": "1001", "original_open_date": "2026-04-11", "is_business": true}' \
  "https://www.creditsync.pro/api/v1/cards"

Example response

{
  "card_id": "clm...",
  "card_display_name": "Amex Hilton Honors Business",
  "matched_template": "Amex Hilton Honors Business ($195/yr)",
  "benefits_created": 4,
  "fee_month_inferred": true,
  "success": true
}

POST/api/v1/cards/bulk

Bulk import multiple cards in one call. Accepts natural language names (fuzzy matched) or exact template IDs. Returns per-card results: created, already_exists, ambiguous (with candidates), or failed. Use dry_run=true to preview matches before committing. Household owner profiles must exist before import.

Parameter	Type	Required	Description
cards	array	Yes	Array of 1-50 card objects. Each needs owner + (name or card_template_id). Optional: nickname, last_four, original_open_date, fee_month, is_business, counts_toward_524, product_changed_from, notes, welcome_offer.
dry_run	boolean	No	If true, validate and match but don't create. Returns what WOULD happen.
skip_duplicates	boolean	No	If true (default), skip existing cards. If false, return error for duplicates.

Example request

curl -X POST -H "Authorization: Bearer cs_your_key" \
  -H "Content-Type: application/json" \
  -d '{"cards": [{"name": "Amex Platinum", "owner": "Matt", "last_four": "1007", "original_open_date": "2022-04-05"}, {"name": "Chase Sapphire Reserve", "owner": "Matt"}], "dry_run": true}' \
  "https://www.creditsync.pro/api/v1/cards/bulk"

Example response

{
  "summary": { "total": 2, "created": 2, "already_exists": 0, "ambiguous": 0, "failed": 0, "dry_run": true },
  "results": [
    { "index": 0, "input_name": "Amex Platinum", "status": "created", "matched_template": { "issuer": "Amex", "name": "Platinum", "annual_fee": 895 } },
    { "index": 1, "input_name": "Chase Sapphire Reserve", "status": "created", "matched_template": { "issuer": "Chase", "name": "Sapphire Reserve", "annual_fee": 550 } }
  ]
}

DELETE/api/v1/cards/:id

Archive a card (soft delete). Benefits and usage history are preserved but the card stops appearing in active views.

Parameter	Type	Required	Description
id	string	Yes	The card_id to archive

Example request

curl -X DELETE -H "Authorization: Bearer cs_your_key" \
  "https://www.creditsync.pro/api/v1/cards/clm..."

Example response

{
  "card_id": "clm...",
  "archived": true,
  "success": true
}

GET/api/v1/programs

List tracked loyalty programs with current balances, CPP valuations, staleness indicators, linked cards, and transfer partner counts. Use has_balance=true to cut payload ~80% by excluding zero-balance programs.

Parameter	Type	Required	Description
has_balance	boolean	No	Only return programs with balance > 0 (cuts payload ~80%)
type	string	No	Filter by program type: airline, hotel, bank, or other
owner	string	No	Filter by owner name
stale_days	integer	No	Only return programs not updated in N days

Example request

curl -H "Authorization: Bearer cs_your_key" \
  "https://www.creditsync.pro/api/v1/programs"

Example response

[
  {
    "program_key": "amex_mr",
    "display_name": "Amex Membership Rewards",
    "type": "bank",
    "currency": "points",
    "balance": 1524000,
    "cpp_valuation": 2.0,
    "estimated_value": 30480.00,
    "last_updated": "2026-04-01",
    "days_since_update": 3,
    "is_stale": false,
    "linked_cards": ["1007 · Amex Platinum"],
    "transfer_partner_count": 21
  }
]

POST/api/v1/programs

Create or update a loyalty program balance. Supports absolute set or relative delta. Auto-creates the program if it doesn't exist.

Parameter	Type	Required	Description
program_key	string	Yes	Program key (e.g., 'amex_mr', 'aa_advantage')
balance	integer	No	Set absolute balance (provide balance OR delta, not both). Optional if only updating cpp_valuation.
delta	integer	No	Relative change (e.g., +12500 or -88000)
display_name	string	No	Program name (required on first creation)
cpp_valuation	float	No	Default cents-per-point valuation

Example request

curl -X POST -H "Authorization: Bearer cs_your_key" \
  -H "Content-Type: application/json" \
  -d '{"program_key": "amex_mr", "delta": -88000}' \
  "https://www.creditsync.pro/api/v1/programs"

Example response

{
  "program_key": "amex_mr",
  "previous_balance": 1524000,
  "new_balance": 1436000,
  "change": -88000,
  "cpp_valuation": 2.0,
  "estimated_value": 28720.00,
  "last_updated": "2026-04-03T14:30:00.000Z"
}

GET/api/v1/programs/transfer-partners

Get all transfer partners for a loyalty currency with transfer ratios.

Parameter	Type	Required	Description
source	string	Yes	Source program key (e.g., 'amex_mr', 'chase_ur')

Example request

curl -H "Authorization: Bearer cs_your_key" \
  "https://www.creditsync.pro/api/v1/programs/transfer-partners?source=amex_mr"

Example response

[
  {
    "target_program_key": "virgin_atlantic",
    "target_display_name": "Virgin Atlantic Flying Club",
    "ratio": 1.0,
    "min_transfer": 1000,
    "notes": null
  }
]

GET/api/v1/earn-rates

Get earning rates for a specific card. Returns bonus categories with multipliers, currencies, caps, and CPP-based value per dollar spent.

Parameter	Type	Required	Description
card_id	string	No	User's card ID (looks up template)
card_template_id	string	No	Catalog template ID directly

Example request

curl -H "Authorization: Bearer cs_your_key" \
  "https://www.creditsync.pro/api/v1/earn-rates?card_id=clm..."

Example response

[
  {
    "category": "dining",
    "multiplier": 4.0,
    "currency": "amex_mr",
    "currency_display_name": "Amex Membership Rewards",
    "cpp_valuation": 2.0,
    "value_per_dollar_cents": 8.0,
    "channel": "any",
    "cap_amount": 50000,
    "is_rotating": false,
    "verified_date": "2026-04-03"
  }
]

GET/api/v1/best-card

Wallet optimizer: given a spend category, returns the best card ranked by effective value per dollar. Uses CPP valuations from loyalty programs. Accepts cpp_override for contextual adjustments.

Parameter	Type	Required	Description
category	string	Yes	Spend category: dining, groceries, gas, flights, hotels, etc.
amount	number	No	Purchase amount for points-earned calculation
owner	string	No	Filter to specific owner
channel	string	No	Filter: direct, portal, or any (default any)
cpp_override	string	No	CPP overrides as 'currency:value' pairs (e.g., 'amex_mr:2.5')

Example request

curl -H "Authorization: Bearer cs_your_key" \
  "https://www.creditsync.pro/api/v1/best-card?category=dining&amount=100&owner=Matt"

Example response

[
  {
    "rank": 1,
    "card_id": "clm...",
    "card_display_name": "2002 · Amex Gold",
    "multiplier": 4.0,
    "currency": "amex_mr",
    "cpp_used": 2.0,
    "value_per_dollar_cents": 8.0,
    "points_earned": 400,
    "estimated_value": 8.00,
    "channel": "any"
  }
]

PATCH/api/v1/cards/:id

Update card metadata: nickname, notes (appended), original open date, product change history, business flag, 5/24 status, last four digits. Also supports logging, updating, and deleting retention offers (retention offers with spend_requirement + spend_deadline auto-create a paired WelcomeOffer for calendar reminders). All changes are audit-logged.

Parameter	Type	Required	Description
id	string	Yes	Card ID (in URL path)
nickname	string	No	Update nickname
notes	string	No	Add a note (appended with timestamp)
original_open_date	string	No	Account open date (YYYY-MM-DD)
product_changed_from	string	No	Previous card name before product change
is_business	boolean	No	Is this a business card?
counts_toward_524	boolean	No	Counts toward Chase 5/24?
last_four	string	No	Last 4 digits (exactly 4)
retention_offer	object	No	Log a retention offer. Minimal legacy shape: { offer, accepted, date?, notes? }. Recommended structured shape: { offer, outcome, offer_type, offer_value_dollars?, offer_points?, offer_currency?, spend_requirement?, spend_deadline?, date?, notes? }. outcome ∈ accepted\|declined\|countered\|escalated\|no_offer. offer_type ∈ statement_credit\|points_bonus\|fee_waiver\|mq_extension\|spend_bonus\|other\|no_offer. Validation: points_bonus requires offer_currency + offer_points; statement_credit/fee_waiver requires offer_value_dollars. When outcome='accepted' AND spend_requirement + spend_deadline are present, server auto-creates a paired WelcomeOffer (origin='retention', sourceEventId=event_id) for calendar reminders. Response echoes retention_entry with event_id, normalized scalars, and paired_welcome_offer_id if one was created.
update_retention_event	object	No	Patch a logged retention offer in place: { event_id, offer?, offer_type?, offer_value_dollars?, offer_points?, offer_currency?, outcome?, notes? }. event_id + date are immutable. Re-runs validation on the merged state. Records an audit breadcrumb in metadata._updates. Prefer this over delete + relog — preserves event_id and history ordering.
delete_retention_event_id	string	No	Delete a retention offer entry by its event_id (from retention_history or log response). Prefer update_retention_event for corrections. If the event has a paired WelcomeOffer (auto-created when logged with spend_requirement + spend_deadline), the paired WO is cascade-deleted in the same transaction — response echoes cascaded_welcome_offer_id when that happens.

Example request

curl -X PATCH -H "Authorization: Bearer cs_your_key" \
  -H "Content-Type: application/json" \
  -d '{"notes": "PC from CSP April 2026", "product_changed_from": "Chase Sapphire Preferred", "counts_toward_524": false}' \
  "https://www.creditsync.pro/api/v1/cards/clm..."

Example response

{
  "card_id": "clm...",
  "nickname": "2726",
  "notes": "[2026-04-04] PC from CSP April 2026",
  "original_open_date": null,
  "product_changed_from": "Chase Sapphire Preferred",
  "is_business": false,
  "counts_toward_524": false,
  "last_four": null,
  "changes": [
    { "field": "productChangedFrom", "old_value": null, "new_value": "Chase Sapphire Preferred" },
    { "field": "countsToward524", "old_value": "true", "new_value": "false" }
  ],
  "success": true
}

GET/api/v1/welcome-offers

List all welcome offers with spend progress, deadline urgency, and bonus valuations. Computed fields include daily_spend_needed and is_at_risk.

Parameter	Type	Required	Description
status	string	No	Filter: in_progress, earned, missed, all (default: in_progress)
owner	string	No	Filter by owner name
expiring_within_days	integer	No	Only offers with deadlines within N days
origin	string	No	Filter: signup (traditional welcome offers) or retention (bonuses granted on retention calls, auto-created from log_retention_offer). Omit for all.

Example request

curl -H "Authorization: Bearer cs_your_key" \
  "https://www.creditsync.pro/api/v1/welcome-offers?status=in_progress&origin=retention"

Example response

[
  {
    "offer_id": "clm...",
    "card_id": "clm...",
    "card_display_name": "2542 · Citi AAdvantage Platinum Select",
    "bonus_amount": 80000,
    "bonus_currency": "aa_aadvantage",
    "bonus_value": 1200.00,
    "spend_requirement": 5000,
    "current_spend": 3200,
    "spend_remaining": 1800,
    "spend_deadline": "2026-07-04",
    "days_remaining": 91,
    "daily_spend_needed": 19.78,
    "spend_requirement_met": false,
    "is_at_risk": false,
    "status": "in_progress",
    "origin": "signup",
    "source_event_id": null
  }
]

POST/api/v1/welcome-offers

Record a welcome offer on a card. Tracks bonus amount, spend requirement, deadline, and progress. One active offer per card.

Parameter	Type	Required	Description
card_id	string	Yes	The card this offer belongs to
bonus_amount	integer	Yes	Points/miles/dollars earned
bonus_currency	string	Yes	Program key (e.g., 'amex_mr')
spend_requirement	number	Yes	Dollar amount to spend
spend_deadline	string	Yes	Deadline in YYYY-MM-DD
current_spend	number	No	Spend already applied (default 0)
notes	string	No	Context (e.g., 'referral link')

Example request

curl -X POST -H "Authorization: Bearer cs_your_key" \
  -H "Content-Type: application/json" \
  -d '{"card_id": "clm...", "bonus_amount": 60000, "bonus_currency": "chase_ur", "spend_requirement": 4000, "spend_deadline": "2026-07-04"}' \
  "https://www.creditsync.pro/api/v1/welcome-offers"

Example response

{
  "offer_id": "clm...",
  "card_display_name": "8615 · Chase Sapphire Reserve",
  "bonus_amount": 60000,
  "bonus_currency": "chase_ur",
  "bonus_value": 1200.00,
  "spend_requirement": 4000,
  "current_spend": 0,
  "spend_remaining": 4000,
  "days_remaining": 91,
  "daily_spend_needed": 43.96,
  "spend_requirement_met": false,
  "is_at_risk": false,
  "status": "in_progress",
  "success": true
}

PATCH/api/v1/welcome-offers/:cardId

Update spend progress or status on an active welcome offer. No auto-earn — set status to 'earned' only after confirming the bonus posted.

Parameter	Type	Required	Description
cardId	string	Yes	Card ID with the active offer (in URL)
current_spend	number	No	Set absolute spend
spend_delta	number	No	Relative change (e.g., +450)
status	string	No	Update: earned, missed, or cancelled
notes	string	No	Additional context

Example request

curl -X PATCH -H "Authorization: Bearer cs_your_key" \
  -H "Content-Type: application/json" \
  -d '{"spend_delta": 1200}' \
  "https://www.creditsync.pro/api/v1/welcome-offers/clm..."

Example response

{
  "offer_id": "clm...",
  "spend_requirement": 4000,
  "current_spend": 1200,
  "spend_remaining": 2800,
  "days_remaining": 84,
  "daily_spend_needed": 33.33,
  "spend_requirement_met": false,
  "is_at_risk": false,
  "status": "in_progress",
  "success": true
}

POST/api/v1/benefits

Add a new benefit to a card. Generates periods automatically based on schedule_type. For mid-year additions or perks not in the catalog. Returns 409 Conflict if a benefit with the same name (custom or catalog-backed) already exists on this card; pass force=true to add a duplicate intentionally.

Parameter	Type	Required	Description
card_id	string	Yes	The card this benefit belongs to
credit_name	string	Yes	Benefit name (e.g., 'Oura Ring credit')
amount	number	Yes	Dollar value per period
schedule_type	string	Yes	Reset schedule: monthly, quarterly, semiannual, annual_calendar, annual_cardmember, every_4_years, spend_gated, one_time
unit	string	No	dollars, points, or nights (default: dollars)
category	string	No	Category (default: other)
force	boolean	No	Set true to bypass duplicate-name check and create a duplicate anyway. Default false — duplicates return 409.
dry_run	boolean	No	If true, validate without persisting. Returns what would be created. Use for testing.

Example request

curl -X POST -H "Authorization: Bearer cs_your_key" \
  -H "Content-Type: application/json" \
  -d '{"card_id": "clm...", "credit_name": "Oura Ring credit", "amount": 200, "schedule_type": "annual_calendar", "category": "fitness"}' \
  "https://www.creditsync.pro/api/v1/benefits"

Example response

{
  "benefit_id": "clm...",
  "credit_name": "Oura Ring credit",
  "amount": 200,
  "schedule_type": "annual_calendar",
  "periods_generated": 2,
  "is_agent_created": true,
  "success": true
}

PATCH/api/v1/benefits/:id

Update a benefit's details. Audit-logged. Amount changes affect future periods only. Set status to 'discontinued' to archive.

Parameter	Type	Required	Description
id	string	Yes	Benefit ID (in URL)
credit_name	string	No	Update name
amount	number	No	Update amount (future periods only)
category	string	No	Update category
status	string	No	Set to 'discontinued' to archive
notes	string	No	Add a note

Example request

curl -X PATCH -H "Authorization: Bearer cs_your_key" \
  -H "Content-Type: application/json" \
  -d '{"amount": 250, "notes": "Increased from $200 effective Jan 2027"}' \
  "https://www.creditsync.pro/api/v1/benefits/clm..."

Example response

{
  "benefit_id": "clm...",
  "changes": [
    { "field": "amount", "old_value": "200", "new_value": "250" }
  ],
  "success": true
}

GET/api/v1/524-status

Compute Chase 5/24 eligibility from card metadata. Returns count, slots available, cards counting, next slot opening, and data quality warnings.

Parameter	Type	Required	Description
owner	string	No	Filter by cardholder name

Example request

curl -H "Authorization: Bearer cs_your_key" \
  "https://www.creditsync.pro/api/v1/524-status?owner=Matt"

Example response

{
  "current_count": 3,
  "limit": 5,
  "slots_available": 2,
  "is_eligible": true,
  "cards_counting": [
    {
      "card_display_name": "2002 · Amex Gold",
      "original_open_date": "2024-09-15",
      "falls_off_date": "2026-09-15",
      "days_until_falloff": 164
    }
  ],
  "next_slot_opens": "2026-09-15",
  "cards_excluded": [
    {
      "card_display_name": "1002 · Amex Business Platinum",
      "reason": "Business card (is_business = true)"
    }
  ],
  "warnings": []
}

GET/api/v1/external-cards

List external cards tracked for Chase 5/24 only. These are cards not in the CreditSync catalog.

Example request

curl -H "Authorization: Bearer cs_your_key" \
  "https://www.creditsync.pro/api/v1/external-cards"

Example response

[
  {
    "id": "cmn...",
    "card_name": "Chase Amazon Visa",
    "open_date": "2024-03-15",
    "is_business": false,
    "owner": "Matt",
    "notes": null
  }
]

POST/api/v1/external-cards

Add a non-catalog card for 5/24 tracking. Only the card name and open date are required.

Parameter	Type	Required	Description
card_name	string	Yes	Card name (e.g., 'Chase Amazon Visa')
open_date	string	Yes	Date card was opened (YYYY-MM-DD)
is_business	boolean	No	Whether card is a business card (default false)
owner	string	No	Cardholder name
notes	string	No	Optional notes

Example request

curl -X POST -H "Authorization: Bearer cs_your_key" \
  -H "Content-Type: application/json" \
  -d '{"card_name":"Chase Amazon Visa","open_date":"2024-03-15","owner":"Matt"}' \
  "https://www.creditsync.pro/api/v1/external-cards"

Example response

{
  "id": "cmn...",
  "card_name": "Chase Amazon Visa",
  "open_date": "2024-03-15",
  "is_business": false,
  "owner": "Matt",
  "success": true
}

DELETE/api/v1/external-cards/:id

Remove an external card from 5/24 tracking.

Example request

curl -X DELETE -H "Authorization: Bearer cs_your_key" \
  "https://www.creditsync.pro/api/v1/external-cards/cmn..."

Example response

{
  "id": "cmn...",
  "card_name": "Chase Amazon Visa",
  "deleted": true
}

GET/api/v1/rewards

List credits & certificates (gift cards, vouchers, travel credits). Filterable by status, type, or expiring window.

Parameter	Type	Required	Description
status	string	No	Filter by status: active, used, expired (default: all)
type	string	No	Filter by type: gift_card, travel_credit, voucher, lounge_pass, free_night, companion_cert, milestone, coupon, other
expiring_within_days	integer	No	Only active rewards expiring within N days

Example request

curl -H "Authorization: Bearer cs_your_key" \
  "https://www.creditsync.pro/api/v1/rewards?status=active&expiring_within_days=30"

Example response

[
  {
    "id": "cmn...",
    "name": "Hilton $50 gift card",
    "type": "gift_card",
    "value": 50,
    "currency": "dollars",
    "expiration_date": "2027-12-31",
    "status": "active",
    "source": "retention call"
  }
]

POST/api/v1/rewards

Track a credit, certificate, or reward. Existence-only — do not store card numbers or PINs. Items with expiration dates appear in the calendar feed.

Parameter	Type	Required	Description
name	string	Yes	Reward name
type	string	No	Type: gift_card, travel_credit, voucher, lounge_pass, free_night, companion_cert, milestone, coupon, other
value	number	No	Dollar value
expiration_date	string	No	YYYY-MM-DD (generates calendar alerts at 90/30/7 days)
source	string	No	Where it came from (e.g., retention call)
owner	string	No	Owner name

Example request

curl -X POST -H "Authorization: Bearer cs_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name":"Hilton $50 gift card","type":"gift_card","value":50,"expiration_date":"2027-12-31","source":"retention call"}' \
  "https://www.creditsync.pro/api/v1/rewards"

Example response

{
  "id": "cmn...",
  "name": "Hilton $50 gift card",
  "type": "gift_card",
  "value": 50,
  "expiration_date": "2027-12-31",
  "status": "active",
  "success": true
}

PATCH/api/v1/rewards/:id

Update a reward or mark it as used. Set status to 'used' when redeemed.

Parameter	Type	Required	Description
status	string	No	Set to 'used' when redeemed, or 'expired'
name	string	No	Update name
value	number	No	Update value
expiration_date	string	No	Update expiration date (YYYY-MM-DD)

Example request

curl -X PATCH -H "Authorization: Bearer cs_your_key" \
  -H "Content-Type: application/json" \
  -d '{"status":"used"}' \
  "https://www.creditsync.pro/api/v1/rewards/cmn..."

Example response

{
  "id": "cmn...",
  "name": "Hilton $50 gift card",
  "status": "used",
  "used_at": "2026-04-06"
}

DELETE/api/v1/rewards/:id

Delete a reward permanently.

Example request

curl -X DELETE -H "Authorization: Bearer cs_your_key" \
  "https://www.creditsync.pro/api/v1/rewards/cmn..."

Example response

{
  "id": "cmn...",
  "name": "Hilton $50 gift card",
  "deleted": true
}

MCP Server

For Claude Desktop integration, install the official MCP server:

// claude_desktop_config.json
{
  "mcpServers": {
    "creditsync": {
      "command": "npx",
      "args": ["@creditsync-pro/mcp"],
      "env": {
        "CREDITSYNC_API_KEY": "cs_your_key"
      }
    }
  }
}

See the npm package for full documentation.

Integration ideas

CreditSync’s API is read/write, so integrations can both query and act. Here are examples across the full tool surface:

Wallet optimizer via NFC/location — Apple Shortcuts triggers get_best_card when you enter a grocery store or restaurant, showing which card earns the most before you tap to pay
Welcome offer spend tracker — connect a bank email parser or Plaid to auto-call update_welcome_offer on each transaction, keeping SUB pacing current without manual entry
ROI home screen widget — Scriptable (iOS) or KWGT (Android) calls get_dashboard to show captured vs. fees and a red/yellow/green ROI indicator at a glance
5/24 application monitor — monthly cron calls get_524_status + search_catalog and alerts when a new Chase slot opens: “You’re now 3/24 — the Hyatt window is open”
Transfer bonus scanner — n8n/Make workflow calls get_transfer_partners on a schedule and alerts when a transfer ratio improves (1:1 → 1:1.3)
Retention call prep — 30 days before an annual fee, get_calendar_events triggers a workflow that pulls ROI data via get_card and generates a retention call script
Points balance dashboard — list_programs(has_balance: true) feeds Grafana or a spreadsheet to track balance trends and spot stale programs approaching expiration
Benefit usage logger — photo of a receipt → OCR extracts amount → mark_benefit_used with partial amount. Works via Apple Shortcuts camera action or a Telegram bot
Gift card tracker — parse confirmation emails for gift cards and vouchers, auto-call add_reward with name, value, and expiration. No manual entry
Weekly spend optimizer email — every Monday, run get_best_card across 8 categories and format as a “weekly wallet guide” showing the optimal card for each spend type
New card onboarding automation — create_card triggers a workflow that creates a welcome offer, checks 5/24 impact, lists benefits, and syncs calendar events — full setup in one trigger
Expiring benefit alerts — Apple Shortcuts, Telegram, Discord, or Slack bot polls get_action_items and pushes alerts for benefits expiring this week