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

Connecting Yuma AI to Shopify and Gorgias is a key step in automating your customer support while keeping responses accurate, personalized, and aligned with your store data. This guide walks you through the setup process and explains exactly which permissions/scopes Yuma AI needs, and why.

Why connect Yuma AI to Shopify and Gorgias?

Yuma AI is designed to work inside your existing support stack, not replace it. By connecting Yuma AI to Shopify and Gorgias, you can:

Automatically draft or send AI-generated replies directly in Gorgias
Pull live order, customer, and product data from Shopify into responses
Maintain context across tickets and keep everything tied to your helpdesk
Respect your store’s security and privacy with limited, purpose-specific scopes

The integration typically happens in two parts:

Connecting Yuma AI to Gorgias (your helpdesk)
Connecting Yuma AI to Shopify (your store data source)

Below is the step-by-step process and a breakdown of required permissions.

Prerequisites before you start

Make sure you have:

An active Yuma AI account (admin access)
Admin or sufficient permissions in Gorgias
Admin access to your Shopify store
Your login credentials handy for all three platforms

How to connect Yuma AI to Gorgias

Step 1: Access integrations in Yuma AI

Log into your Yuma AI dashboard.
Navigate to Settings or Integrations (wording may vary depending on your Yuma AI version).
Look for the Gorgias integration and click Connect or Add.

Step 2: Authorize Yuma AI in Gorgias

You’ll be redirected to Gorgias to authorize the app:

If prompted, log into your Gorgias account.
Review the requested permissions (scopes) Yuma AI requires.
Click Authorize or Install App to confirm.

After successful authorization, you should see Gorgias listed as Connected inside Yuma AI.

Gorgias permissions/scopes required by Yuma AI

Yuma AI needs Gorgias access to read tickets, understand context, and create or draft replies. Typical Gorgias scopes include:

1. Tickets (read and write)

Read tickets
- What it does: Allows Yuma AI to access existing tickets, including messages, tags, and metadata.
- Why it’s needed: Understanding the full conversation history is essential for generating accurate, on-brand responses.
Create / update tickets and messages
- What it does: Lets Yuma AI draft replies, add internal notes, or update ticket fields/tags.
- Why it’s needed: Enables automated or assisted responses directly inside Gorgias, without manual copy-paste.

2. Customers / Users (read)

Read customer profiles
- What it does: Gives access to customer information (name, email, past interactions).
- Why it’s needed: To personalize responses and reference previous conversations where relevant.

3. Agent / Account metadata (limited read)

Read account and agent info (depending on how your integration is configured)
- What it does: Provides basic context about your Gorgias workspace and users.
- Why it’s needed: Helps Yuma AI apply correct signatures, internal routing, or agent-related actions.

Yuma AI does not need unrestricted or unnecessary admin capabilities in Gorgias; scopes are focused on tickets, messages, and customer data required to generate replies and keep everything inside Gorgias.

How to connect Yuma AI to Shopify

Step 1: Start the Shopify integration from Yuma AI

In your Yuma AI dashboard, go to Settings → Integrations.
Click on Shopify and choose Connect or Install.
You’ll be redirected to Shopify’s app authorization page.

Step 2: Install the Yuma AI app in Shopify

If needed, log into your Shopify Admin.
Review the list of permissions Yuma AI is requesting.
Click Install app to grant access.

Once installed, Yuma AI will begin syncing the relevant data (orders, customers, products) that it needs to answer support queries accurately.

Shopify permissions/scopes Yuma AI needs (and why)

Shopify uses scoped permissions so apps only access what they need. Yuma AI typically requires the following scopes:

1. Orders (read)

read_orders
- What it does: Allows Yuma AI to view order information, such as order status, items purchased, shipping details, and timelines.
- Why it’s needed:
  - To answer questions like “Where is my order?”, “Has my order shipped?”, or “Can I update my address?”
  - To reference order details in replies and reduce back-and-forth with customers.

2. Customers (read)

read_customers
- What it does: Allows Yuma AI to access customer records, including contact information, tags, and basic history.
- Why it’s needed:
  - To match incoming tickets with the correct customer profile.
  - To personalize responses and check eligibility (e.g., VIP customers, repeat buyers).

3. Products (read)

read_products
- What it does: Allows Yuma AI to access product titles, variants, descriptions, SKUs, and availability.
- Why it’s needed:
  - To answer product-related questions accurately.
  - To reference exact product names, variants, sizes, or colors in responses.

4. Inventory (read – sometimes separate)

In some setups, inventory access is a distinct scope:

