Shopify Integration

Overview

Shopify is a location-specific e-commerce integration that connects an Upvendo location to a Shopify online store. It supports bidirectional menu sync -- you can import products from Shopify into Upvendo or export your Upvendo menu to Shopify. The integration uses Shopify's OAuth 2.0 flow for authentication and registers webhooks for real-time updates on products, collections, orders, inventory, and customers.

Purpose

This integration lets you synchronize your menu between Upvendo and a Shopify online store so that products, collections, variants, and orders stay in sync across both platforms.

Key Concepts

• OAuth Authentication: Shopify connects via an OAuth 2.0 flow where the merchant authorizes Upvendo to access their Shopify store. A legacy API key/secret method exists but is deprecated.
• Bidirectional Menu Sync: Menus can be imported from Shopify into Upvendo (collections become display groups, products become items) or exported from Upvendo to Shopify (display groups become collections, items become products).
• Webhook-Driven Updates: After OAuth authorization, Upvendo registers webhooks for products, collections, inventory, orders, and customers so that changes in Shopify trigger real-time updates in Upvendo.
• Shopify Collections = Upvendo Display Groups: Shopify custom collections and smart collections map to Upvendo display groups. The collection type (custom_collection or smart_collection) is preserved in external_ids.
• Shopify Variants = Upvendo Variant Groups: Products with multiple variants in Shopify are mapped to Upvendo variant groups, with each Shopify variant becoming an individual Upvendo item linked to the variant group.

Prerequisites

• An active Shopify store with admin access
• A location already created in Upvendo (Settings > Locations)
• The Shopify store must be on a plan that supports API access (custom apps or partner development stores)
• Payment providers (Stripe, Viva Wallet) must be configured separately -- Shopify does NOT handle Upvendo payments
• Branding profile configured (Settings > Brand)

Setup Steps

Step 1: Select Your Location

1. Go to Settings > Locations (/settings/locations)
2. Ensure the location you want to connect to Shopify is created and selected in the topbar

Step 2: Initiate OAuth Connection

1. Go to Shopify (/shopify)
2. Click Connect with Shopify
3. The system initiates an OAuth flow via the POST /shopify/{locationId}/oauth endpoint
4. You are redirected to Shopify to authorize Upvendo
5. After authorization, Shopify redirects back to the callback URL
6. The system stores the OAuth access token and registers webhooks automatically

Step 3: Import or Export Menu

• Import from Shopify: Click Import Menu to pull Shopify products and collections into Upvendo. This dispatches an ImportShopifyMenuJob that fetches both custom collections and smart collections, then creates corresponding display groups, items, and variant groups in Upvendo.
• Export to Shopify: Click Sync Menu to push your Upvendo menu to Shopify. This dispatches an ExportUpvendoMenuToShopifyJob that creates/updates Shopify collections and products from Upvendo display groups and items.

Step 4: Verify the Sync

1. Go to the Shopify page and check the sync status
2. Review imported/exported items under Menus > Items (/menus/items)
3. Confirm products appear correctly in your Shopify admin

Data Sync Details

What Syncs

Upvendo Entity	Shopify Entity	Notes
Display Group	Collection	Custom collections and smart collections
Item	Product	Single-variant products become standalone items
Variant Group	Product (multi-variant)	Multi-variant products map to variant groups
Item (in group)	Product Variant	Each variant becomes an Upvendo item
Menu	--	A Shopify-specific menu is created automatically
Images	Product Images	Images sync via URL references

Sync Direction

• Import (Shopify to Upvendo): Fetches collections and products via Shopify Admin API (version 2023-10), creates Upvendo display groups, items, variant groups, and a menu with Shopify channel visibility.
• Export (Upvendo to Shopify): Pushes Upvendo display groups as collections and items as products to Shopify. Also creates product-collection associations via Shopify Collects API.
• Webhooks (Real-time): Registered webhook topics include products/create, products/update, products/delete, collections/create, collections/update, collections/delete, inventory_items/update, orders/create, orders/updated, orders/cancelled, orders/fulfilled, orders/paid, order_transactions/create, customers/create, customers/update, customers/delete.

Conflict Resolution

• When importing, existing items are matched by external_ids.shopify.id and external_ids.shopify.variant_id; matched items are updated, new items are created.
• When exporting, existing Shopify products are matched by stored external IDs and updated via PUT; new products are created via POST.
• Inactive Shopify products (status !== 'active') are soft-deleted in Upvendo during import.

Actions

Connect

• OAuth (Recommended): POST /api/backoffice/shopify/{locationId}/oauth initiates the OAuth flow. The callback at /shopify-callback exchanges the authorization code for an access token and stores credentials.
• Legacy API Keys (Deprecated): The orchestrator's enable() method accepts shop_name, api_key, api_secret, and is_sandbox parameters directly.

Sync

