Shopify Integration

import { Aside, Steps, Tabs, TabItem } from ‘@astrojs/starlight/components’;

Connect your Shopify store to HARi to keep customers, orders, products and fulfillments in sync. Once connected, every order placed, customer created, or product updated on Shopify lands in HARi within seconds — no scheduled jobs to babysit, no CSV exports, no double data entry.

What it does

From Shopify	Into HARi
Customers (name, email, phone, billing/shipping addresses, default address, accepts marketing, tags)	Contact records, deduplicated by email
Orders (line items, totals, taxes, shipping, payment status, fulfilment status, notes)	Invoice records with line items
Products (title, variants, SKU, vendor, type, prices, inventory)	Product records
Fulfilments (carrier, tracking number, tracking URL)	Linked to the matching order
Real-time updates	Webhooks — changes in Shopify reflect in HARi within seconds
GDPR data requests	Customer data-request and redaction webhooks handled per Shopify policy

You keep using Shopify to run your store. HARi becomes the place where you see the customer behind every order: lifetime value, recent emails, support tickets, sales-team notes — alongside the order data Shopify already has.

Before you connect: install the E-commerce Integration

The Shopify connection needs the E-commerce Integration solution installed on your workspace first. This solution adds the entities HARi uses to store synced Shopify data — Product, Invoice, and Invoice Line. Without it, customers will sync but products and orders won’t.

You don’t need to install it manually if you don’t want to:

• When you arrive on Settings → Integrations → Shopify with this solution missing, HARi shows an amber banner with a one-click “Install E-commerce Integration” button.
• Clicking it installs the E-commerce Integration and its dependency (the Billing solution, which provides the Invoice / Product entities) in the right order — Billing first, E-commerce Integration second.
• The whole chain takes a few seconds. After that, the sync buttons unlock.

If you’d rather install ahead of time: Settings → Solutions → find E-commerce Integration → Install. HARi takes care of the Billing dependency automatically.

Quick start

There are two ways to connect:

For most merchants. One-click connect using HARi’s official Shopify app from the App Store.

The HARi CRM public Shopify app is currently in review with Shopify. While in review, new installs through this path are blocked. Until approval lands, use the **custom app** path below — it works today for any Shopify Plus organization.

When the app is live in the Shopify App Store, this section will document the one-click flow. For now, please use the custom app path.

For Shopify Plus organizations, or merchants who need their own dedicated Shopify app for compliance, billing isolation, or testing. Requires ~10 minutes of one-time setup in your Shopify Partners or Dev Dashboard.

The rest of this page walks through the custom app path step by step.

Connect using your own Shopify custom app

What you’ll need

• A Shopify store on Shopify Plus (the multi-store custom-distribution flow requires Plus). Non-Plus stores: please wait for the standard install above to become available.
• Owner-level access to a Shopify Partners account OR access to the Dev Dashboard for your Plus organization
• Your HARi workspace admin login

Step 1 — Create a Shopify app

1. Open Shopify Partners (partners.shopify.com) and sign in. Or use your Plus organization’s Dev Dashboard if that’s where you manage apps.

2. Create a new app. Pick Custom distribution as the distribution method when prompted. Give it a clear name — e.g. HARi for {Your Store Name}.

3. You’ll land on the app’s configuration page with several tabs: Overview, Configuration, API access, Distribution, Settings.

Step 2 — Configure the app

The configuration must match HARi’s expectations exactly. Open the app’s Configuration tab and set:

Field	Value
App URL	https://{your-tenant}.haricrm.com/settings/integrations/shopify — replace {your-tenant} with your HARi workspace subdomain (e.g. acme.haricrm.com)
Allowed redirection URL(s)	https://app.haricrm.com/api/integrations/shopify/oauth/callback — this exact URL, on app.haricrm.com, not your tenant subdomain
Embedded in Shopify admin	false — HARi opens in its own browser tab, not inside Shopify’s admin
Use legacy install flow	false (the modern default — recommended)
Admin API access scopes	The 56 scopes listed below

Paste this scope list (comma-separated, no spaces — paste as one block into Shopify’s scope picker):

read_assigned_fulfillment_orders, write_assigned_fulfillment_orders,
read_customer_events, read_companies, write_companies, read_customers,
write_customers, read_customer_merge, write_customer_merge,
read_price_rules, write_price_rules, read_discounts, write_discounts,
write_draft_orders, read_draft_orders, read_files, write_files,
read_fulfillments, write_fulfillments, write_inventory, read_inventory,
read_locales, write_locales, write_locations, read_locations,
write_marketing_events, read_marketing_events, read_markets, write_markets,
read_merchant_managed_fulfillment_orders, write_merchant_managed_fulfillment_orders,
read_metaobject_definitions, write_metaobject_definitions, read_metaobjects,
write_metaobjects, write_order_edits, read_order_edits, read_orders,
write_orders, read_payment_terms, write_payment_terms, read_products,
write_products, read_reports, read_returns, write_returns, read_shipping,
write_shipping, read_shopify_payments_payouts, read_shopify_payments_disputes,
write_shopify_payments_disputes, read_store_credit_account_transactions,
write_store_credit_account_transactions, read_store_credit_accounts,
read_translations, write_translations