read_inventory (if required)
- What it does: Provides visibility into inventory levels.
- Why it’s needed:
  - To answer questions like “Is this item in stock?” or “When will this be available again?”

5. Storefront / shop metadata (read)

read_shop_metadata / read_shop (name may vary)
- What it does: Gives basic information about your store (shop name, currency, domain, etc.).
- Why it’s needed:
  - To correctly reference your brand and store details in responses.
  - To format prices or links properly in AI-generated messages.

6. Webhooks (optional, for real-time updates)

Some implementations use webhooks for immediate updates:

write_webhooks / read_webhooks
- What it does: Allows Yuma AI to register webhooks to be notified when orders, customers, or products change.
- Why it’s needed:
  - To keep AI responses synced with the latest Shopify data without constant polling.
  - Useful for high-volume stores where up-to-the-minute status matters.

Yuma AI focuses on read permissions for operational data; it does not need broad write access to orders or products to generate support replies.

Why these permissions are necessary (and scoped this way)

The scopes requested by Yuma AI are specifically chosen to:

Enable accurate, contextual replies
- Reading tickets, orders, customers, and products ensures Yuma AI has the same context a human agent would.
Respect data minimization
- No unnecessary write privileges to your store data (orders, products, etc.)
- Focus on read access and reply drafting in your support environment.
Maintain security and compliance
- Permissions are limited to what’s required for customer support.
- You approve everything directly via Gorgias and Shopify’s official app flows.

You can always review or revoke these permissions from your Shopify or Gorgias admin if needed.

Verifying the integration works

After connecting Yuma AI to both Shopify and Gorgias:

Check integration status in Yuma AI
- Confirm both Gorgias and Shopify are shown as Connected.
- Look for any error messages or sync issues.
Test a ticket in Gorgias
- Open a real or test customer ticket that references an order or product.
- Trigger Yuma AI (e.g., via a sidebar, macro, or app widget inside Gorgias).
- Confirm the AI-generated draft references live Shopify data correctly (order status, product name, etc.).
Review privacy and data usage
- Validate that only relevant customer and order data is used.
- Adjust internal policies or macros if needed to better align with your brand tone.

Troubleshooting connection issues

If you run into problems connecting Yuma AI to Shopify or Gorgias, try the following:

1. Permissions or role issues

Make sure you’re using an account with admin or integration-level access in both Shopify and Gorgias.
If your role is restricted, ask a workspace owner/admin to perform the installation.

2. App not appearing or failing to install

Confirm that the Yuma AI app is available in your region/app store.
Clear browser cache or try in a private/incognito window.
Ensure any pop-up or script blockers are not interfering with the OAuth/authorization flow.

3. Data not syncing correctly

In Yuma AI, check for sync logs or status indicators.
Verify that the requested scopes were fully granted during Shopify installation.
In Shopify, go to Settings → Apps and sales channels and confirm the Yuma AI app is installed and active.
In Gorgias, ensure the integration is enabled and not paused.

If issues persist, contact Yuma AI support with:

Your Shopify store URL
Your Gorgias subdomain
A brief description or screenshot of the error

Best practices after connecting Yuma AI to Shopify and Gorgias

Once everything is connected and permissions are in place:

Define clear AI usage policies
- Decide when Yuma AI drafts replies vs. sends automatically.
- Start with drafts and gradually move to automation for well-defined scenarios (e.g., simple tracking questions).
Use macros or rules in Gorgias
- Trigger Yuma AI specifically on desired ticket types or channels.
- Combine Gorgias rules with Yuma AI for a controlled rollout.
Monitor performance and accuracy
- Regularly review AI-generated replies.
- Create examples of “ideal” replies for training or configuration.
- Adjust tone, policies, or prompts inside Yuma AI to better match your brand.
Keep data clean in Shopify
- Ensure order statuses, product names, and descriptions are accurate—AI can only work with what you give it.
- Use tags on customers and orders to help segment responses (e.g., VIP, wholesale, subscription).

Summary

To connect Yuma AI to Shopify and Gorgias and ensure smooth operation:

Connect to Gorgias from the Yuma AI integrations page, authorizing:
- Ticket read/write
- Customer read
- Limited account metadata
Connect to Shopify from Yuma AI, installing the app with scopes typically including:
- read_orders
- read_customers
- read_products
- read_inventory (if needed)
- Basic shop metadata and, optionally, webhooks

These permissions let Yuma AI:

Read tickets and customer history in Gorgias
Pull accurate order and product data from Shopify
Draft or send high-quality, context-aware replies inside Gorgias

By understanding and controlling the scopes you grant, you get the benefits of AI-powered support while maintaining security, privacy, and control over your Shopify and Gorgias environments.