• Export Menu to Shopify: POST /api/backoffice/shopify/{locationId}/sync-menu -- dispatches ExportUpvendoMenuToShopifyJob
• Import Menu from Shopify: POST /api/backoffice/shopify/{locationId}/import-menu -- dispatches ImportShopifyMenuJob
• Get Status: GET /api/backoffice/shopify/{locationId}/ -- returns integration status, credentials, and sync details
• Update Settings: PUT /api/backoffice/shopify/{locationId}/ -- updates integration credentials or settings

Disconnect

• Disable Integration: DELETE /api/backoffice/shopify/{locationId}/ -- disables the Shopify integration for the location

Fields

Credentials (stored in ThirdPartyIntegration.credentials)

Field	Type	Description
shop_name	string	The Shopify store domain (e.g., example.myshopify.com)
access_token	string	OAuth access token for Shopify Admin API
scopes	string	Granted OAuth scopes (comma-separated)
auth_method	string	oauth for OAuth flow
api_key	string	(Legacy) Shopify API key
api_secret	string	(Legacy) Shopify API secret

Settings (stored in ThirdPartyIntegration.settings)

Field	Type	Description
sync_menus	boolean	Whether menu sync is enabled (default: true)
sync_orders	boolean	Whether order sync is enabled (default: true)
sync_inventory	boolean	(Legacy) Whether inventory sync is enabled
sync_prices	boolean	(Legacy) Whether price sync is enabled

OAuth Scopes Requested

read_products, write_products, read_product_listings, read_inventory, write_inventory, read_orders, write_orders, read_draft_orders, write_draft_orders, read_order_edits, write_order_edits, read_customers, write_customers, read_locations, read_price_rules, write_price_rules, read_merchant_managed_fulfillment_orders, write_merchant_managed_fulfillment_orders

Business Rules

• A location can have only one Shopify integration at a time. Attempting to enable when already enabled returns a 400 error: "Shopify integration already enabled for this location."
• Disabling a non-existent integration returns a 400 error: "Shopify integration not enabled for this location."
• The OAuth access token is verified via HMAC signature validation using the Shopify client secret.
• During import, a dedicated Upvendo menu is created with Shopify channel visibility if one does not already exist. The menu is named "Shopify Default Menu."
• Modifier groups are NOT supported for Shopify sync -- only items, variant groups, and display groups are synchronized.

FAQs

How do I connect my Shopify store?

Go to the Shopify page in the backoffice, click "Connect with Shopify," and complete the OAuth authorization flow. Your Shopify store will be connected automatically.

Can I sync in both directions?

Yes. Use "Import Menu" to pull products from Shopify into Upvendo, or "Sync Menu" to push your Upvendo menu to Shopify.

Does Shopify handle payments for kiosk or online ordering?

No. Shopify integration handles menu and product sync only. You still need Stripe (online) or Viva Wallet (kiosk) for payment processing in Upvendo.

What happens to inactive Shopify products during import?

Products with a status other than active are soft-deleted in Upvendo. If the product is reactivated in Shopify and re-imported, it will be restored.

Are modifier groups supported?

No. Shopify does not natively support modifier groups the way Upvendo does. Only items, variant groups, and display groups are synchronized.

Troubleshooting

"Shopify integration already enabled for this location"

The location already has an active Shopify integration. To reconnect, first disable the existing integration via the Shopify page, then connect again.

"Missing required Shopify credentials (access_token or shop)"

The OAuth flow did not complete successfully, or credentials were lost. Disconnect and reconnect the Shopify integration using OAuth.

Products not appearing after import

Check the sync status on the Shopify page. The import job runs asynchronously -- it may take a few minutes. Verify the Shopify store has products in collections (uncollected products are not imported).

"Failed to create Shopify product" during export

Verify the OAuth access token is still valid (tokens can be revoked in Shopify admin). Check that the Shopify store has not exceeded API rate limits. Try again after a few minutes.

Webhook events not updating Upvendo

Verify webhooks are registered in your Shopify admin under Settings > Notifications > Webhooks. If missing, disconnect and reconnect the integration to re-register webhooks. The webhook endpoint is POST /shopify-webhook with HMAC verification middleware.

Assistant Guidance

When a user asks about Shopify integration:

• Clarify whether they want to import from Shopify (pull products into Upvendo) or export to Shopify (push Upvendo menu to Shopify).
• Remind them that Shopify does NOT handle payments in Upvendo -- they still need Stripe or Viva Wallet.
• If they report sync issues, ask them to check the sync status on the Shopify page and verify their OAuth connection is active.
• For new setups, guide them through: create location > connect via OAuth > import or export menu.
• If they mention API keys or secrets, note that the legacy API key method is deprecated; recommend OAuth instead.

Relations

Depends On

• Locations (a location must exist before connecting Shopify)
• ThirdPartyIntegration model (stores credentials, settings, sync status)
• Menu system (display groups, items, variant groups)

Affects

• Menu Items (created/updated during import)
• Display Groups (created/updated during import/export)
• Variant Groups (created/updated during import/export)
• Menus (a Shopify-specific menu is created with Shopify channel visibility)