Gorgias API Explained (Auth, Rate Limits & Endpoints)

Authentication: HTTP Basic with your email and API key

Gorgias authenticates the REST API with plain HTTP Basic authentication. There is no bearer-token dance and no per-request signing for the standard API-key path — you send your account email as the username and your API key as the password, base64-encoded into a single Authorization: Basic header, over HTTPS.

You find the credentials in one place. Per the Gorgias REST API credentials guide, click the Settings gear in the bottom-left, open Account, then REST API. Under API Access & Credentials you get three fields:

1. Base API URL — always https://{your-domain}.gorgias.com/api/, where {your-domain} is your account subdomain. Every request is account-scoped by that hostname.
2. Username — your Gorgias account email address.
3. Password (API Key) — the key itself. If none exists yet, the field shows a Create API Key button; a Reset button next to it invalidates the old key and issues a new one.

There is also a Run in Postman button that imports the full Gorgias collection with your credentials pre-filled, which is the fastest way to browse the surface area before you write any code. A minimal live call looks like this:

# GET the most recent ticket from your account
curl -u '[email protected]:YOUR_API_KEY' \
  'https://yourstore.gorgias.com/api/tickets?limit=1'

For anything customer-facing or multi-tenant, Gorgias also supports OAuth2, which — beyond being the right choice for a shared app — buys you a higher rate ceiling, covered next.

Rate limits: the leaky bucket, 40 vs 80 per 20 seconds

Gorgias rate-limits with a leaky-bucket algorithm: you can burst up to a ceiling, and the bucket drains at a fixed rate so capacity replenishes over the window. The exact ceilings, from the official rate-limits reference, depend on how you authenticated:

Two things follow from this. First, if you are building a real integration that will move volume, OAuth2 doubles your throughput versus a raw API key — that alone is often reason enough to do the OAuth work. Second, when you go over, Gorgias returns HTTP 429 Too Many Requests, and it hands you exactly what you need to recover gracefully:

• Retry-After — the number of seconds to wait before retrying.
• X-Gorgias-Account-Api-Call-Limit — your live usage as a ratio, e.g. 10/80, so you can back off before you hit the wall rather than after.

Any robust client should read both headers on every response, sleep for Retry-After seconds on a 429, and ideally throttle itself as X-Gorgias-Account-Api-Call-Limit approaches the ceiling. Do not hard-code a fixed sleep and hope — the leaky bucket means your effective headroom shifts with recent traffic.

Core endpoints: the resources worth knowing

The API is organized around the objects you already recognize from the helpdesk. All paths hang off https://{domain}.gorgias.com/api/, accept and return JSON, and follow the usual GET / POST / PUT / DELETE conventions. The resources you will reach for most:

• /api/tickets — the central object. List, retrieve, create, and update tickets; filter and paginate with query params like limit, order_by, and cursor-based pagination.
• /api/tickets/{id}/messages (and /api/messages) — the individual messages inside a ticket, which is where replies are read and written.
• /api/customers — the people contacting you, with their contact points and attached data.
• /api/users — agents and other Gorgias users (useful for assignment and reporting).
• /api/tags — the tag taxonomy; pair this with Gorgias tags if you are syncing labels to another system.
• /api/macros — the saved reply templates behind Gorgias macros.
• /api/integrations — where HTTP Integrations (webhooks) are managed programmatically.

The full object definitions, every filter, and pagination details live in the Gorgias API reference. For a hands-on tour of authenticating and paging through tickets, our how to use the Gorgias API guide is the companion how-to.

Webhooks: HTTP Integrations and their trigger events

Gorgias does not use the word "webhook" in its UI — it calls outbound event callbacks HTTP Integrations. Per the HTTP Integrations documentation, you create one under Account → HTTP integration → Manage → Add HTTP integration, where you set the target URL, the HTTP method (GET, POST, PUT, or DELETE), and the events that should fire it. The available triggers are:

• Ticket created
• Ticket updated
• Ticket self unsnoozed
• Ticket message created
• Ticket message failed
• Ticket assignment updated and Ticket status updated — note these two are mutually exclusive with the others, so you configure them on separate integrations.

