Gorgias API Guide: Keys, OAuth2, Rate Limits, Webhooks and MCP

Gorgias opens its REST API on every Helpdesk plan, so the cheapest way in is Starter at $10 a month, billed monthly only. Bills grow with ticket volume, with overage per ticket past the plan's allowance; our Gorgias pricing guide has the full table. You authenticate with HTTP Basic auth: the account email as username, an API key as password. Self-serve plans allow 2 requests per second, and the custom Enterprise plan allows 4. Public apps must switch to OAuth2 and pass a review. HTTP integrations push ticket events out. The Gorgias MCP plugs Claude or ChatGPT into the account. Our verdict is simple. The API is broad and well documented, but plan every sync around the rate limit.

Gorgias gives developers three entry points, and picking the wrong one costs rework. The REST API is for your own code: it reads and writes tickets, messages, customers, macros, rules, tags, views, teams, jobs and statistics against a base URL of your account subdomain, documented as an OpenAPI 3.1.0 spec. HTTP integrations run the other direction, firing a request at your server when something happens in the helpdesk. The MCP lets an outside AI assistant work inside the account as a signed-in user. All three are available on every Helpdesk plan.

Step 1: create an API key and send your first request

Open the REST API page in Settings. It shows three values: the base API URL, the username (your email address) and the API key, which acts as the password. Only the account owner and admins can see these credentials or create keys, and each admin gets a personal key. A key grants full access to the account's data, and resetting it invalidates the old one at once^[1]. A Run in Postman button imports Gorgias's Postman collection with your domain, email and key already filled in, which is the fastest way to explore.

A safe first call is a read. GET /api/account returns your domain, status and account settings such as business hours, and GET /api/users/0 returns the current user. Writing comes next, with two traps. A ticket cannot exist without a message, so POST /api/tickets needs message fields and answers with a 201. A message created with sent_datetime already filled is stored as history and not sent. Leave it empty and Gorgias sends it asynchronously, but an email only goes out if its sender address matches a connected email integration.

Errors follow ordinary HTTP codes. A 401 usually means an invalid, expired or missing token. A 403 means the key lacks permission, which depends on the role of the user behind it. A 409 means you tried to create or update a resource with an identifier already in use. Merged customers return a 301 redirect with an empty body rather than a 404, so follow redirects on customer endpoints.

Step 2: build a public app with OAuth2

Anything you plan to list for other merchants follows a fixed path, and Basic auth is not allowed on it. Gorgias makes OAuth2 mandatory for third-party apps, with one-click install and no manual HTTP integration installs. The payoff for merchants is visibility: with OAuth2 they see which data an app can reach and can revoke it by disconnecting the app. The order is:

1. Register on the Developer Portal and create a draft app.
2. Get a sandbox: start a trial account and ask Gorgias's tech partners team to convert it to a developer account.
3. Set up OAuth2 and build against the sandbox.
4. Submit the app with testing instructions and a test account for review.

The flow uses your subdomain's /oauth/authorize URL and the /oauth/token endpoint, with a client ID and secret bound to each app. Access tokens expire after 24 hours; the refresh token does not expire, and requesting it needs the offline scope^[2]. Gorgias scopes come as read and write pairs per object, statistics is read only, and write:all is deprecated, so request granular scopes from day one. If a merchant deactivates your app, the whole OAuth2 flow has to run again.

Review is done by Gorgias's tech partnership team, which checks that the app works and fits its expectations. An approved app appears both in the in-product App Store and on the public App Store page. A rejected one gets a list of fixes. Gorgias also asks partners to drop scopes they do not need and to cope with high-volume accounts during peaks such as Black Friday.

Step 3: stay under the rate limit and page through results

Gorgias meters calls with a leaky bucket: a fixed budget per window that refills over time. API-key integrations get 40 requests in a 20-second window and OAuth2 apps get 80^[3]. Gorgias's pricing page states the same ceiling as 2 requests per second on the four self-serve plans and 4 on the custom plan. Go over it and the call fails with 429 Too Many Requests. Each response carries a Retry-after header with the seconds to wait and an X-Gorgias-Account-Api-Call-Limit header showing calls used against the budget.

