Kustomer#
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.
yourbrandinhttps://yourbrand.kustomerapp.com. Karla uses it to route API calls tohttps://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.
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:
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, 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.
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.
What Karla creates in Kustomer#
When a customer submits a Resolve claim, Karla:
- 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. - 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. - 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) — nohttps://, no.kustomerapp.com, no trailing path.
Where to next#
- Helpdesk integrations overview — other connection options.
- Zendesk — native Zendesk integration setup.
- Gorgias — native Gorgias integration setup.
- Dixa — native Dixa integration setup.
- Webhooks — push claim events to a custom endpoint instead.
- Data processing — the full claim payload shape.
- Integration and automation — auto-refunds, routing rules, and custom transformations.