Cost Savings

July 28, 2026 · View on GitHub

Use case

Returns a rollup of savings attributed to multi-objective (cost-aware) routing — how much cheaper the chosen gateway was versus the plain success-rate head, trended over the window.

Authentication

Protected. Send either Authorization: Bearer <jwt_token> or x-api-key: <api_key>. In sandbox, also send x-feature: decision-engine.

For local development, start with:

export BASE_URL=http://localhost:8080
export AUTH_HEADER="Authorization: Bearer <jwt_token>"
export TENANT_HEADER="x-tenant-id: public"
# Sandbox only:
# export BASE_URL=https://sandbox.hyperswitch.io
# export FEATURE_HEADER="x-feature: decision-engine"

Request

  • Method and path: GET /analytics/cost-savings
  • Parameters:
    • x-tenant-id (header, required, string) — see Environment setup.
    • range (query, optional, string)
    • start_ms (query, optional, integer)
    • end_ms (query, optional, integer)
    • page (query, optional, integer)
    • page_size (query, optional, integer)
    • payment_method_type (query, optional, string)
    • payment_method (query, optional, string)
    • card_network (query, optional, string)
    • card_is_in (query, optional, string)
    • currency (query, optional, string)
    • country (query, optional, string)
    • auth_type (query, optional, string)
    • gateway (query, optional, string)
    • payment_id (query, optional, string)
    • request_id (query, optional, string)
    • route (query, optional, string)
    • status (query, optional, string)
    • flow_type (query, optional, string)
    • routing_approach (query, optional, string)
    • exclude_routing_approach (query, optional, string)
    • error_code (query, optional, string)
  • Body: Optional query parameters include range and currency. Omit currency to aggregate across all currencies present in the window.

Example

curl "$BASE_URL/analytics/cost-savings?range=1w&currency=USD" \
  --header "$AUTH_HEADER" \
  --header "$TENANT_HEADER"

Response

{
  "merchant_id": "merchant_demo",
  "range": "1w",
  "currency": "USD",
  "available_currencies": [
    { "currency": "USD", "decision_count": 4820 },
    { "currency": "EUR", "decision_count": 612 }
  ],
  "trend": [
    { "bucket_ms": 1784112000000, "saved_value": 128.42 }
  ],
  "totals": {
    "saved_value": 962.3,
    "cost_won_count": 341,
    "total_decisions": 4820
  }
}

Notes

  • Analytics reads are ClickHouse-backed and merchant-scoped by the authenticated context.
  • Use range=15m|1h|12h|1d|1w or start_ms plus end_ms for a custom window.
  • saved_value is money saved versus the SR head's cost, in the requested (or aggregated) currency.
  • Requires cost data ingestion to have fitted a cost model — otherwise cost_won_count stays at zero.