Reliability behavior is worth designing around. Each request has a 5-second timeout. On a connection error or timeout, Gorgias retries up to 3 times with exponential backoff — 10 seconds, then 20, then 40. And if your endpoint fails 500 consecutive times, Gorgias auto-disables the integration (the counter resets after any successful delivery). The practical takeaways: your receiver must respond fast and idempotently — the same event can arrive more than once — and you should monitor for the disabled state so a bad deploy on your side doesn't silently switch your automations off. If you would rather keep event logic inside Gorgias, Gorgias Rules and Flows cover a lot of ground without any external endpoint at all.

The honest limits — where the API stops (and where an AI layer starts)

The Gorgias API is solid, well-documented, and genuinely complete for helpdesk objects. Credit where due: for tickets, messages, customers, tags, and macros, you can build almost anything. But there are real edges an ecommerce team should walk in with eyes open:

• Rate limits are tight for bulk work. 40 requests / 20 seconds on an API key is fine for event-driven writes and modest syncs; it is not fine for a naive full-history backfill. Expect to page carefully, respect Retry-After, and possibly move to OAuth2 for the 80/20s ceiling.
• Revenue and order data are not simply "in the API." Gorgias's richest ecommerce value — order details, revenue attribution, order management actions — comes from its Shopify (and other store) integrations, which are their own connectors and, for some capabilities, plan- or add-on-gated. The REST API exposes helpdesk objects; it is not a substitute for querying your store's own API for live order status.
• No agent-lifecycle webhooks. HTTP Integrations fire on ticket and message events, but there is no agent-created or agent-deactivated event, so user-provisioning sync has to be polled through /api/users rather than pushed.
• The API moves data; it doesn't reason over it. A GET /api/tickets hands you a conversation. It will not read that conversation, understand the shopper's intent, look up their order, and write the correct reply. That is application logic you still have to build.

That last gap is exactly where an AI agent layer fits. The category of AI agents for customer service exists to do the reasoning the REST API can't. Macha is one such layer that runs on top of the Gorgias you already use through a live connector — it does not replace Gorgias or its API. It authenticates over this same REST surface to read tickets and post replies, and when a shopper asks "where's order #1043?", it fetches the answer through a custom tool that wraps your store or backend API into something the agent can call, then writes a grounded reply on the ticket. Credits are consumed per AI action, not per resolution — the pricing page has the breakdown. The clean split: let the Gorgias API stay the read/write plumbing and system of record, and put an agent on top for the part the plumbing can't do — understand the message and answer it. New to the platform underneath all this? Start with what is Gorgias.

FAQ

How do I authenticate with the Gorgias API? Use HTTP Basic authentication: your account email as the username and your API key as the password, base64-encoded into an Authorization: Basic header over HTTPS. Find both values under Settings (gear) → Account → REST API, in the API Access & Credentials section. For shared or multi-tenant apps, use OAuth2 instead.

What are the Gorgias API rate limits? The leaky-bucket limiter allows 40 requests per 20-second window for API-key (Basic auth) integrations and 80 per 20 seconds for OAuth2 apps. Enterprise accounts use the same counts over a smaller 10-second window. Going over returns HTTP 429, with a Retry-After header (seconds to wait) and an X-Gorgias-Account-Api-Call-Limit header showing your live usage.

What's the base URL and which endpoints matter? The base is https://{your-domain}.gorgias.com/api/. The core resources are /api/tickets, /api/tickets/{id}/messages (and /api/messages), /api/customers, /api/users, /api/tags, /api/macros, and /api/integrations.

Does Gorgias have webhooks? Yes — they're called HTTP Integrations, set up under Account → HTTP integration → Manage → Add HTTP integration. Triggers include Ticket created, updated, self unsnoozed, message created, and message failed, plus mutually-exclusive Ticket assignment updated and Ticket status updated. Each call has a 5-second timeout, retries up to 3 times (10/20/40s backoff), and the integration auto-disables after 500 consecutive failures.

Can I add AI on top of the Gorgias API without replacing Gorgias? Yes. Macha connects through the same REST API as a native connector and runs on top of your existing Gorgias account — it reads tickets and posts replies over the API, calls your own tools for order data, and never replaces Gorgias or its API.

Ready to turn the Gorgias API into an actual automation? Start a free trial of Macha and connect it to your Gorgias in minutes.