Shopify Integration Guide

Flexsee relies on Shopify order, product, and customer data to power commerce models. Follow this checklist to connect a shop and verify data flow.

1. Install the Flexsee Shopify app

1. Log into the merchant's Shopify admin.
2. Navigate to the installation URL provided by Flexsee.
3. Approve requested scopes:
   • read_products
   • read_orders
   • read_customers
   • read_inventory
4. Upon installation the callback registers the store in shopify_stores and issues a long-lived access token.

2. Configure webhooks

Flexsee listens for the following events:

Topic	Purpose
orders/create	Trigger marketing enrichments and post-purchase tests
orders/paid	Feed model freshness tracking
customers/update	Sync profile attributes

Webhooks are provisioned automatically by the installer. You can confirm under Settings → Notifications → Webhooks in Shopify admin. All webhooks point to https://api.flexsee.ai/shopify/webhooks with the shared secret stored in shopify_stores.sharedSecret.

3. Run a test order

1. Enable Shopify’s Bogus Gateway in payment settings.
2. Create a draft order or go through the storefront checkout.
3. Use card number 1 repeated 16 times to simulate a successful payment in the Bogus Gateway.
4. The Flexsee admin panel should show the order under the organization within ~30 seconds.

If the order does not appear:

• Check the webhook delivery log in Shopify (look for non-200 responses).
• Verify the Flexsee backend logs for /shopify/webhooks requests.
• Ensure the store’s sync_status is not errored in the database.

4. Monitor sync health

The dashboard integration tile reports:

• Last sync time
• Number of products and orders ingested
• Webhook status

Flexsee staff can also inspect admin → Organizations → Data & Models for deeper stats.

5. Flexsee AI Predictions app and tracking pixel

The Flexsee AI Predictions Shopify app includes a web pixel extension that sends behavioral events (page views, product views, add to cart, checkout) to Flexsee for AI training and analytics.

Reconnect the pixel when it shows "Disconnected"

If Flexsee AI Predictions appears as Disconnected under Settings → Customer events → Pixels (or App pixels), reconnect it as follows:

1. Get your Organization ID

   • In the Flexsee dashboard, go to Settings (or open the Flexsee AI Predictions app in Shopify and check its Settings page). Your Organization ID is a UUID (e.g. 3b033270-c656-4817-ae29-105c9eef6fe1). The Shopify app’s Settings page shows this if the app is installed.

2. Open the pixel in Shopify

   • In Shopify admin go to Settings → Customer events (or Settings → Pixels).
   • Open the App pixels tab.
   • Find Flexsee AI Predictions and click the row or the ⋯ menu → Manage / Configure (wording may vary by Shopify version).

3. Configure and enable

   • Set Organization ID to your Flexsee organization ID (required).
   • Optionally set API Endpoint to https://api.flexsee.ai/ingest/events if it’s blank.
   • Optionally set Meta Pixel ID if you use Meta Ads (see below).
   • Save and ensure the pixel is enabled (turned on). The status should change from Disconnected to Connected.

4. Set data access to Always on

   • In the same Customer events → App pixels screen, open Flexsee AI Predictions (click the row or ⋯ → Manage).
   • Under Mode, select Always on (not “Optimized”). This allows Flexsee to access all customer and business event data needed for AI training and recommendations. Click Apply.

5. If you use GraphQL

   • The pixel is managed by Shopify’s Admin API. The app reads it with the webPixel query (id, settings). To set or update settings programmatically you can use the webPixelUpdate mutation (requires write_pixels scope). The settings input must be a JSON object matching the extension’s schema (e.g. { "orgId": "<your-org-uuid>", "apiEndpoint": "https://api.flexsee.ai/ingest/events" }). After a successful update, enable the pixel in the Shopify admin UI if it isn’t already.

Optional: Meta Pixel ID (for Meta Ads Publish advert)

If you use Meta Ads and Publish advert to create conversion campaigns, you can have the Flexsee pixel also send ViewContent, AddToCart, and Purchase to your Meta Pixel. No extra code is required.

1. Create or use a Web Pixel in Meta Events Manager and connect it to your ad account.
2. In Shopify admin, go to Settings → Customer events and open the Flexsee AI Tracking Pixel.
3. Set Meta Pixel ID (optional) to your Pixel ID.

The pixel will forward those standard events to your Meta Pixel so Publish advert and conversion campaigns work. See Meta Pixel (for Publish advert) in the Meta Ads guide for more.

6. Removing or re-connecting a store

• Revoking the app token in Shopify immediately stops data access.
• Within Flexsee, the integration can be reconnected by re-running the install flow. The existing org records will be reused.

Troubleshooting tips

• "Missing keys: metaPixelId" (GraphQL webPixelCreate / webPixelUpdate) – Shopify validates settings against every key in the extension schema. Include all keys: orgId, apiEndpoint, enableConsoleLogging, samplingRate, metaPixelId. Use "" for optional fields you don't use (e.g. metaPixelId if you don't use Meta Pixel). See step 4 under "Reconnect the pixel" above for a full example.
• Duplicate orders – ensure the webhook secret matches; mismatched secrets cause validation failures and retries.
• Missing line items – confirm the order sync Lambda (if applicable) has access to the store token.
• 404 from /marketing/test/post-purchase – redeploy the marketing service; the admin test harness depends on that endpoint.