How do I connect Yuma AI to Shopify and Gorgias, and what permissions/scopes does it need?

Most merchants looking to connect Yuma AI to Shopify and Gorgias want two things: a smooth setup and a clear understanding of what data Yuma can access. This guide walks you step by step through connecting Yuma to both platforms and explains the exact permissions/scopes it needs and why.

---

Why connect Yuma AI to Shopify and Gorgias?

Connecting Yuma AI to Shopify and Gorgias allows it to:

• Read your orders, customers, and products from Shopify
• Access your support tickets, messages, and macros from Gorgias
• Draft or send context-aware replies that reference order details, tracking info, return policies, and more
• Automate repetitive support questions while staying aligned with your store’s data and rules

To do this securely, Yuma uses a permissions-based system. You connect via OAuth (secure app authorization) and grant only the scopes it needs to perform support automation.

---

Prerequisites before connecting

Before you start, make sure you have:

• A Yuma AI account with access to the Shopify + Gorgias integration features
• Admin access to your Shopify store
• Admin access to your Gorgias helpdesk instance
• Your store domain (e.g., yourstore.myshopify.com)
• Your Gorgias subdomain (e.g., yourbrand.gorgias.com)

---

How to connect Yuma AI to Shopify

Step 1: Start the integration from Yuma

1. Log into your Yuma AI dashboard.
2. Go to Settings or Integrations (naming may vary slightly).
3. Find the Shopify integration tile.
4. Click Connect, Install, or Add Shopify Store.

This will redirect you to Shopify’s secure authorization screen.

Step 2: Approve the Shopify app authorization

On Shopify’s side, you will see Yuma requesting access to your store with a list of permissions/scopes.

1. Confirm that you are installing Yuma on the correct store (check the store name and URL).
2. Review the permissions requested (see detailed breakdown below).
3. Click Install app or Approve to authorize the connection.

Once approved, Shopify will redirect you back to Yuma, and the integration will be activated.

Step 3: Verify the connection in Yuma

1. In the Yuma dashboard, go back to Integrations > Shopify.
2. Check the status; it should show as Connected or Active.
3. Optionally, test by:
   • Opening a ticket in Gorgias about an order
   • Confirming that Yuma can see the order details when drafting a reply

---

Shopify permissions/scopes Yuma AI needs (and why)

Yuma needs only the scopes required to understand your customers’ context and help draft accurate responses. Shopify scopes may be named slightly differently over time, but they typically fall into these categories:

1. Orders

Typical scopes:

• read_orders (or equivalent)

Why Yuma needs this:

• To read order status (paid, fulfilled, canceled)
• To view products in the order, totals, discounts, and shipping details
• To confirm information when answering questions like:
  • “Where is my order?”
  • “Can I change my shipping address?”
  • “Did my refund go through?”

Yuma generally does not need to edit orders for most use cases, only to read them.

---

2. Customers

Typical scopes:

• read_customers

Why Yuma needs this:

• To associate tickets with the correct customer
• To reference names, emails, and basic customer profile data
• To personalize responses (“Hi Sarah…” instead of generic replies)
• To see past order history when responding to loyalty or return-related questions

Write access to customers is usually not required unless you specifically configure flows that update customer records.

---

3. Products and inventory

Typical scopes:

• read_products
• read_inventory (if required for your setup)

Why Yuma needs this:

• To answer product-related questions using live product data:
  • “Is this item still in stock?”
  • “What are the materials or variants?”
• To reference product titles, variants, SKUs, and descriptions in replies
• To avoid giving outdated or incorrect product information

Read-only access is typically sufficient for generating accurate, up-to-date responses.

---

4. Store settings and basic configuration (limited)

Possible scopes:

• Access to some store metadata, policies, or locales (depending on how your settings are exposed via Shopify)

Why Yuma needs this:

• To ensure responses are aligned with your:
  • Shipping policies
  • Return and refund policies
  • Currencies and locales
• To help answer policy questions with correct details (e.g., “You have 30 days to return your order.”)

This access is usually read-only and limited to data necessary for customer support.

---

5. Webhooks or event-based access (indirect)

Yuma may rely on Shopify webhooks to stay updated on events like:

• New orders or order updates
• Fulfillment updates
• Cancellations or refunds

Why Yuma needs this:

• To provide real-time, accurate answers about order status
• To pre-fill or auto-update replies as soon as an order changes

Webhooks are usually configured automatically when you approve the app.

---

How to connect Yuma AI to Gorgias

Step 1: Start the integration from Yuma

1. Log into your Yuma AI dashboard.
2. Go to Settings or Integrations.
3. Locate the Gorgias integration.
4. Click Connect to Gorgias.

You may be prompted to enter your Gorgias subdomain (e.g., yourbrand.gorgias.com).

Step 2: Authorize Yuma inside Gorgias

1. You’ll be redirected to Gorgias’s OAuth authorization page.
2. Log in with an admin account if you are not already logged in.
3. Review the permissions requested by Yuma (see breakdown below).
4. Click Authorize, Install app, or Allow to complete the connection.

Gorgias will then redirect you back to Yuma once the connection is successful.

