# Zendesk

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

# Zendesk

:::info

The Zendesk integration creates a structured ticket in your Zendesk instance
whenever a customer submits a Resolve claim. Photos, affected items, order
context, and the customer's resolution preference are attached automatically.

:::

## What you need

Before you start, gather:

- **Zendesk admin access** — to create an API token.
- **Your Zendesk subdomain** — the hostname of your instance, e.g.
  `yourbrand` in `https://yourbrand.zendesk.com`.
- **An agent email address** — the Zendesk user Karla will authenticate as.
  Must belong to an agent or admin with permission to create tickets.
- **A Zendesk API token** — used together with the agent email for Basic
  authentication.

Karla uses **Basic authentication** with the combination `{email}/token:{api_token}`.
This is Zendesk's standard API auth pattern — not your account password.

## Steps

### 1. Enable API token access in Zendesk

In Zendesk, open **Admin Center** and navigate to **Apps and integrations →
Zendesk API**.

On the **Settings** tab, make sure **Token Access** is enabled.

### 2. Create an API token

Still under **Zendesk API**, open the **API tokens** tab and click **Add API
token**.

Name it something recognizable — e.g. `Karla Resolve Integration` — and copy
the token immediately. Zendesk only shows it once.

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

### 3. Note your Zendesk endpoint

Your Zendesk endpoint is the base URL of your instance:

```json title="Zendesk endpoint"
https://your-subdomain.zendesk.com
```

Replace `your-subdomain` with your actual Zendesk subdomain. Karla uses this
to identify your Zendesk instance and route API calls to the correct account.

### 4. Connect Zendesk in the Karla portal

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

Enter the following:

| Field         | Value                                                       |
| ------------- | ----------------------------------------------------------- |
| **Endpoint**  | Your Zendesk base URL, e.g. `https://yourbrand.zendesk.com` |
| **Email**     | The agent email address Karla will authenticate as          |
| **API token** | The token you created in step 2                             |

Click **Save**. Karla validates the credentials against your Zendesk instance
using Basic authentication before storing them.

Once saved, toggle the integration on. New Resolve claims will create tickets
in Zendesk automatically.

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

## What Karla creates in Zendesk

When a customer submits a Resolve claim, Karla opens a Zendesk ticket with:

- **Subject and description** mapped from the claim reason and customer notes.
- **Requester** set to the customer email from the order.
- **Custom fields and tags** reflecting the Resolve flow type, resolution
  preference, and shipment phase (configured per shop).
- **Attachments** — claim photos and signatures uploaded as ticket attachments.
- **Order and shipment context** in the ticket body — order number, carrier,
  tracking number, affected line items.

Your agents see a complete ticket without looking up the order elsewhere.

## Troubleshooting

**Authentication failed after saving**

- Confirm the email belongs to an active agent or admin in Zendesk.
- Confirm the API token was copied in full — no leading or trailing spaces.
- Confirm Token Access is enabled in Zendesk Admin Center.
- Use the `{email}/token:{api_token}` format — the literal word `token` between
  the email and the API token is required by Zendesk.

**Tickets 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.
- Check that the agent email has permission to create tickets in Zendesk.

**Wrong Zendesk instance**

- Double-check the endpoint URL matches your subdomain exactly —
  `https://your-subdomain.zendesk.com` with no trailing path.

## Where to next

- [Helpdesk integrations overview](./overview) — other connection options.
- [Gorgias](./gorgias) — native Gorgias 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.