Shopify Integration

Authentication Model

The app uses the Shopify Dev Dashboard with client credentials grant — not the standard OAuth install flow. Access tokens are exchanged server-to-server and cached (encrypted) for 24 hours via ShopifyTokenManager.

WARNING

The store and the Dev Dashboard app must be in the same Shopify organization. If a store is transferred out of the organization, the app will stop working.

Dev Dashboard Setup

1. Create the App

1. Open the Shopify Dev Dashboard
2. Click Create app and choose Start from Dev Dashboard
3. Name it (e.g., "LamaShopi -- Shop Name")

2. Create a Version

In the Versions tab, configure:

• Scopes: read_products, read_inventory, read_customers, read_locations
• App Proxy:
  • Prefix: apps
  • Subpath: lamashopi
  • Proxy URL: https://your-domain.com/shopify/proxy
• Webhooks API version: 2025-04

Click Release to publish the version.

3. Install the App

From the app's Home tab, click Install app, select the store, and confirm.

4. Copy Credentials

Go to Settings and copy:

• Client ID to SHOPIFY_CLIENT_ID
• Client secret to SHOPIFY_CLIENT_SECRET

App Proxy

The App Proxy is how the storefront theme communicates with the companion app. Shopify proxies requests from /apps/lamashopi/* to your Laravel app at /shopify/proxy/*, adding an HMAC signature for verification.

Route Structure

All proxy routes are registered under /shopify/proxy/ with the shopify.app_proxy middleware:

/shopify/proxy/inventory/{handle}     → InventoryController
/shopify/proxy/wishlists/*            → WishlistController
/shopify/proxy/oos/*                  → OosController
/shopify/proxy/shipping/thresholds    → ShippingController
/shopify/proxy/stores                 → StoreLocatorController
/shopify/proxy/bundles/*              → BundleController

Routes are only registered when their corresponding feature flag is enabled.

HMAC Verification

The VerifyShopifyAppProxy middleware verifies the HMAC signature on all incoming proxy requests. It also optionally checks that the request comes from the configured SHOPIFY_SHOP_DOMAIN.

Webhooks

Registered Webhooks

Webhooks are registered via php artisan shopify:register-webhooks:

Topic	Route	Handler
inventory_levels/update	/shopify/webhooks/inventory-update	WebhookController::inventoryUpdate

This webhook is only registered when inventory or OOS features are enabled.

GDPR Webhooks

GDPR compliance webhooks must be configured manually in the Dev Dashboard version settings:

Topic	Handler
customers/data_request	GdprWebhookController::customersDataRequest
customers/redact	GdprWebhookController::customersRedact
shop/redact	GdprWebhookController::shopRedact

Set the compliance webhook URL to https://your-domain.com/shopify/webhooks/ — Shopify appends the topic path automatically.

HMAC Verification

The VerifyShopifyWebhook middleware verifies the X-Shopify-Hmac-Sha256 header on all incoming webhook requests.

Admin API

The ShopifyClient service handles all communication with Shopify's Admin API:

• GraphQL with automatic throttle detection and retry
• REST for endpoints not available via GraphQL
• Authentication via ShopifyTokenManager (client credentials grant, cached encrypted token)

Secret Rotation

To rotate the client secret:

1. Generate a new secret in the Dev Dashboard (Settings then Rotate secret)
2. Update SHOPIFY_CLIENT_SECRET in .env
3. Clear the cached token: php artisan cache:forget shopify:access_token
4. Restart queue workers: php artisan queue:restart

Scope Changes

When new features require additional API scopes:

1. Create a new version in the Dev Dashboard with updated scopes
2. Release the version
3. The merchant must approve the new scopes in the Shopify admin