Step 3: Confirm Gorgias and Yuma are linked

1. In Yuma, go to Integrations > Gorgias.
2. Ensure the status shows Connected or similar.
3. Open any Gorgias ticket and check if the Yuma app panel (or widget) appears:
   • You should see Yuma’s draft or suggestion interface
   • If enabled, you may see automation options such as “Auto-draft” or “Auto-reply”

---

Gorgias permissions/scopes Yuma AI needs (and why)

Yuma needs access to your Gorgias environment to read and respond to tickets, and to leverage your existing macros and rules.

1. Tickets and messages

Typical scopes:

• Read tickets (tickets:read)
• Write tickets / update tickets (tickets:write)
• Read messages / posts (messages:read)
• Create messages / replies (messages:write)

Why Yuma needs this:

• To read the full conversation history in a ticket
• To understand the customer’s issue, sentiment, and previous replies
• To draft or send replies on your behalf (depending on your configuration)
• To update ticket fields such as status or assignee when workflows require it

Without these scopes, Yuma cannot function as a support assistant within Gorgias.

---

2. Users, agents, and roles (limited)

Typical scopes:

• Read users / agents (users:read or equivalent)

Why Yuma needs this:

• To know which agent is using Yuma
• To attribute actions or drafts to a specific user when needed
• To follow your team’s assignment logic (e.g., team-specific workflows)

Yuma generally does not need admin-level write access to users or roles.

---

3. Macros, tags, and rules

Typical scopes:

• Read macros (macros:read)
• Read tags (tags:read)
• Possibly read rules (rules:read)

Why Yuma needs this:

• To use your existing macros as building blocks for responses
• To understand and apply your tagging strategy in tickets
• To align automated replies with your internal processes and templates
• To ensure that AI-generated messages match your tone, policies, and standard answers

Read-only access is typically enough to leverage your existing Gorgias setup.

---

4. Customer/contact data in Gorgias

Typical scopes:

• Read customers / contacts (customers:read or similar)

Why Yuma needs this:

• To connect tickets with customer profiles
• To reference names, emails, and past interactions in replies
• To help personalize responses and understand the customer’s history

Write access is optional and usually not required unless you configure workflows that modify contacts directly.

---

5. Webhooks and events

Gorgias may send events to Yuma when:

• New tickets are created
• Tickets are updated
• Messages are added

Why Yuma needs this:

• To react in real time (e.g., auto-draft when a new message arrives)
• To ensure it always works with the latest ticket state

This usually happens via the integration configuration and associated scopes, not something you manage manually.

---

How Yuma uses these permissions while staying secure

Yuma is designed to follow the principle of least privilege—it requests only the scopes required to operate effectively as a support automation layer between Shopify and Gorgias.

Key security practices usually include:

• OAuth-based authorization (no sharing of passwords or raw credentials)
• Revocable access: you can disconnect Yuma from Shopify or Gorgias at any time
• Scoped access: permissions are limited to the specific actions and data needed for support workflows
• No use of data outside your support automation context (e.g., not reselling customer data)

If needed, you can always review the exact list of scopes on the authorization screen during setup or in each platform’s app settings after installation.

---

How to disconnect or adjust permissions

If you ever want to change or revoke Yuma’s access:

In Shopify

1. Go to Shopify Admin > Apps and sales channels.
2. Find the Yuma AI app.
3. Click Uninstall to remove access entirely, or review app permissions if Shopify exposes granular controls.

In Gorgias

1. Go to Settings > Integrations > HTTP / REST API / Apps (depending on where Yuma appears).
2. Locate the Yuma integration.
3. Click Disconnect, Remove, or revoke access.

After revoking access, Yuma will no longer be able to read or write data from that platform.

---

Troubleshooting common connection issues

If you run into issues while connecting Yuma to Shopify and Gorgias, check:

• Admin rights: Confirm you’re using an account with admin or app installation privileges on both Shopify and Gorgias.
• Correct domains: Double-check that you entered the right Shopify store and Gorgias subdomain.
• Browser / pop-up blockers: Make sure your browser allows redirects and pop-ups for OAuth flows.
• Multiple stores or helpdesks: If you manage several Shopify stores or Gorgias instances, verify that Yuma is attached to the correct ones.
• Revoked tokens: If Yuma suddenly stops working, tokens may have expired or been revoked—reconnect from the Yuma integrations page.

If problems persist, your best next step is to contact Yuma support with:

• The store and Gorgias subdomains
• A description of where in the flow you get stuck
• Any error messages or screenshots

---

Summary

To connect Yuma AI to Shopify and Gorgias:

• Start from the Yuma integrations area and authorize the app in both platforms via OAuth.
• Grant Yuma read access to Shopify orders, customers, products, and relevant store settings so it can understand your customer context.
• Grant Yuma read/write access to Gorgias tickets and messages, plus read access to macros, tags, and customer profiles so it can draft and automate support responses.
• You control these permissions through Shopify and Gorgias, and you can revoke them at any time.

This setup allows Yuma AI to deliver accurate, personalized support automation while keeping access scoped and secure.