Shopify Integration — Freshdesk

A Freshdesk ticket sidebar app that pulls Shopify customers and orders into the agent view. Built with React Meta, Crayons React, and Platform request templates.

Platform	3.0
Framework	React Meta
Surface	ticket_sidebar
Node	24.11.1
FDK	10.1.2

---

What it does

Agents on a ticket can:

• Look up orders by customer email (Shopify Orders API)
• Browse customers as accordion cards (Shopify Customers API)
• Clear results or reset the form between lookups

Shopify calls use request templates (fetchCustomers, fetchCustomerOrders in config/requests.json). Credentials are stored in installation parameters — the access token is secure.

---

Prerequisites

Requirement	Link / notes
Node.js 24.x	Node downloads
FDK 10.1.2	Freshworks FDK setup
Freshdesk dev account	Your Freshdesk site URL (e.g. https://acme.freshdesk.com)
Shopify store	Shopify Admin with permission to create custom apps
Admin API token	Scopes: read_customers, read_orders — see Step 1

---

Step 1 — Create a Shopify custom app

Create a custom app in your store (not an embedded Partner app). The Freshdesk sidebar only needs an Admin API token — no App URL or OAuth redirect.

1. Open Shopify Admin → Settings → Apps and sales channels → Develop apps.
   • Docs: Create and install a custom app
2. Click Create an app (e.g. Freshdesk integration).
3. Under Configuration → Admin API integration, set Admin API access scopes:

   read_customers,read_orders
   

   • Scope reference: Shopify access scopes
4. Click Save, then Install app on your store.
5. Open API credentials and copy:
   • Admin API access token (starts with shpat_…) — use this in Freshdesk, not the Storefront token
   • Your store subdomain from your-store.myshopify.com → subdomain is your-store

Freshdesk iparam	Where to get it
Shopify sub domain	your-store from your-store.myshopify.com
Shopify Access Token	Custom app → API credentials → Admin API access token

---

Step 2 — Install dependencies and validate

From this folder:

cd only-migration/shopify-integration
npm install
fdk config set global_apps.enabled true
fdk validate

global_apps.enabled is required because request templates are declared under modules.common — see global app concepts.

Expected: 0 platform errors, 0 lint errors.

---

Step 3 — Run locally

fdk run

Keep this terminal running. The FDK serves the app and opens local developer tools.

Local URL	Purpose
http://localhost:10001/custom_configs	Enter iparams (subdomain + token)
http://localhost:10001/system_settings	Account URLs and module subscription
http://localhost:10001/web/test	Webhook / event testing (not used by this app)

Docs: Test your app

---

Step 4 — Configure installation parameters

1. With fdk run active, open http://localhost:10001/custom_configs.
2. Enter:
   • Shopify sub domain — e.g. your-store
   • Shopify Access Token — Admin API token from Step 1
3. Click Save.

These map to config/iparams.json and are substituted into config/requests.json at runtime.

---

Step 5 — Test in Freshdesk

1. Open your Freshdesk site with dev mode:
   • https://<your-domain>.freshdesk.com/a/?dev=true
   • If the URL already has query params, use &dev=true instead of ?dev=true
2. When the browser prompts, allow local network access (required for fdk run).
3. Open any ticket.
4. In the right Apps panel, launch Shopify Integration.
5. Try:
   • Enter a customer email → Fetch Orders
   • Fetch Customers to list store customers
   • Reset All to clear the sidebar

---

Screenshots

View
Ticket sidebar
Fetch Customers
Fetch Orders

---

UI actions

Button	Action
Fetch Orders	Loads orders for the email in the input field
Clear Orders	Clears email and order list
Fetch Customers	Loads customer accordion cards from Shopify
Clear Customers	Removes customer cards
Reset All	Clears customers, orders, and status messages

---

Project structure

shopify-integration/
├── manifest.json                 # React Meta + request template declarations
├── package.json
├── app/
│   ├── sidebar.html              # ticket_sidebar entry
│   ├── components/               # ShopifyMain, ShopifyApp, CustomerCard, OrderCard
│   ├── utils/                    # shopify-api.js, validation.js
│   └── styles/
├── config/
│   ├── iparams.json
│   └── requests.json             # Shopify Admin API 2023-04
├── tests/
│   └── shopify-api.test.js
└── docs/
    ├── usecase.md
    ├── solution.md
    ├── app_dev_guide.md
    └── assets/shopify-api-collection.json

---

Testing

npm test
fdk validate

---

Troubleshooting

Symptom	What to check
401 / request fails	Correct subdomain and Admin API token; custom app installed on the store
No customers	Store has customers; scopes include read_customers
No orders for email	Email has orders in Shopify; scopes include read_orders
global apps validation error	Run fdk config set global_apps.enabled true
App does not appear	fdk run is running; URL has ?dev=true; local network allowed
Invalid scopes in Partner dashboard	This app uses store custom apps, not embedded Partner OAuth — see Step 1

---

Related documentation

Freshworks

• Request method
• Installation parameters
• Ticket sidebar placement
• Freshworks CLI — fdk run

Shopify

• Custom apps in Shopify Admin
• Admin REST API — Customers
• Admin REST API — Orders
• Access scopes

Repo guides

• Use case
• Solution walkthrough
• App development guide
• Shopify API collection