Gorgias
Gorgias is a customer support helpdesk for ecommerce. This source syncs your helpdesk data from the Gorgias REST API. This includes tickets, messages, customers, and their supporting configuration and activity objects. See Streams for the full list.
Prerequisites
- A Gorgias account with access to Settings > REST API, where you create API keys.
- Your Gorgias subdomain. If you sign in at
https://acme.gorgias.com, your subdomain isacme.
Set up the Gorgias source
- In Gorgias, go to
https://YOUR_SUBDOMAIN.gorgias.com/app/settings/apiand create an API key. - In Airbyte, create a new Gorgias source and complete the fields below.
The connector uses HTTP basic authentication. Enter your email address as the username and your API key as the password. Private apps, including this connector, use API keys. OAuth2 is only for public Gorgias apps. See the Gorgias authentication reference for details.
Configuration
| Input | Type | Description | Default Value |
|---|---|---|---|
username | string | The email address of the Gorgias user that owns the API key. | |
password | string | The API key generated in Settings > REST API. | |
domain_name | string | Your Gorgias subdomain, taken from the URL prefix you use to reach Gorgias. For https://acme.gorgias.com, enter acme. | |
start_date | string | The starting cursor value for incremental syncs, in YYYY-MM-DDTHH:MM:SSZ format. Airbyte rejects any other format. The streams that read in full on every sync ignore this value. |
Streams
| Stream Name | Primary Key | Pagination | Supports Full Sync | Supports Incremental |
|---|---|---|---|---|
| account | domain | No pagination | ✅ | ✅ |
| customers | id | DefaultPaginator | ✅ | ✅ |
| custom-fields | id | DefaultPaginator | ✅ | ✅ |
| events | id | DefaultPaginator | ✅ | ✅ |
| integrations | id | DefaultPaginator | ✅ | ✅ |
| jobs | id | DefaultPaginator | ✅ | ✅ |
| macros | id | DefaultPaginator | ✅ | ✅ |
| views | id | DefaultPaginator | ✅ | ✅ |
| rules | id | DefaultPaginator | ✅ | ✅ |
| satisfaction-surveys | id | DefaultPaginator | ✅ | ✅ |
| tags | id | DefaultPaginator | ✅ | ✅ |
| teams | id | DefaultPaginator | ✅ | ✅ |
| tickets | id | DefaultPaginator | ✅ | ✅ |
| messages | id | DefaultPaginator | ✅ | ✅ |
| users | id | DefaultPaginator | ✅ | ✅ |
| views_items | view_id, id | DefaultPaginator | ✅ | ✅ |
The views_items stream reads every view’s items returned by the views stream. It adds the parent view’s view_id to each record. The same item can appear in multiple views. Therefore, the stream uses view_id and id together as its primary key.
Rate limits
Gorgias limits API key integrations to 40 requests within 20 seconds. It returns 429 Too Many Requests when you exceed this limit. The connector paces requests within that limit and requests the maximum 100 records per page. Before retrying a throttled request, it waits for the seconds specified in the Retry-after response header. See the Gorgias rate limit reference for details.
Anything using the same credentials shares this request limit. If other integrations use the same API key, syncs can still receive 429 responses. A sync can fail after three retries of a request.
IP allow list
If you use Airbyte Cloud and restrict access to specific IPs, add the Airbyte Cloud IP addresses to your allow list.
Incremental syncs
Each stream has its own cursor field and applies sync state differently:
| Stream | Cursor field | How state limits the sync |
|---|---|---|
| account | created_datetime | Reads in full on every sync |
| customers | updated_datetime | Stops paginating at the cursor |
| custom-fields | updated_datetime | Filters records after reading in full |
| events | created_datetime | Filters server-side, with a 5-minute lookback |
| integrations | updated_datetime | Filters records after reading in full |
| jobs | created_datetime | Stops paginating at the cursor |
| macros | created_datetime | Reads in full on every sync |
| views | created_datetime | Reads in full on every sync |
| rules | created_datetime | Stops paginating at the cursor |
| satisfaction-surveys | created_datetime | Reads in full on every sync |
| tags | created_datetime | Stops paginating at the cursor |
| teams | created_datetime | Stops paginating at the cursor |
| tickets | updated_datetime | Stops paginating at the cursor |
| messages | created_datetime | Stops paginating at the cursor |
| users | created_datetime | Stops paginating at the cursor |
| views_items | created_datetime | Reads in full on every sync |
Streams that stop paginating at the cursor only request pages that can contain new records. Their incremental syncs are therefore much cheaper than a full read. Streams that filter after a full read still request every page from the Gorgias API. They reduce the records Airbyte emits, but not the API calls made during the sync.
Limitations
The following streams use created_datetime as their incremental cursor. Their incremental syncs don’t capture changes made after a record’s creation:
- jobs: job status transitions, including changes to
started_datetimeandended_datetime. The schema doesn’t includeupdated_datetime. - messages: changes to message fields after creation. The schema doesn’t include
updated_datetime. - rules: rule edits and deactivation changes. The schema includes
updated_datetime, but the/api/rulesendpoint can’t order by it. Therefore, the stream usescreated_datetimeas its cursor. - tags: tag renames and changes to descriptions or decorations. The schema doesn’t include
updated_datetime. - teams: team renames and changes to descriptions, decorations, or members. The schema doesn’t include
updated_datetime. - users: role, name, active-status, and timezone changes. The schema includes
updated_datetime, but the/api/usersendpoint can’t order by it. Therefore, the stream usescreated_datetimeas its cursor.
Run a full refresh of the affected stream to capture these changes.
The custom-fields stream only returns custom fields with the object type Ticket. It doesn’t sync custom fields defined on other Gorgias objects, such as customers.
Streams that read in full during every sync capture changes made after creation. These include a macro’s name or a survey’s score and scored_datetime.
The connector doesn’t capture deletions as deletion events. Tickets expose trashed, and tags expose deleted_datetime. However, there is no deletion stream, so deleted records aren’t captured as deletion events.
The incremental sync end_datetime is evaluated when the sync starts. Records created during a sync fall outside that window and are picked up by the next sync.
Changelog
Expand to review
| Version | Date | Pull Request | Subject |
|---|---|---|---|
| 0.1.61 | 2026-11-03 | 90597 | Update dependencies |
| 0.1.60 | 2026-11-01 | 90358 | Simplify rate-limit error handling configuration with no change in sync behavior |
| 0.1.59 | 2026-10-27 | 89935 | Update dependencies |
| 0.1.58 | 2026-10-20 | 89237 | Update dependencies |
| 0.1.57 | 2026-10-13 | 88643 | Update dependencies |
| 0.1.56 | 2026-10-06 | 87876 | Update dependencies |
| 0.1.55 | 2026-09-29 | 87230 | Update dependencies |
| 0.1.54 | 2026-09-22 | 86646 | Update dependencies |
| 0.1.53 | 2026-09-15 | 86083 | Update dependencies |
| 0.1.52 | 2026-09-08 | 85503 | Update dependencies |
| 0.1.51 | 2026-08-25 | 84910 | Incremental syncs now avoid re-reading previously-synced data across the applicable Gorgias streams using cursor-aware pagination, server-side date filtering, or client-side filtering. See Incremental syncs for what an incremental sync no longer picks up. |
| 0.1.50 | 2026-08-18 | 84643 | Update dependencies |
| 0.1.49 | 2026-08-11 | 83969 | Update dependencies |
| 0.1.48 | 2026-08-04 | 83514 | Update dependencies |
| 0.1.47 | 2026-07-28 | 82941 | Update dependencies |
| 0.1.46 | 2026-07-21 | 82473 | Update dependencies |
| 0.1.45 | 2026-07-14 | 81873 | Update dependencies |
| 0.1.44 | 2026-06-30 | 81090 | Update dependencies |
| 0.1.43 | 2026-06-23 | 80502 | Update dependencies |
| 0.1.42 | 2026-06-16 | 79893 | Update dependencies |
| 0.1.41 | 2026-06-09 | 79345 | Update dependencies |
| 0.1.40 | 2026-06-02 | 78776 | Update dependencies |
| 0.1.39 | 2026-04-28 | 77277 | Update dependencies |
| 0.1.38 | 2026-04-21 | 76614 | Update dependencies |
| 0.1.37 | 2026-03-17 | 74936 | Update dependencies |
| 0.1.36 | 2026-03-10 | 74662 | Update dependencies |
| 0.1.35 | 2026-02-24 | 73115 | Update dependencies |
| 0.1.34 | 2026-01-20 | 71909 | Update dependencies |
| 0.1.33 | 2026-01-14 | 71733 | Update dependencies |
| 0.1.32 | 2025-12-18 | 70485 | Update dependencies |
| 0.1.31 | 2025-11-25 | 70062 | Update dependencies |
| 0.1.30 | 2025-11-18 | 69410 | Update dependencies |
| 0.1.29 | 2025-10-29 | 68809 | Update dependencies |
| 0.1.28 | 2025-10-21 | 68243 | Update dependencies |
| 0.1.27 | 2025-10-14 | 67919 | Update dependencies |
| 0.1.26 | 2025-10-07 | 67412 | Update dependencies |
| 0.1.25 | 2025-09-30 | 66399 | Update dependencies |
| 0.1.24 | 2025-09-09 | 66058 | Update dependencies |
| 0.1.23 | 2025-08-23 | 65350 | Update dependencies |
| 0.1.22 | 2025-08-09 | 64599 | Update dependencies |
| 0.1.21 | 2025-08-02 | 64303 | Update dependencies |
| 0.1.20 | 2025-07-26 | 63845 | Update dependencies |
| 0.1.19 | 2025-07-19 | 63487 | Update dependencies |
| 0.1.18 | 2025-07-12 | 63114 | Update dependencies |
| 0.1.17 | 2025-07-05 | 62553 | Update dependencies |
| 0.1.16 | 2025-06-28 | 62193 | Update dependencies |
| 0.1.15 | 2025-06-21 | 61810 | Update dependencies |
| 0.1.14 | 2025-06-14 | 61147 | Update dependencies |
| 0.1.13 | 2025-05-24 | 60609 | Update dependencies |
| 0.1.12 | 2025-05-10 | 59874 | Update dependencies |
| 0.1.11 | 2025-05-03 | 59240 | Update dependencies |
| 0.1.10 | 2025-04-26 | 58770 | Update dependencies |
| 0.1.9 | 2025-04-19 | 58193 | Update dependencies |
| 0.1.8 | 2025-04-12 | 57708 | Update dependencies |
| 0.1.7 | 2025-04-05 | 57041 | Update dependencies |
| 0.1.6 | 2025-03-29 | 56719 | Update dependencies |
| 0.1.5 | 2025-03-22 | 56041 | Update dependencies |
| 0.1.4 | 2025-03-08 | 55491 | Update dependencies |
| 0.1.3 | 2025-03-01 | 54794 | Update dependencies |
| 0.1.2 | 2025-02-22 | 54335 | Update dependencies |
| 0.1.1 | 2025-02-15 | 50638 | Update dependencies |
| 0.1.0 | 2025-01-30 | 52637 | Add retries for rate limited streams |
| 0.0.8 | 2024-12-23 | 49935 | Add additional cursor datetime format |
| 0.0.7 | 2024-12-21 | 50123 | Update dependencies |
| 0.0.6 | 2024-12-14 | 49219 | Update dependencies |
| 0.0.5 | 2024-12-11 | 48973 | Starting with this version, the Docker image is now rootless. Please note that this and future versions will not be compatible with Airbyte versions earlier than 0.64 |
| 0.0.4 | 2024-11-06 | 48378 | Fix incremental sync format, Auto update schema with additional fields |
| 0.0.3 | 2024-10-29 | 47923 | Update dependencies |
| 0.0.2 | 2024-10-28 | 47459 | Update dependencies |
| 0.0.1 | 2024-09-29 | 46221 | Initial release by @btkcodedev via Connector Builder |