**About webhook subscriptions**: you do **not** need to declare webhook topics in the app config. HARi automatically registers the 14 standard webhook subscriptions (orders, customers, products, GDPR, app lifecycle) via Shopify's Admin API immediately after install. Leave the Webhooks section empty.

**About `read_all_orders`**: this is a *protected customer data* scope that Shopify only grants to apps with explicit approval. It's deliberately omitted from the list above. If you need order history older than 60 days, request access through **Partners → app → API access requests** first, then add `read_all_orders` to the scope list once approved.

When all fields are set, save the configuration.

Step 3 — Release a version

Shopify’s Dev Dashboard uses versions. Your configuration is a draft until you release it.

1. Open the Versions tab → review the draft version
2. Click Release version → confirm
3. The version status changes to Active

If you skip this step, HARi’s connect button will return “installation link is invalid” because Shopify only honours released versions.

Step 4 — Add your store to the distribution list

1. Open the Distribution tab
2. Confirm Custom distribution is selected
3. Add your *.myshopify.com domain (or your Plus organization) to the allowed-stores list — Shopify generates a per-store install link
4. Copy the generated install link if you need to share it; you’ll use it implicitly when HARi initiates the OAuth flow

Step 5 — Copy the credentials

1. Open the Settings tab → Credentials section
2. Copy the Client ID (32-character hex string)
3. Click Reveal on the Secret field → copy the value (also 32-character hex, prefixed shpss_)

Keep these two values safe. The Secret is treated like a password and will be stored encrypted on HARi’s side.

Step 6 — Connect in HARi

1. Log into HARi as a workspace admin
2. Navigate to Settings → Integrations → Shopify
3. Enter your store’s *.myshopify.com domain in the Store domain field
4. Expand Advanced settings at the bottom of the form
5. Tick “Use a custom Shopify app for this store” — the credentials form appears
6. Leave “Use legacy install flow” unchecked — modern Dev Dashboard apps use managed install
7. Paste your Client ID and API secret key into the corresponding fields
8. Leave “Include orders older than 60 days” unticked unless your app has Shopify approval for read_all_orders
9. Click Connect Shopify

You’ll be redirected to Shopify’s consent screen. Approve the install. Shopify hands you back to HARi, which:

• Validates the OAuth handshake
• Stores your access token (encrypted)
• Registers all 14 webhook subscriptions on your store
• Triggers an initial sync of your customers, orders, and products if you have the e-commerce solution installed

The connected card appears with a “Custom Shopify app (xxxx…xxxx)” badge showing the last 5 characters of your Client ID — that’s your confirmation that HARi is using your app credentials, not the shared HARi public app.

What gets synced

Once connected, HARi keeps in sync continuously via Shopify webhooks. No polling, no scheduled jobs.

Topic	What HARi does
orders/create	Creates an Invoice in HARi with all line items
orders/updated	Updates the invoice (price changes, fulfillment status, refunds)
orders/cancelled	Marks the invoice cancelled
orders/delete	Soft-deletes the invoice (recoverable for 30 days)
customers/create	Creates a Contact, linked to future orders by email
customers/update	Updates the contact (new address, marketing consent change, tags)
customers/delete	Soft-deletes the contact
products/create / products/update / products/delete	Mirrors the catalogue
customers/data_request	Logs the GDPR data-export request for your records
customers/redact / shop/redact	Triggers customer / shop redaction per Shopify policy
app/uninstalled	Cleans up the integration on HARi side if you uninstall from Shopify

Initial sync (when the integration is first connected) pulls historical data using Shopify’s bulk APIs:

• Products: typically a few seconds for small catalogues, up to a minute for 10,000+ variants
• Customers: ~1 minute per 5,000 customers
• Orders: limited to the last 60 days by default (Shopify policy on the standard read_orders scope). If you have read_all_orders approved, full history is available

You can trigger a manual full or incremental resync at any time from Settings → Integrations → Shopify → Sync section.

Older order history (>60 days)

By default, Shopify limits the read_orders scope to orders placed in the last 60 days. To access older orders, your Shopify app needs the protected read_all_orders scope, which Shopify approves separately from app installation.

1. In Shopify Partners (or your Dev Dashboard) → your app → API access requests → request access to read_all_orders
2. Provide justification — Shopify will ask why you need historical orders. Common answers: customer lifetime value analysis, cohort/retention metrics, churn prediction, full historical CRM record
3. Wait for Shopify’s review (~5-10 business days)
4. Once approved, add read_all_orders to your app’s scope list and release a new version
5. In HARi, tick “Include orders older than 60 days” in Advanced settings, then Disconnect → Reconnect so Shopify re-grants the upgraded scope

Without approval, HARi can still sync everything new — order history beyond the 60-day window is the only limitation.

Managing the integration

Disconnect

Settings → Integrations → Shopify → Disconnect in HARi:

