---
title: "Calculate Card Value"
method: POST
path: "/api/v1/intelligence/value"
tags: ["Intelligence"]
---

# Calculate Card Value

`POST /api/v1/intelligence/value`

## 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/value`
- Auth: API key in header `X-API-Key`

Calculate the financial value of a credit card.

Always deterministic (no verbose mode). If card_name is provided, looks up
the card in the database and uses actual rewards multipliers, benefits, and
points program data. Otherwise, uses basic calculation with the provided
annual_fee and spending values.

## Headers

- `authorization` string, nullable

## Request body

- V1CardValueRequest: Request for POST /api/v1/intelligence/value
  - `card_name` string, nullable: Card name to look up. If provided, uses actual card benefits from DB.
  - `annual_spending` number, required: Total annual spending on this card
  - `annual_fee` number, required: Annual fee for the card
  - `monthly_spending` object, nullable: Per-category monthly spending
  - `sign_on_bonus` number, nullable: Sign-on bonus amount
  - `sign_on_bonus_type` string, nullable: Sign-on bonus type (points or cashback)
  - `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)