# Gorgias

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

# Gorgias

:::info

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

You can also embed a Resolve entry point directly in your Gorgias Help Center
so customers start a claim from your support site.

:::

## What you need

Before you start, gather:

- **Gorgias admin access** — to create an API key.
- **Your Gorgias account domain** — the hostname of your instance, e.g.
  `yourbrand` in `https://yourbrand.gorgias.com`.
- **An agent email address** — the Gorgias user Karla will authenticate as.
  Must belong to an agent or admin with permission to create tickets.
- **A Gorgias API key** — created under **Settings → REST API**.

Karla uses **Basic authentication** with your email as the username and the
API key as the password (`email:api_key`). This is Gorgias's standard REST
API auth pattern — not your account password.

## Connect Gorgias for ticket creation

### 1. Create an API key in Gorgias

In Gorgias, open **Settings → REST API** and click **Create API key**.

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 user associated with the API key must have permission to create tickets
and access customer records. Admin or full agent roles work best.

### 2. Note your Gorgias endpoint

Your Gorgias endpoint is the base URL of your account:

```json title="Gorgias endpoint"
https://your-account.gorgias.com
```

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

### 3. Connect Gorgias in the Karla portal

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

Enter the following:

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

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

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

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

## What Karla creates in Gorgias

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

- **Subject and message body** mapped from the claim reason and customer notes.
- **Customer** matched or created from the order email.
- **Tags and custom fields** reflecting the Resolve flow type, resolution
  preference, and shipment phase (configured per shop).
- **Attachments** — claim photos and signatures uploaded to the ticket.
- **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.

## Embed Resolve in your Help Center (optional)

In addition to ticket creation, you can surface a Resolve entry point inside
your Gorgias Help Center. Customers click a branded tile and are taken to
the Resolve flow for your shop — pre-localized based on the Help Center
language.

Supported Help Center languages: English, German, French, Spanish, Italian,
Dutch, Danish, and Polish.

### 1. Share your Help Center URLs with Karla

The Help Center embed is activated per domain. Send Karla the URLs where you
want the Resolve tile to appear — for example your Help Center home page,
contact page, or return-policy articles.

Karla whitelists those URLs before the widget goes live.

### 2. Add the Gorgias SDK to your Help Center

Karla provides a script tag for your shop. Add it to your Gorgias Help
Center custom code (typically under **Settings → Help Center → Advanced** or
your theme's custom HTML/JS section):

```html
<script
  src="https://gorgias-sdk.gokarla.io/latest/bundle.min.js"
  data-shop-slug="my-shop-slug"
></script>
```

Replace `my-shop-slug` with your Karla shop slug (find it in the
[portal](https://portal.gokarla.io/) under your shop profile).

When a customer clicks the tile, they are redirected to your Resolve flow at
`https://app.gokarla.io/resolve/{shop-slug}/finder`, with the language taken
from the Help Center URL.

:::tip Help Center + ticket integration together
Most merchants use both: the Help Center tile drives customers into Resolve
self-service, and the native integration creates structured Gorgias tickets
when they submit a claim. They complement each other — you do not need to
pick one or the other.
:::

## Troubleshooting

**Authentication failed after saving**

- Confirm the email belongs to an active agent or admin in Gorgias.
- Confirm the API key was copied in full — no leading or trailing spaces.
- Confirm the key was created under **Settings → REST API**, not expired or
  revoked.
- Basic auth uses `email:api_key` — your account password will not work.

**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 Gorgias.

**Wrong Gorgias account**

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

**Help Center tile not showing**

- Confirm Karla has whitelisted your Help Center URLs.
- Confirm the script tag includes the correct `data-shop-slug`.
- Confirm the SDK script is present in your Help Center custom code and the
  page has been published.

## Where to next

- [Helpdesk integrations overview](./overview) — other connection options.
- [Zendesk](./zendesk) — native Zendesk integration setup.
- [Webhooks](./webhooks) — push claim events to a custom endpoint instead.
- [Data processing](../data-processing) — the full claim payload shape.
- [Integrate in your shop](../integrate-in-your-shop) — embed Resolve on your
  storefront via the Browser SDK.