---
title: "Renewal Check"
method: POST
path: "/api/v1/intelligence/renewal"
tags: ["Intelligence"]
---

# Renewal Check

`POST /api/v1/intelligence/renewal`

## Request

- Base URL: `https://kokofinance.net` (the document declares no server; this is the origin it was published from)
- URL: `https://kokofinance.net/api/v1/intelligence/renewal`
- Auth: API key in header `X-API-Key`

Check if a credit card is worth renewing.

fast mode: Deterministic renewal verdict using calculate_renewal_verdict().
Returns RENEW, DOWNGRADE, or CANCEL_AND_REPLACE verdict with downgrade
and replacement options.

verbose mode: Same deterministic verdict plus AI-generated detailed analysis,
retention tips, and timing guidance (uses asyncio.to_thread for Gemini call).

## Query parameters

- `mode` 'fast' | 'verbose': Response mode for intelligence endpoints.

## Headers

- `authorization` string, nullable

## Request body

- V1RenewalCheckRequest: Request for POST /api/v1/card/renewal-check
  - `card_name` string, required: Name of the card to check for renewal
  - `card_id` integer, nullable: Matched card ID if known
  - `acquired_date` string, nullable: Date card was acquired (YYYY-MM-DD)
  - `portfolio_card_names` string[], nullable: Other cards in portfolio for context
  - `benefit_selections` string[], nullable: Individual benefit keys the user uses (e.g. ['uber', 'dining', 'admirals_club']). Selected at 100%, unselected at 0%.
  - `benefit_categories_used` string[], nullable: Benefit categories the user uses (e.g. ['dining_credit', 'lounge_access']). benefit_selections provides finer control.
  - `params` ClientParameters: Configurable parameters for B2B API consumption. These parameters allow API clients (issuers, fintechs) to customize KoKo's analysis for their use case without changing core logic.
    - `issuer_preferences` IssuerPreference[], nullable
      - `issuer` string, required: Card issuer name
      - `weight` number: 1.0 = neutral, >1.0 = boost, <1.0 = de-boost
    - `credit_tier` string, nullable
    - `spending` SpendingInput: Monthly spending by category (dollars)
      - `groceries` number, nullable: Monthly grocery spend
      - `dining` number, nullable: Monthly dining/restaurant spend
      - `travel` number, nullable: Monthly travel spend
      - `gas` number, nullable: Monthly gas/fuel spend
      - `streaming` number, nullable: Monthly streaming services spend
      - `shopping` number, nullable: Monthly general shopping spend
      - `other` number, nullable: Monthly other spend
      - `total_monthly` number, nullable: Total monthly spend override
    - `point_balances` InlinePointBalance[], nullable: Point/miles balances for enrichment. API consumers provide these per-request.
      - `program` string, required: Program key
      - `balance` integer, required: Point/miles balance
    - `primary_goal` string, nullable
    - `benefit_selections` string[], nullable: Individual benefit keys the user actually uses. Selected benefits count at 100%, unselected at 0%. If omitted, all benefits use the default 50% utilization. Common keys: uber, dining, travel, airline_fee, hotel_fhr, saks, clear_plus, digital_entertainment, admirals_club, global_entry, lyft, grubhub. Use GET /api/v1/benefit-categories for the full registry.
    - `benefit_categories_used` string[], nullable: Standard benefit categories the user uses (alternative to benefit_selections). Each category maps to one or more individual benefit keys. Valid values: dining_credit, travel_credit, hotel_credit, lounge_access, shopping_credit, entertainment_credit, business_credit, loyalty_bonus, other. Note: benefit_selections provides finer control.
    - `renewal_cancel_threshold` number, nullable: Net value below this → CANCEL_AND_REPLACE. Default: -100
    - `renewal_keep_threshold` number, nullable: Net value at or above this → RENEW. Default: 50

## Response `200`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/kokofinance/apis/koko-finance-api.md) · [All operations](https://skmtc.dev/kokofinance/apis/koko-finance-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kokofinance/apis/koko-finance-api/revisions/a5f1170af4d4?raw)