• Revokes your access token on Shopify
• Removes the integration record from HARi
• Stops new orders/customers/products from syncing
• Does not delete any data already synced into HARi

You can reconnect at any time using the same steps above.

Move the connection to a different HARi workspace

If you originally connected your store to the wrong HARi workspace, disconnect from the old workspace first, then connect from the new one. HARi enforces one-shop-per-workspace globally, so you’ll see a clear error if you try to install on a second workspace without disconnecting first.

Uninstall from Shopify

Uninstalling the HARi app inside your Shopify admin (Apps → HARi → Uninstall) automatically:

• Notifies HARi via the app/uninstalled webhook
• HARi marks the integration as inactive
• After 48 hours, Shopify sends a shop/redact webhook — HARi soft-deletes Shopify-sourced data for compliance

If you simply want to pause syncing, disconnect from HARi instead — that’s reversible. Uninstall is the harder break.

Common errors

What you see	What it means	What to do
”Installation link is invalid” on Shopify consent screen	The Shopify app’s configuration doesn’t match what HARi sent: scope mismatch, no released version, or store not in distribution list	Verify a version is Active (not draft), your *.myshopify.com domain is in the Distribution allowed stores, and Use legacy install flow matches the checkbox in HARi (both off for modern apps)
“OAuth error: missing_shopify_permission: read_all_orders”	The “Include orders older than 60 days” box is ticked in HARi, but your Shopify app doesn’t have approval for the read_all_orders protected scope	Untick the option, OR request scope approval first (see “Older order history” above)
“This app is under review” on Shopify	You’re trying to install HARi’s public App Store app, which is still being reviewed by Shopify	Use the custom app path on this page instead until the public app is approved
”This Shopify store is already connected to another HARi workspace” (HTTP 409)	The shop is already linked to a different HARi workspace	Disconnect it from the other workspace first, then connect from the current one
No webhooks arriving after install	Either the install never finished, or your Shopify app’s permissions don’t include the topics HARi subscribed to	Disconnect and reconnect. The reconnect re-registers all 14 webhook subscriptions
”Could not load Shopify connection status”	Transient network issue between HARi and Shopify	Reload the page. If it persists, contact support — there may be a Shopify API outage

FAQ

Can a single Shopify store connect to multiple HARi workspaces? No. One shop maps to exactly one HARi workspace. This is enforced by HARi to prevent webhook data from accidentally double-writing into two CRMs.

Can one HARi workspace connect to multiple Shopify stores? Yes. If you operate multiple Shopify stores under the same brand, connect each one separately. Customers and orders from each store flow into the same workspace, tagged by store domain.

Will reconnecting a store wipe the previously-synced data? No. Disconnect leaves all synced records in HARi. Reconnecting picks up where you left off — only changes that happened during the disconnect window will be missed (Shopify holds 48 hours of webhook retries, so even short disconnects usually catch up automatically).

How do I know the integration is healthy? Settings → Integrations → Shopify shows a connected card with the shop name, plan, currency, timezone, last sync time, and a counter of products/customers/invoices. If syncing is active you’ll see a progress block; if the last sync failed you’ll see an error badge with a link to the queue.

What does “Use legacy install flow” actually mean? It’s a Shopify app config setting (use_legacy_install_flow). Modern Shopify apps created in the Dev Dashboard default to false — Shopify manages installation centrally. Older apps use true, where the app requests scopes via OAuth URL parameter. HARi supports both, but you must match the toggle in HARi to whichever the Shopify app config says. For new custom apps in 2026, leave both unchecked.

My custom app is in the old “Develop apps” UI inside my Shopify store admin — can I use that? Shopify deprecated creating new “Develop apps” on 2026-01-01. Existing ones still work; new merchants can’t create them. The path documented on this page (Partners or Dev Dashboard custom distribution) is the supported modern equivalent.

Where are my API credentials stored? Encrypted at rest using AES-256-GCM inside your HARi tenant database. They’re never shared with other tenants or shipped in environment variables. Only the encrypted Shopify access token and (for custom apps) the API secret key leave HARi’s database — and only when HARi calls Shopify or verifies an incoming webhook.

Is two-way sync supported? HARi reads from Shopify (orders, customers, products in). Some write operations are supported for future scenarios (creating draft orders from HARi, updating customer tags) — those are documented per workflow when applicable. The default flow is read-only: changes happen in Shopify and reflect in HARi.

What if I’m not on Shopify Plus and the public app isn’t approved yet? The public app is in active review with Shopify. Estimated approval is within 1-4 weeks. If you want early access, contact us — we can generate a per-store custom install link as a bridge solution.

Get help

If you hit an error not listed above, or your custom app setup isn’t behaving as expected, contact support with:

• Your HARi workspace subdomain (e.g. acme.haricrm.com)
• Your Shopify store domain (e.g. mystore.myshopify.com)
• The exact error message text and any error code
• A screenshot of your Shopify app’s Configuration tab (with the Secret field collapsed)

We typically respond within one business day.