# Kustomer

Source: https://gokarla.io/docs/guides/resolve/integrations/kustomer

# Kustomer

:::info

The Kustomer integration creates a structured conversation in your Kustomer
account whenever a customer submits a Resolve claim. Karla matches or creates
the customer, opens a conversation, and attaches the full claim — photos,
affected items, order context, and resolution preference — as an internal note
your agents can act on immediately.

:::

## What you need

Before you start, gather:

- **Kustomer admin access** — to create an API key with the right permissions.
- **Your Kustomer organization name** — the label in your Kustomer app URL, e.g.
  `yourbrand` in `https://yourbrand.kustomerapp.com`. Karla uses it to route
  API calls to `https://yourbrand.api.kustomerapp.com`.
- **A Kustomer API key** — created under **Settings → Security → API Keys**.
  The key needs permission to read and create customers, create conversations,
  and create notes.

Karla authenticates with **bearer-token authentication**
(`Authorization: Bearer {api_key}`) — not your Kustomer account password.

## Connect Kustomer for conversation creation

### 1. Create an API key in Kustomer

In Kustomer, open **Settings → Security → API Keys** and create a key with
access to customers, conversations, and notes.

Name it something recognizable — e.g. `Karla Resolve Integration` — and copy
the key immediately.

:::warning
Treat the API key like a password. Do not share it in email or chat — enter
it only in the Karla portal.
:::

The key needs at least these permission sets (or their legacy equivalents):

| Permission          | Used for                                        |
| ------------------- | ----------------------------------------------- |
| Customer read       | Look up existing customers by email             |
| Customer create     | Create a customer when none exists              |
| Conversation create | Open a new conversation for the customer        |
| Note create         | Attach the structured claim as an internal note |

### 2. Note your organization name

Your organization name is the label in your Kustomer app URL:

```text title="Kustomer organization name"
yourbrand        (from https://yourbrand.kustomerapp.com)
```

Enter only the organization name (`yourbrand`) in the portal — not the full
URL. Karla appends `.api.kustomerapp.com` and uses it to route API calls to
the correct Kustomer workspace.

### 3. Connect Kustomer in the Karla portal

In the [Karla portal](https://portal.gokarla.io/), navigate to
**Settings → Integrations** and select **Kustomer**.

Enter your credentials under **API Configuration**:

| Field            | Value                                         |
| ---------------- | --------------------------------------------- |
| **API Key**      | The key you created in step 1                 |
| **Organization** | Your Kustomer organization name (`yourbrand`) |

Save the credentials. Karla validates against your Kustomer workspace using
bearer authentication before storing.

Once credentials are saved, toggle the integration on. New Resolve claims will
create conversations in Kustomer automatically.

:::note
If you do not see Kustomer under **Settings → Integrations**, contact your
account manager — the integration may need to be enabled for your shop first.
:::

### 4. Optional settings

A few extra settings live alongside the connection, all optional:

- **Default team ID** — for Kustomer workspaces using teams, the team new
  conversations should be assigned to. Leave empty to let Kustomer route through
  its own queues.
- **Carrier affidavit** — saving a postal **sender address** (plus optional
  **type of goods** and **main carrier**) attaches a carrier affidavit PDF to
  investigation (not-received) conversations, ready for carrier disputes.
  Clearing the sender address removes it.
- **Ticket templates** — customize the conversation name, note body, tags, and
  attachments per claim reason. See
  [Helpdesk integrations → Ticket templates](./overview#ticket-templates).

## What Karla creates in Kustomer

When a customer submits a Resolve claim, Karla:

1. **Matches or creates the customer** — looks up the order email in Kustomer
   (`GET /v1/customers/email={email}`). If no match exists, Karla creates a new
   customer record with the shipping name and email from the order.
2. **Opens a conversation** — creates a new conversation on that customer
   (`POST /v1/customers/{id}/conversations`) with tags reflecting the Resolve
   flow type, resolution preference, and shipment phase.
3. **Attaches the claim as an internal note** — posts the structured claim
   details to the conversation (`POST /v1/notes`) so agents see everything in
   one place without a public customer-facing message.

The note includes:

- **Subject and body** mapped from the claim reason and customer notes.
- **Tags** reflecting the Resolve flow type, resolution preference, and
  shipment phase (configured per shop).
- **Attachments** — claim photos and signatures linked to the conversation.
- **Order and shipment context** — order number, carrier, tracking number,
  affected line items.

Your agents see a complete conversation with an internal note — no copy-pasting,
no looking up the order elsewhere.

## Troubleshooting

**Authentication failed after saving**

- Confirm the API key was copied in full — no leading or trailing spaces.
- Confirm the key was created under **Settings → Security → API Keys** and is
  not expired or revoked.
- Confirm the **Organization** field matches your Kustomer workspace name
  exactly — the label from `https://{org}.kustomerapp.com`, not the full URL.

**Conversations not appearing**

- Confirm the integration toggle is enabled in the Karla portal.
- Confirm Resolve is enabled and customers are submitting claims through an
  active Resolve flow.
- Confirm the API key has customer, conversation, and note permissions.

**Customer lookup issues**

- Karla matches customers by the order email. If the email in Kustomer differs
  from the order (aliases, typos), Karla creates a new customer record instead
  of linking to an existing one.

**Wrong Kustomer workspace**

- Double-check the **Organization** field is just the label (`yourbrand`) — no
  `https://`, no `.kustomerapp.com`, no trailing path.

## Where to next

- [Helpdesk integrations overview](./overview) — other connection options.
- [Zendesk](./zendesk) — native Zendesk integration setup.
- [Gorgias](./gorgias) — native Gorgias integration setup.
- [Dixa](./dixa) — native Dixa integration setup.
- [Webhooks](./webhooks) — push claim events to a custom endpoint instead.
- [Data processing](../data-processing) — the full claim payload shape.
- [Integration and automation](../integration-and-automation) — auto-refunds,
  routing rules, and custom transformations.