Classify a billing dispute

What kind of billing dispute does message raise?

You need to sort incoming billing complaints into a fixed set of dispute types so each can be routed to the right handler or template.

Explore this recipe interactively · Source and implementation guide

Use dispute-kind in TypeScript

Install with npm install jev-recipes. Requires Node.js 22.9 or newer and ES modules. Set TYPESAFE_API_KEY in your server environment for live calls, which send input to TypeSafe and use API quota. See the installation guide.

import { disputeKind } from 'jev-recipes/dispute-kind';

const result = await disputeKind({
  "message": "I cancelled my Pro plan on August 28th and got the confirmation email, but my card was charged $49 again on September 1st. Please reverse it and confirm the account is actually closed this time.",
  "minConfidence": 0.8
});
console.log(result);

Input contract

Field	Type	Needed
message	string	Required
minConfidence	number	Optional

Full input and result schemas

{
  "input": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "message": {
        "type": "string"
      },
      "minConfidence": {
        "type": "number",
        "minimum": 0,
        "maximum": 1
      }
    },
    "required": [
      "message"
    ]
  },
  "result": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "model": {
        "type": "string"
      },
      "usage": {
        "type": "object",
        "properties": {
          "input_tokens": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "output_tokens": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "input_tokens",
          "output_tokens"
        ],
        "additionalProperties": false
      },
      "status": {
        "type": "string",
        "enum": [
          "ready",
          "review"
        ]
      },
      "verdict": {
        "type": "string",
        "enum": [
          "duplicate_charge",
          "wrong_amount",
          "unrecognized_charge",
          "refund_not_received",
          "cancellation_not_honored",
          "other",
          "unclear"
        ]
      },
      "confidence": {
        "type": "number",
        "minimum": 0,
        "maximum": 1
      },
      "probabilities": {
        "type": "object",
        "propertyNames": {
          "type": "string",
          "enum": [
            "duplicate_charge",
            "wrong_amount",
            "unrecognized_charge",
            "refund_not_received",
            "cancellation_not_honored",
            "other",
            "unclear"
          ]
        },
        "additionalProperties": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "required": [
          "duplicate_charge",
          "wrong_amount",
          "unrecognized_charge",
          "refund_not_received",
          "cancellation_not_honored",
          "other",
          "unclear"
        ]
      }
    },
    "required": [
      "model",
      "usage",
      "status",
      "verdict",
      "confidence",
      "probabilities"
    ],
    "additionalProperties": false
  }
}

Saved example result

This hand-authored response demonstrates the contract. It is not a model accuracy measurement. Run it without an API key: npx jev-recipes demo dispute-kind.

{
  "model": "demo-fixture",
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0
  },
  "status": "ready",
  "verdict": "cancellation_not_honored",
  "confidence": 0.88,
  "probabilities": {
    "duplicate_charge": 0.03,
    "wrong_amount": 0.02,
    "unrecognized_charge": 0.02,
    "refund_not_received": 0.02,
    "cancellation_not_honored": 0.88,
    "other": 0.01,
    "unclear": 0.02
  }
}

Evaluation evidence

Fixture only

No verified live accuracy measurement is available. Evaluate representative cases before using this decision in your workflow.

Use the evaluation guide to measure this decision on your own labeled cases.

Limitations

Classifies what the customer claims, not whether the claim is valid. Verify charges, refunds, and cancellations against your billing records in code.
A message that raises several disputes is classified by the one it presses most; split multi-issue messages in code when each matters.
Amounts and dates in the message are treated as part of the customer's claim, not checked.

Related recipes

issue-impact: Use issue-impact to grade how badly a reported problem affects the customer, rather than what kind of billing dispute it is.
route: Use route when the destinations are caller-defined queues rather than this fixed set of billing dispute types.