Statamic Shopify Laravel Package

Getting Started

1. Install and publish config

   composer require statamic-rad-pack/shopify
   php artisan vendor:publish --tag=shopify-config
   

2. Set credentials in .env. At minimum you'll need the store domain, API key/secret, and an access token (or the OAuth flow if you're building a custom app). Check config/shopify.php immediately after publishing — this is the file that changed most in v8.0.0. Confirm every key matches what the new shopify-app-php backend expects rather than assuming your v7 env vars carry over.
3. Look first at: config/shopify.php → the service provider bindings → the console commands (php artisan list | grep shopify) → the Antlers tags/fieldtypes the addon registers. The commands tell you what the package actually does (import, sync, webhook handling) faster than the docs.
4. First use case: point it at a development store, run the product import command to pull products into a Statamic collection, then render them with the package's tags in a template. Verify the data round-trips before touching cart/checkout.

Implementation Patterns

• Import once, then sync. Treat the initial product import as a seeding step and wire the ongoing sync to a scheduled command (->daily() or more frequently for price/stock). Keep the collection schema stable so re-imports are idempotent — match on Shopify product/variant ID, not title.
• Keep Shopify as the source of truth for commerce fields (price, inventory, availability) and Statamic as the source of truth for editorial fields (descriptions, imagery, merchandising). Attempting bidirectional sync on the same field is where projects break.
• Cart/checkout as a thin proxy. Use the package's cart endpoints to create a checkout and redirect to Shopify's hosted checkout. Don't try to reimplement tax/shipping calculation locally.
• Webhooks for order and inventory events rather than polling. Register them in the Shopify admin, point them at your app's webhook route, and let the package verify the HMAC. Use these to update local inventory or trigger fulfillment notifications.
• Cache aggressively. Product/cart reads hit the Shopify API; wrap template-facing reads in Statamic's cache tags and invalidate on webhook receipt rather than on a timer.
• Feature-flag the storefront integration in a config value so you can run a staging environment against a development store without editing code.

Gotchas and Tips

• v8.0.0 is a major, breaking release. The underlying library moved to shopify/shopify-app-php. Budget real migration time: authentication, session/token storage, GraphQL client construction, and webhook signature verification are all likely to differ from v7. Do not treat this as a composer update.
• Diff your published config. Major-version config changes are merged only when you republish; an old config/shopify.php silently overriding new defaults is the most common post-upgrade failure. Republish and merge by hand.
• Env var names may have changed. Grep your .env and deployment config for SHOPIFY_* keys and confirm each is still read by the new library. A missing key often surfaces as an opaque auth error rather than a clear exception.
• Webhook verification: confirm the new library's HMAC check is actually wired into your route. A verification step that was implicit in v7 may now require an explicit middleware or a different header/secret.
• Token lifecycle: the new app library distinguishes online vs. offline access tokens and may enforce expiry. Long-running import jobs using a short-lived token will fail mid-run — use an offline token for background commands.
• Rate limits: Shopify's GraphQL cost-based limits are not the same as REST's call-count limits. If you migrated any custom queries, check for throttling under load and add backoff/retry.
• Debugging: php artisan config:clear before every investigation, and log the raw API response — the package's exceptions tend to wrap the underlying client error, which hides Shopify's actual message.
• Extension point: if the package doesn't expose what you need (e.g. a specific mutation), resolve the underlying client from the container and call it directly rather than forking. Check the service provider's bindings for the client class name after the v8 swap.