Shopify Integration Guide
Connect your Shopify store to ZaLinkAI using Admin API 2024-01 and give AI agents full commerce capabilities.
OAuth 2.0 Authentication
Shopify uses OAuth 2.0 to install custom and public apps on merchant stores.
App Installation
Merchant clicks "Install" from the Shopify App Store or your install URL. They are redirected to Shopify's OAuth consent screen with your client_id, scopes, and redirect_uri.
Permission Grant
The merchant reviews and approves the requested API scopes. Shopify validates the request and generates an authorization code.
Callback & Verification
Shopify redirects to your callback URL with the code, shop domain, and HMAC signature. Verify the HMAC to ensure the request is authentic.
Token Exchange
Exchange the code for an offline access token. Shopify offline tokens do not expire and do not require refresh -- they persist until the app is uninstalled.
Required API Scopes
ZaLinkAI requests the minimum scopes needed for full AI agent functionality.
read_products
Access product catalog, variants, images, and collections.
write_draft_orders
Create draft orders for AI-powered cart and checkout flows.
read_orders
Retrieve order history, fulfillment status, and tracking data.
read_customers
Access customer profiles, addresses, and purchase history.
write_checkouts
Generate secure checkout URLs for conversational commerce.
read_inventory
Track real-time stock levels across locations.
read_shipping
Access shipping zones, rates, and delivery profiles.
read_discounts
Retrieve active discount codes and price rules.
Platform Capabilities
Full overview of AI agent actions available through the Shopify connector.
Product & Collections
- Product catalog with variants and metafields
- Smart and custom collection sync
- Image and media management
- Multi-location inventory tracking
Cart & Checkout
- Draft Order-based cart system
- Secure checkout URL generation
- Discount code application
- Abandoned checkout recovery
Customer Management
- Customer profiles and segments
- Address book and contact data
- Order history per customer
- Customer tags and notes
Webhooks & Events
- HMAC-SHA256 signature verification
- Order, product, and customer events
- App uninstalled lifecycle event
- Automatic retry with exponential backoff
Offline Access Tokens
Shopify offline tokens provide persistent access that simplifies integration.
Offline tokens do not expire and do not require periodic refresh.
Tokens remain valid until the merchant uninstalls the app.
ZaLinkAI encrypts tokens with AES-256 before storage.
If the merchant reinstalls, a new token is issued automatically.
Troubleshooting
Common issues and resolutions for the Shopify integration.
invalid_hmac
HMAC signature verification failed on the OAuth callback.
Ensure you are computing HMAC-SHA256 using the correct client_secret and comparing all query parameters (excluding hmac itself).
access_denied
Merchant did not approve the required scopes.
The merchant must approve all requested scopes. Redirect them to the install URL again.
shop_not_found
The provided shop domain is invalid or the store is deactivated.
Validate the shop domain format (my-store.myshopify.com) before initiating OAuth.
api_version_unsupported
The requested API version is deprecated or invalid.
ZaLinkAI uses Admin API 2024-01. Ensure your app configuration matches this version.