Available · v1

Returns Intelligence

Send a customer's return request with whatever order and policy context you have. Get back the reason, a priority, an eligibility status, and a suggested next step your workflow can act on.

  • Classify returns into eight documented reasons
  • Apply your return window with exact arithmetic, not guesswork
  • Route exceptions, contradictions, and unclear requests to a person
  • Suggested actions only; Kovca never approves or rejects on its own
Try it in the playgroundAPI referenceGuides
Request body
{
  "customer_message": "I bought these headphones 45 days ago and the left speaker stopped working. I'd like a refund.",
  "product": {
    "name": "Wireless Headphones",
    "category": "electronics"
  },
  "order": {
    "days_since_delivery": 45
  },
  "return_policy": {
    "window_days": 30,
    "exceptions": [
      "Defective products may qualify for additional review"
    ]
  }
}
Response · 200 OK
{
  "request_id": "req_3nWq8ZtLs2KfP0aV",
  "reason": "defective",
  "priority": "medium",
  "suggested_action": "manual_review",
  "requires_human_review": true,
  "eligibility": {
    "status": "requires_review"
  },
  "signals": [
    "outside_return_window",
    "policy_exception_may_apply",
    "reported_defect"
  ],
  "missing_information": []
}
The problem

Return requests arrive as free text

Customers describe returns in their own words, often without order details or a clear reason. Teams spend time working out what happened, whether the policy covers it, and what to do next.

Reason and priority
Defective, damaged, wrong item, not as described, changed mind, missing parts, delivery issue, or other, plus an operational priority.
Policy-aware eligibility
Compares days since delivery to your return window and flags supplied exceptions that may apply. No policy means no eligibility verdict.
Actionable signals
Documented signal codes and missing-information codes so your system knows what to ask for or escalate.
Use cases

Where teams use it

  • Ecommerce help desks
  • Returns portals
  • Marketplace operations
  • Warranty pre-screening
Integrate

One HTTP call

const response = await fetch("https://kovca.io/api/v1/returns/triage", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KOVCA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "customer_message": "I bought these headphones 45 days ago and the left speaker stopped working. I'd like a refund.",
    "product": {
      "name": "Wireless Headphones",
      "category": "electronics"
    },
    "order": {
      "days_since_delivery": 45
    },
    "return_policy": {
      "window_days": 30,
      "exceptions": [
        "Defective products may qualify for additional review"
      ]
    }
  }),
});

if (!response.ok) {
  const { error, request_id } = await response.json();
  throw new Error(`${error.code}: ${error.message} (${request_id})`);
}

const { reason, suggested_action, eligibility, requires_human_review } = await response.json();

Related APIs

  • Catalog Matching

    Decide whether two product records are the same item, a different variant, or a different product.

  • Compatibility Intelligence

    Determine whether two products work together using structured specifications, compatibility rules, and intelligent evaluation.

  • Listing Intelligence

    Check product listings for contradictions, missing attributes, unsupported claims, and your listing requirements before publication.

  • Warranty Intelligence

    Classify warranty claims, check them against the warranty terms you supply, and get the next workflow step.