Connect Shopify and monitor sync health

Overview

Shopify starts at /integrations and continues in the connected-store workroom at /integrations/shopify. A reliable rollout authorizes the store, verifies the automatic first catalog import, and maps each channel item to a Formuley Product OS product, Product OS SKU, or formula fallback.

The Shopify feature requires an eligible integration plan and may be unavailable while launch controls are off. The interface is the source of truth for the current availability state.

1. Connect to Shopify

1. Open /integrations and find Shopify.
2. Select Connect.
3. Enter the canonical store domain, such as mystore.myshopify.com. Use the .myshopify.com domain, not a custom storefront URL.
4. Select Connect again and complete Shopify's authorization screen with a store administrator account.
5. When Shopify returns to Formuley, confirm the connection is Connected and open Details.

The callback registers the connection and required webhooks, then automatically attempts the first import of up to 250 products and their variants. This import is best effort: Shopify can return Connected even if that initial attempt fails, so verify the catalog before mapping.

2. Verify or refresh the product catalog

After authorization, open /integrations/shopify and confirm the expected products and variants appear. Import Products is a refresh or retry action: select it, review the dialog, then select Start Import when the automatic attempt was incomplete or the Shopify catalog changed. The result reports how many products were imported and updated.

Run Import Products again after adding or changing Shopify catalog records that should be available for new mappings.

3. Map products to Formuley records

Under Product mappings, select Add mapping and choose the Shopify product or variant first. Then assign one of these destinations:

• a Product OS product;
• a Product OS SKU; or
• a formula fallback when a Product OS target is not the right record yet.

The mapping stores the Shopify product and variant identity with the selected Formuley destination. Create explicit variant mappings when variants need different destinations. Unmapped order lines can still arrive, but their reconciliation remains pending and they cannot provide reliable formula-level COGS or margin context.

4. Understand order and financial updates

Shopify order webhooks cover create, update, paid, canceled, and fulfilled events. The normalized financial status determines the accounting behavior:

• paid, refunded, and partially refunded order states are eligible for revenue refresh;
• net merchandise revenue is allocated across line items after current discounts, tax, and shipping context are handled;
• mapped formula lines can carry a cost-per-unit snapshot into COGS and reconciliation;
• reprocessing replaces prior revenue entries for the same order instead of intentionally duplicating them.

Shopify order processing does not deduct raw ingredient stock. Raw ingredients are consumed by the batch-production workflow; deducting them again when a finished product sells would double count material usage. The order record tracks revenue, the available COGS snapshot, and reconciliation status.

5. Review Orders, Profit Guardian, and sync health

Use /orders to inspect connected order records. Use /profit-guardian only after mappings and revenue reconciliation are trustworthy.

The Sync history table in /integrations/shopify shows:

• run type and start time;
• completed, partial, failed, or other current status;
• succeeded and failed record counts; and
• whether the run came from a webhook or requested sync.

Select Sync now from the Shopify card in /integrations when you need a requested order sync. Catalog refresh remains under Import Products in the detail workroom.

Check the rollout

• The integration card and detail page both show the same connected store.
• Catalog count reflects the expected products after the automatic attempt or a completed Start Import refresh.
• Every product or variant that should power formula-level reporting has one intended mapping.
• A test paid order appears in /orders with the correct current total and line quantities.
• Revenue, discount allocation, and available COGS reconcile before Profit Guardian is trusted.
• A repeat order update does not create duplicate revenue rows.
• Sync history shows the test run and exposes failures instead of looking healthy.

Troubleshooting

Authorization fails

Confirm the lower-case .myshopify.com domain and store-admin access. Retry Reconnect from /integrations. If Formuley reports that reinstall is required, uninstall the Formuley app in Shopify Settings → Apps and sales channels, then begin the Formuley connection flow again.

The store is connected but no products appear

The initial automatic attempt is non-fatal, so a connected store can still have an empty catalog. Open /integrations/shopify, select Import Products, then Start Import to retry.

Orders arrive without formula-level margin

Check the exact Shopify product and variant under Product mappings. Add the Product OS or formula target, then request or wait for the next applicable order update. Historical financial interpretation should be reconciled with the finance owner before reuse.

A sync fails or is partial

Open Sync history and compare succeeded and failed counts. Correct authorization or mapping problems before repeating Sync now. Large catalogs may require multiple requests, so judge completion from the recorded results rather than button timing.

The wrong store is connected

Select Disconnect only after confirming the target connection. Disconnect changes the connection state; it does not replace your responsibility to preserve and reconcile previously synced business records.

Related routes

• /integrations
• /integrations/shopify
• /orders
• /reports/sales
• /profit-guardian

Next docs

• Source, buy, and reconcile materials
• Reports and audit exports
• Costs, pricing, and margin guardrails