# Claim automation

Source: https://gokarla.io/docs/guides/resolve/claim-automation

# Claim automation

:::info

Claim automation lets you close Resolve claims without an agent in the loop.
You define ordered **rule sets** in the Karla portal — each rule checks claim
data with logic you control and either **automates** (refund or replacement in
your shop) or routes the claim to **manual** review. Rules are evaluated
top-to-bottom; the first match wins. Everything else falls through to your
team.

:::

## What you need

Before turning automation on:

- **Resolve enabled** on your Karla package.
- **Shop connected** with refund and replacement endpoints exposed — Karla
  acts in your commerce platform when a rule matches. See
  [Shop connection](./shop-connection).
- **Portal admin access** — only admins can view and edit Claim Automation
  settings.
- **Optional helpdesk integration** — useful when you want agents notified
  even after an automated resolution. See
  [Helpdesk integrations](./integrations/overview).

:::note
Claim Automation appears under **Settings** in the
[Karla portal](https://portal.gokarla.io/) for eligible shops. If you do not
see it, contact your account manager.
:::

## How a claim moves through automation

When a customer submits a Resolve claim, Karla evaluates your rule set against
the structured claim record — reason, resolution preference, claimed value,
shipment status, and the rest of the payload described in
[Data processing](./data-processing).

```text title="Evaluation flow"
Customer submits claim
  → Is claim automation enabled?
      No  → Manual handling (helpdesk ticket per your integration)
      Yes → Walk rules top-to-bottom
              → First rule where ALL conditions match:
                    automate → Refund or reorder in your shop (per customer preference)
                    manual   → Stop — manual handling
              → No rule matched → Manual handling
  → Safety gates may still override automation (see below)
  → Optional helpdesk notification (per your notification mode)
```

A matched **Automate** rule does **not** choose refund vs replacement. That
comes from the customer's **resolution preference** on the claim — refund,
reorder, or keep with reward. You pick which of these options customers can
choose under **Resolve → Features → Resolution options** in the portal;
refund and reorder are offered by default, keep with reward is opt-in. The
rule only decides whether Karla may act automatically or must hand off to
your team.

## Configure rules in the portal

In the [Karla portal](https://portal.gokarla.io/), open
**Settings → Claim Automation**.

### Master controls

| Control                     | What it does                                                 |
| --------------------------- | ------------------------------------------------------------ |
| **Enable claim automation** | Master on/off for automated refund and reorder               |
| **Notification mode**       | Whether automated resolutions still create a helpdesk ticket |

**Notification mode** options:

- **Notify** — create an outcome ticket in your helpdesk so agents see what
  Karla did (recommended when you want an audit trail alongside automation).
- **Silent** — resolve in your shop only; no ticket for automated outcomes.

### Rule sets

Rules are **ordered**. Karla evaluates them from top to bottom and stops at
the first match. Reorder rules with the up/down controls when priority matters.

Each rule has:

- **Action** — `Automate` or `Manual`
- **Conditions** — one or more checks; **all** must match (logical AND)

Use **Add rule** and **Add condition** to build your set. A claim that matches
no rule is handled manually — automation is strictly opt-in per matching rule.

:::tip Start conservative
Many merchants begin with a narrow **Automate** rule (e.g. low-value missing
product + refund preference) and a catch-all **Manual** rule at the bottom.
Expand automation as you gain confidence in the outcomes.
:::

## Condition fields and operators

Each condition compares one claim attribute to a value you set.

| Field                     | What it checks                                  | Operators               | Example                      |
| ------------------------- | ----------------------------------------------- | ----------------------- | ---------------------------- |
| **Claim reason**          | Which Resolve flow/reason the customer selected | equals, is one of       | `missing_product`            |
| **Resolution preference** | What the customer asked for                     | equals, is one of       | `refund`                     |
| **Claimed value**         | Monetary value of the claimed items             | `=`, `≤`, `<`, `>`, `≥` | `50` (auto-refund up to €50) |
| **Shipment status**       | Current shipment phase/status                   | equals, is one of       | `delivered`                  |

### Claim reason values

| Value in portal             | Typical flow               |
| --------------------------- | -------------------------- |
| `partial_damage`            | Defective — partial damage |
| `damage`                    | Defective — full damage    |
| `investigation`             | Not received               |
| `missing_product`           | Missing product            |
| `wrong_product`             | Wrong product              |
| `return`                    | Return                     |
| `dissatisfied_with_product` | Dissatisfied               |
| `support`                   | General support            |

Use **is one of** with comma-separated values when a rule should match
multiple reasons or preferences (e.g. `missing_product, wrong_product`).

## Example rule sets

### Tiered value gates

Route low-risk claims to automation; keep high-value orders manual.

1. **Automate** — `claimed value` ≤ `75` AND `resolution preference` equals
   `refund` AND `claim reason` is one of `missing_product, wrong_product`
2. **Manual** — no conditions (catch-all)

### Reason-based routing

Automate only the claim types your ops team trusts.

1. **Automate** — `claim reason` equals `missing_product`
2. **Manual** — `claim reason` equals `dissatisfied_with_product`
3. **Manual** — no conditions (everything else)

### Replacement only when delivered

Honor the customer's reorder request only after delivery is confirmed.

1. **Automate** — `resolution preference` equals `reorder` AND `shipment status`
   equals `delivered` AND `claimed value` ≤ `200`
2. **Manual** — no conditions

## Safety gates

Your rules define **what Karla may attempt**. Karla still runs **platform
safety gates** before executing a refund or replacement — even when a rule
matches. If a gate fails, the claim falls back to manual handling and Karla
records why.

Common automatic fallbacks:

| Outcome                    | Meaning                                               |
| -------------------------- | ----------------------------------------------------- |
| `manual_out_of_stock`      | Replacement requested but inventory is not available  |
| `manual_missing_address`   | Shipping address required for reorder is incomplete   |
| `manual_item_match_failed` | Claimed line items could not be matched to the order  |
| `manual_value_unresolved`  | Claimed value could not be calculated reliably        |
| `manual_shopify_error`     | Shop platform returned an error during refund/reorder |
| `manual_already_processed` | Another claim on this order was already auto-resolved |

Karla also treats an order as **already processed** once any claim on that
order received an automated outcome — preventing duplicate refunds or
replacements from repeat submissions.

These gates are not configurable in the portal today; they protect your shop
regardless of how permissive your rules are.

## Customer resolution preference

What the customer selects in Resolve (when you expose the choice) drives the
**action** Karla takes on an automated match:

| Preference         | Automated action                                                       |
| ------------------ | ---------------------------------------------------------------------- |
| `refund`           | Issue a refund in your shop                                            |
| `reorder`          | Create a replacement order                                             |
| `keep_with_reward` | Available as a rule condition; use when you offer keep-item incentives |

The options customers can pick from are configurable under
**Resolve → Features → Resolution options** in the portal — refund and
reorder are enabled by default; enable keep with reward there to offer it.
You control whether customers see the preference picker per flow in
[Flows and customization](./flows-and-customization). If the picker is
hidden, Resolve defaults to `refund` for the submitted claim; if only one
option is configured, that option is submitted automatically.

## API access

Claim automation settings are available programmatically for headless or
multi-shop setups:

```bash title="GET /v1/shops/{slug}/settings/triggers/claim-resolution"
curl -X GET "https://api.gokarla.io/v1/shops/{slug}/settings/triggers/claim-resolution" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```bash title="PATCH /v1/shops/{slug}/settings/triggers/claim-resolution"
curl -X PATCH "https://api.gokarla.io/v1/shops/{slug}/settings/triggers/claim-resolution" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": true,
    "notify_mode": "notify",
    "rules": [
      {
        "action": "automate",
        "conditions": [
          { "field": "claim_reason", "op": "equals", "value": "missing_product" },
          { "field": "claimed_value", "op": "<=", "value": 75 }
        ]
      }
    ]
  }'
```

A `PATCH` replaces the full `rules` array when you include it. Omit fields you
want to leave unchanged.

## Troubleshooting

**Automation never runs**

- Confirm **Enable claim automation** is on.
- Confirm at least one **Automate** rule exists and its conditions match real
  claim data (check reason codes and claimed value).
- Confirm your shop connection supports refunds and replacements.

**Rule matches but claim stays manual**

- Check the claim's **resolution outcome** in the API — a safety gate may have
  blocked execution (out of stock, already processed, etc.).
- Confirm the customer selected a resolution preference your rule allows.

**Agents not notified after automation**

- Set **Notification mode** to **Notify** if you expect helpdesk tickets for
  automated outcomes.
- Confirm your helpdesk integration is connected and enabled.

**Wrong priority between rules**

- Remember **first match wins**. Move stricter or higher-priority rules above
  broader catch-all rules.

## Where to next

- [Integration and automation](./integration-and-automation) — helpdesk routing
  and custom transformations beyond claim automation.
- [Shop connection](./shop-connection) — what Resolve needs from your shop.
- [Data processing](./data-processing) — the claim payload rules evaluate.
- [Flows and customization](./flows-and-customization) — customer-facing
  resolution preference and flow toggles.
- [Helpdesk integrations](./integrations/overview) — tickets for manual claims
  and notify-mode outcomes.
- [Portal → Resolve](/docs/guides/portal/resolve) — claims analytics and the
  Claims table.