Lists use cursor pagination. You pass cursor, limit and order_by, and read meta.next_cursor from each response until it runs out. The limit defaults to 30 and goes up to 100 on most lists. That choice matters for exports. Reading 100,000 tickets at 100 a page takes 1,000 requests, or 500 seconds at 2 a second, a little over 8 minutes by our arithmetic. Left at the default of 30, the same export needs 3,334 requests and close to 28 minutes.

For bulk writes, hand the work to Gorgias instead of looping. POST /api/jobs schedules a background job, such as applying a macro to a set of tickets and closing them, which can take minutes or hours depending on size. Its status is readable through the API. Cancelling a job stops it, but changes already applied are not reverted.

Step 4: push ticket events out with HTTP integrations

Gorgias's webhooks are HTTP integrations. Owners and admins create them in the UI or through POST /api/integrations, choosing a URL, method (GET, POST, PUT or DELETE), headers and a body. Triggers include events such as ticket created, ticket updated, message created, ticket self-unsnoozed and message failed (the API reference also lists assignee updated, status updated and ticket handed over). The same mechanism powers sidebar widgets: your service exposes an endpoint that returns data for a customer's email address, and the widget appears only when that customer has data. Each HTTP integration needs its own widget.

Delivery is less forgiving than many webhook systems. Each request has a 5-second timeout, and Gorgias retries up to three times, after 10, 20 and 40 seconds, only in some failure cases^[4]. A 429 or 500 from your side is not retried at all. After 500 consecutive failures, Gorgias disables the integration. So answer fast and queue the real work. Our Gorgias integrations guide covers the partner apps built on this same mechanism.

Step 5: connect Claude or ChatGPT through the Gorgias MCP

The Gorgias MCP is a remote server at mcp.gorgias.com that an outside assistant reaches through OAuth; Gorgias says setup takes about five minutes. Since 29 October 2026 it has been an official connector in the Claude and ChatGPT directories, and Cursor or other MCP clients connect by URL. It works on every Helpdesk plan at no extra cost, needs no AI Agent subscription, and Gorgias still calls it open beta. Each connection reaches one Gorgias account, and data it retrieves falls under the AI provider's terms, not Gorgias's.

The assistant acts as you. Your role limits it. Every MCP tool has a minimum role, and changing custom fields, widgets or satisfaction surveys needs Admin, while the read-only SQL tool over analytics needs Lead or above. Guardrails are built in: new rules and AI Agent actions arrive turned off, guidance, skills and Help Center articles save as drafts, and macros are archived rather than deleted. Two cautions remain. Three tools run AI Agent actions against the live store even in a test, and whether the assistant asks before messaging a customer depends on Claude's or ChatGPT's settings. Our Gorgias AI playbook covers AI Agent itself.

Changes that break old integrations, and the license terms

Code written against older docs can fail quietly, so check these changelog items. Since December 2024 Gorgias enforces TLS 1.2 or higher. Ticket subjects longer than 998 characters return HTTP 400. Attachment URLs returned by the API are no longer directly reachable: fetch them through the Downloads API, which answers with a 307 redirect to a timed, signed URL. Audit-log events are kept for 12 months, and older ones are permanently deleted, including through the events endpoints. The views-items cursor format also changed in April 2024, so reset any stored cursors.

The biggest recent change hits anyone archiving email. From 8 September 2026, 30 days after an email is sent or received, its headers are set to null and the original HTML and text bodies are archived when stripped versions exist, reachable through body_url. The policy ran retroactively over historical email. The API itself sits under a separate API License Agreement: no license fee, Delaware law, disputes in California courts, and Gorgias's liability under it capped at 100 US dollars. Ending that license leaves your subscription agreement untouched.

The bottom line

The Gorgias API suits e-commerce teams that need to sync tickets, customers and order context with their own systems, and it costs nothing beyond the Helpdesk plan you already pay for. Its weak points are operational, not missing features. Budget for 2 requests per second, keep webhook endpoints under the 5-second timeout, and copy email headers within 30 days if your records need them. Agencies building for many merchants should start with OAuth2 and granular scopes; everyone else can begin with an admin key and Postman.