Shopify

Overview

Use this page if you want to connect a Shopify store to VAT Engine.

This guide is for merchants, agencies, and developers who are setting up or managing a customer account connection.

Billing And Access

VAT Engine's current public Shopify app posture is free. Installing, reconnecting, syncing, and using Shopify App Home do not require a Stripe checkout or another external paid subscription.

VAT Engine may offer separate services outside the Shopify app, but those services do not unlock or limit Shopify connector functionality. If VAT Engine introduces paid App Store plans later, it will use Shopify's billing solution and show the applicable plan and approval flow in Shopify Admin.

What The Shopify Connection Does

• Connects one Shopify store to one VAT Engine customer account
• Stores the Shopify credentials needed for future sync and webhook handling on the server side only
• Registers the required operational Shopify webhook topics for that specific store after install or reconnect
• Minimizes retained Shopify webhook data and refetches the authoritative order snapshot before VAT Engine imports filing-relevant changes
• Lets you map the store to a VAT Engine source profile for reporting
• Automatically reuses the connected store mapping and matching source aliases when imported Shopify activity should land under a specific VAT Engine source profile
• Requires a disconnected store to reconnect before account source choices are shown again
• Lets account operators preview one Shopify order and its normalized VAT Engine events before running an import
• Prepares the account for imported order activity and review workflows

App Configuration Ownership

VAT Engine now separates app-level Shopify configuration from per-store connection data.

• Per-store rows in Dashboard -> Integrations own the verified Shopify shop identity, source mapping, connection status, and whether VAT Engine holds tokens for that specific store.
• The read-only Shopify app configuration panel on the same page shows the shared app URL, OAuth callback URL, privacy webhook URL, requested scopes, and Shopify API versions used by every Shopify install on that VAT Engine deployment.

Shared Shopify app settings cannot be edited store by store. If the displayed permissions or URLs do not match the connection instructions supplied for your account, contact VAT Engine support before reconnecting.

Background sync, reconciliation, webhook inspection, and historical backfill use the stored Shopify authorization. The dashboard shows whether authorization is available but never returns Shopify credentials to the browser.

Data Minimization And Approval Posture

VAT Engine's current Shopify connector is intentionally narrow.

• The deployment-level install scope policy allows read_orders, read_products, read_merchant_managed_fulfillment_orders, read_third_party_fulfillment_orders, and, when older-history access is needed, read_all_orders.
• Shopify order fetches are limited to order, refund, duty and additional-fee, tax, channel, country-code, and product-tax-mapping evidence such as product or variant IDs, SKU, tags, category, app-owned product metafields, Shopify's gift-card flag, and line-level taxability signals.
• VAT Engine reads Shopify's low-sensitivity order-level taxExempt flag, but the minimum-access query does not request the protected purchasing-entity field. To provide affirmative evidence, create a merchant-owned Order metafield in Shopify Admin with namespace and key vat_engine.customer_type, type single-line text with preset choices, and only b2b and b2c choices. VAT Engine reads the same value and Shopify revision in recent-order and historical-import paths without permission to write orders. A current validated value supplies the order's B2B or B2C classification input. VAT Engine does not guess from taxExempt, customer presence, purchasing-entity context, a missing field, or one default applied to every store order. Missing, malformed, wrong-type, stale, or conflicting values remain unknown/needs review, not proof that an order is B2C. Deleting or invalidating the field also removes the previous affirmative value from current use; correcting it with a later valid revision restores the evidence. VAT Engine orders recent and historical observations so a delayed older import cannot restore a value that a later import removed. If VAT Engine cannot reserve reliable evidence tracking when an import starts, that import remains queued instead of appearing to run indefinitely. Routine secure credential renewal for the same verified store does not remove its current customer-type evidence. App Home Settings shows the exact field contract and links to Shopify custom data and orders. Save the value in Shopify Admin, then queue reconciliation or refresh App Home so VAT Engine can observe the new revision. Review customer type before using the order in filing-grade output. Order-metafield previews describe only the metafield classification result; they do not report native Shopify buyer attribution as unavailable when that evidence is intentionally not used. Native and hybrid modes show a bounded buyer-attribution status when those choices are available and selected. Eligible Shopify development stores can use these choices for controlled testing after protected customer data is selected for the development app. Production stores see these choices only after Shopify approves the corresponding public-app access; development access never substitutes for production approval.
• Large Shopify product tags or app-owned product-metafield payloads are reduced to bounded matcher-safe signals before VAT Engine stores canonical evidence, so unusually large catalog metadata degrades to reviewable truncation instead of breaking imports.
• Customer contact fields and street-level address fields are not part of the current VAT Engine Shopify order adapter.
• Country-code data is used only where Shopify has approved the required access. If that evidence is unavailable, affected VAT classifications remain in review. Shopify orders can omit both shipping and billing addresses; VAT Engine keeps those orders in the review queue instead of repeatedly failing webhook processing. They remain outside filing-ready totals until a valid tax destination is available and the classification is resolved.

Shopify's app-review model expects apps to request only the minimum data they actually need. If VAT Engine ever needs broader Shopify customer data in the future, that should be treated as a new explicit app-policy change rather than a per-store toggle.

Before You Start

Have these ready:

1. A VAT Engine customer account with dashboard access
2. Admin access to the Shopify store
3. For a controlled dashboard connection only, the store's permanent myshopify.com domain, for example your-store.myshopify.com
4. Optional but recommended: the VAT Engine source profile that should represent this store
5. Optional: your preferred display label for the store inside VAT Engine

Shopify's official documentation treats the permanent .myshopify.com domain as the stable shop identifier for app configuration and embedded app context. Use that value in VAT Engine rather than a storefront custom domain or an /admin URL.

Recommended Connection Flow

Public Shopify Flow

This is the target public flow after VAT Engine's managed-install authorization gate is complete; it is not evidence that the App Store listing is already available.

1. Open VAT Engine from the intended Shopify-owned installation surface in Shopify Admin.
2. Review and approve the requested Shopify permissions.
3. Sign in to or create the VAT Engine account that should own the store connection.
4. Explicitly confirm that the verified Shopify store should link to that VAT Engine account.
5. Return to Shopify App Home and confirm the connection health and source mapping.

The public flow does not accept a manually entered shop domain and does not expose a dashboard reconnect action. Reopen the app from Shopify Admin if authorization must be restored.

Controlled Custom-App Dashboard Flow

Use this flow only when the deployment operator confirms that controlled dashboard distribution is enabled. It is not the public App Store installation path.

1. Sign in to the VAT Engine customer account that should own the Shopify store connection.
2. Open Dashboard -> Integrations.
3. Optional but recommended: create a matching Source profile first if you want reporting grouped under a stable store label.
4. Create a new Shopify integration in VAT Engine.
5. Enter the store's permanent your-store.myshopify.com domain and optional display label.
6. Click Connect Shopify.
7. Review and approve the requested scopes in Shopify.
8. Wait for VAT Engine to return you to Dashboard -> Integrations.
9. Confirm the integration status looks correct and that the source profile mapping is what you expected.

Embedded Shopify Admin Flow

Open VAT Engine from Shopify Admin to install or manage the connection.

• For a Shopify-managed installation, App Home verifies the current store and then asks you to sign in to or create the VAT Engine account that will own the connection. The confirmation link expires if it is not completed promptly. Reopen VAT Engine from Shopify Admin and complete the newest tab if an older flow has expired or been replaced.

• For a previously disconnected store, App Home asks you to sign in to the VAT Engine account that owns the previous connection and confirm the store link before access is restored. If the store has changed ownership, contact VAT Engine support instead of linking it to another account.

• When App Home confirms that the current Shopify installation needs recovery, it starts the secure reconnect flow once. If Shopify requires additional merchant action, App Home shows the error instead of repeatedly redirecting; you can then choose Reconnect explicitly.

• If connection verification overlaps with a reconnect, VAT Engine checks the latest authorization before saving health status. Shopify throttling or temporary availability issues do not disconnect the store.

• When automatic recovery overlaps with an explicit reconnect in the current App Home page, the newer action remains in control. An older response cannot replace its recovery destination.

• Shopify App Home now shows the connected store name, current connection state, granted scopes, source profile linkage, current free Shopify plan, protected-customer-data posture, webhook health, and recent sync status.

• Home groups the store, source profile, plan, last successful sync, webhook activity, and automation status in one connection overview. Missing mappings or activity are identified directly instead of appearing as empty values.

• App Home activity requests are limited to the connected store and load recent import work in bounded pages. They show progress, affected records, timestamps, and safe recovery guidance without exposing background-worker details or stored Shopify payloads.

• Use Setup to work through the ordered connection, source, tax-default, permission, automatic update, data-access, and first-import steps. Each unfinished step presents one next action, and a step is marked complete only after VAT Engine confirms the saved store state. Use Activity to review sync health or start other imports, and Settings to reconnect or disconnect the store. Select the app name in Shopify Admin to return to Home.

• In the Choose a VAT source step, App Home shows the current source and the active Shopify-compatible sources available to your VAT Engine account. Select a different source, confirm that it should represent this store for VAT reporting, and then choose Confirm source. If no source is available, open VAT Engine from the empty state and create one, then choose Reload VAT sources or return focus to App Home.

• In the Complete source tax defaults step, review the source name, sales channel, supplier establishment country, default dispatch country, and whether the marketplace is normally the deemed supplier. Countries must use assigned two-letter ISO codes such as DE or NL; arbitrary placeholders are rejected. Order and fulfillment evidence takes precedence over these defaults.

• Missing establishment or dispatch evidence is shown as a filing-grade automation blocker. You can save the incomplete source state, but affected imports remain in review until the missing evidence is supplied. Shopify asks you to save or discard any edits before leaving the form. Collapsing the step or refreshing App Home keeps the draft available; choose Discard to restore the last saved values.

• App Home groups repeated connection blockers and keeps health information separate from available actions, so the current issue and the next merchant step remain clear.

• The Protected-data policy setup item checks that VAT Engine's requested Shopify permissions and data fields stay within its supported minimal policy. Shopify's separate app-access review does not leave merchant store setup permanently blocked.

• The Import your first orders step becomes available after the preceding setup items are confirmed complete by VAT Engine. The same readiness is checked again when the import is requested and when the job is saved, so a simultaneous settings change or completed first import cannot create duplicate work. It imports Shopify's recent 60-day order window and shows progress from the saved import job. While it is running, Setup and Activity offer a status refresh instead of starting a duplicate import. After completion, later synchronization uses manual resync or reconciliation. Older orders require approved read_all_orders access and a separate historical backfill.

• A queued or running historical backfill can be cancelled without affecting ordinary order, webhook, or reconciliation jobs. In Activity, choose Cancel, review what will happen, and confirm Cancel import. The action is disabled while the request is in progress, and Shopify Admin confirms the result. Repeating the request is safe. If Shopify has already started the remote historical-data operation, VAT Engine also asks Shopify to cancel it and reports when that remote confirmation is unavailable.

• App Home Activity lists recent imports newest first in responsive pages. Filter the current page by active, completed, failed, or cancelled work, and review progress, affected records, update time, and a safe failure summary without leaving Shopify Admin.

• App Home Activity summarizes unresolved VAT review work for the connected store by source, customer type, destination, product mapping, imported goods, and marketplace liability, together with the oldest unresolved date. Select a category to open the authenticated VAT Engine review queue already filtered to that store. The summary contains counts only; order details, customer information, and stored classification evidence remain in the VAT Engine workspace.

• If a Settings form has unsaved changes, Shopify asks you to save or discard them before App Home moves to another section. After saving, later edits continue from the latest saved version even if the setup item is collapsed and reopened.

• App Home rejects malformed or oversized source-setting and order-preview requests before applying changes. Refresh the section and retry with the values shown in the form.

• Source tax settings can be shared by more than one connected integration. VAT Engine waits for imports on every connected integration using that source profile to finish before saving those settings, so one import cannot span two tax configurations.

• You can leave App Home open, refresh its current section, or reopen a section later without reusing the short-lived credential from the original launch. VAT Engine asks Shopify for current authorization whenever it loads store data or performs an action.

• App Home follows Shopify Admin's interface and accessibility conventions.

• The embedded view can run the primary merchant-safe actions directly from Shopify Admin: reconnect, disconnect, initial import, manual resync, reconciliation, and webhook-subscription repair.

• Each App Home action is authorized for the current Shopify store and VAT Engine account. Stored Shopify credentials are not exposed in the embedded page.

• If the same canonical Shopify shop domain is linked to more than one VAT Engine account on a deployment, the embedded view fails closed and asks support to resolve the ownership conflict instead of guessing which tenant should receive the embedded session.

Order Preview And Controlled Import

After the Shopify connection is in place, open the integration's Activity page in VAT Engine.

• Use Shopify order adapter preview to enter either a Shopify numeric order ID or a full Shopify order GID.
• VAT Engine fetches that order through Shopify Admin GraphQL and shows the normalized sale/refund events it would import.
• The same activity page now also surfaces Operator alerts and runbooks for the connected store. If VAT Engine detects stale sync freshness, failed cursors, repeated Shopify throttle pressure, elevated webhook delivery failures, or overdue privacy work, that panel highlights the issue and links back to the affected section before you start another replay or resync.
• Use Actions & progress for alerts, sync controls, health checks, privacy requests, previews, and import jobs. Use Technical details for receiver, throttle, retention, audit, webhook, and cursor diagnostics. A warning icon on either tab means that view contains an active issue. Alert links open the correct view automatically, and affected topic, delivery, failure, or runbook details open automatically. Healthy details and historical records stay collapsed until you choose to inspect them.
• Queued and running import jobs update automatically while you keep the activity page open. Live updates stop after the work finishes and pause when the browser tab is not active.
• Shopify jobs now continue normally after VAT Engine is updated. If a job remains queued for several minutes, refresh the activity view and contact support if the status does not change.
• Order previews now handle stores without candidate store, channel, or fulfillment labels without interrupting the activity page.
• If Shopify repeats the same delivery or an older webhook triggers another refetch after a newer Shopify order revision was already stored, VAT Engine now no-ops that stale replay instead of writing an older ledger snapshot over the newer committed state.
• The same preview now also shows Shopify's test-order flag and channel-policy result for each normalized event. If the resolved VAT Engine source profile is explicitly marked as a test channel, Shopify test orders are excluded automatically. If a Shopify order is a test order without that explicit source default, or if Shopify identifies a marketplace, subscription, POS, wholesale, or other non-owned-store channel without a matching source-profile channel default, VAT Engine keeps the normalized rows in review instead of filing them by default.
• The preview now also shows the country-evidence policy and customer-type resolution path for each normalized event. Physical goods and shipping-charge rows use shipping country first with billing fallback, while non-shipping supplies use billing country first with shipping fallback. If Shopify reports taxExempt=true without a purchasing-company identity, VAT Engine keeps that row in review instead of forcing B2B or B2C. The current minimum-access query does not return a purchasing-company identity, so a non-exempt order also needs an explicit merchant-confirmed customer-type value on that order before its B2C classification should be treated as filing-ready.
• The same preview now also distinguishes cash-settled refunds from credit-note-only corrections by using Shopify refund transaction outcomes, shows Shopify order adjustments as separate correction rows, and surfaces the original sale reference when Shopify provides a stable order-line link.
• Shipping-charge, refunded-shipping, and shipping-linked adjustment rows stay separate from goods rows. VAT Engine auto-classifies those rows only when Shopify's observed shipping VAT and the actual shipping VAT amount both match the destination country's standard VAT rate; zero-rate, reduced-rate, exempt, amount-mismatched, or otherwise non-standard shipping tax stays in review with an explicit shipping allocation diagnostic.
• The same preview now also shows marketplace or merchant liability for each normalized event when Shopify exposes a decisive signal. VAT Engine prefers Shopify tax-line liability, uses the mapped source-profile default only as a fallback policy, and keeps marketplace-channel orders in review when Shopify does not expose enough liability evidence to file confidently.
• The same preview now also shows imported-goods and IOSS diagnostics. When Shopify exposes non-EU dispatch evidence together with duties or import-fee signals, VAT Engine flags the affected normalized event as an imported-goods candidate, records the detected import origin, and keeps the row in review unless it can derive a filing-safe consignment intrinsic value. VAT Engine does not treat shipping, duties, or additional fees as part of the intrinsic goods value, and it no longer lets those imported-goods signals silently override an explicit non-goods Shopify product tax mapping such as service or tbe_service.
• VAT Engine now also uses Shopify's own special-product signals before it trusts a catalog rule too far. Gift-card products with no VAT are excluded automatically, while taxed gift cards, non-taxable rows without a matching exempt rule, and zero-VAT rows without the right zero-rate or exempt mapping stay in review with explicit product-mapping diagnostics.
• VAT Engine now also treats Shopify taxesIncluded as the amount-basis signal for each normalized event. When Shopify line prices already include VAT, VAT Engine backs VAT out before it evaluates the canonical taxable base. When Shopify keeps tax separate, VAT Engine uses the captured line amount as the taxable base and adds VAT on top for the gross amount.
• For zero-VAT Shopify rows, VAT Engine now separates tax treatment more explicitly. Order-level taxExempt=true pushes the row toward exempt, an explicit zero-rate Shopify tax line pushes it toward zero-rated, and contradictory or incomplete evidence stays in review instead of silently treating every zero-VAT row as the same case. Those Shopify signals are still subordinate to unresolved VAT Engine product-tax review: if a row still needs an explicit zero-rate, exempt, or other special-product mapping, the tax-treatment panel stays diagnostic only and the row remains in needs_review.
• Product-tax mappings limit excise, new-means-of-transport, and assembly or installation flags to goods and imported goods. Those flags cannot be combined with gift-card handling.
• When Shopify exposes fulfillment-order routing for a physical-goods line, VAT Engine now also shows the dispatch-country topology for that line. One Shopify line can split into multiple VAT Engine events by dispatch-country group if Shopify reports multi-origin fulfillment.
• Those split events now also keep fulfillment-location alias evidence scoped to their own dispatch segment, so a DE split row does not inherit NL warehouse aliases during source attribution.
• Shopify shipping sale rows and refund-shipping rows now reuse fulfillment-location alias evidence only when Shopify routing points to one unambiguous assigned location for the order. If the order is routed across multiple locations, VAT Engine leaves shipping-family source attribution fail-closed instead of guessing from the whole warehouse set.
• If Shopify later cancels an order that already had a committed sale imported, VAT Engine now shows any remaining cancellation residual explicitly instead of silently mutating the original sale row.
• If one of those later non-sale corrections belongs to a VAT return period that is already locked or filed, VAT Engine keeps the closed period immutable. When the correction can be linked back to an already imported original sale, VAT Engine stores it on the first later open correction date and retains the original Shopify effective date in canonical evidence. If the original sale cannot be linked, VAT Engine blocks the import and asks for operator review instead of inventing a closed-period rewrite.
• The same card can then run a controlled import for those normalized events.
• If Shopify reports that the fetched order snapshot is partial or truncated, VAT Engine still shows the preview for diagnosis but blocks the import until a complete order fetch is available. The preview helps you verify one order before importing it. It does not replace historical sync, reconciliation, or the final review of filing-ready classifications.

Order preview requests are limited to the connected Shopify store and accept only a Shopify numeric order ID or full Order GID. VAT Engine applies the same minimized preview contract wherever the preview is opened, including Shopify App Home. Embedded previews are matched to the current Shopify store, connection, and requested order before results are returned. They remain private and preview-only, without returning customer contact details, street-address fields, or an imported result. In Shopify App Home, open Order preview and submit the order ID to fetch it explicitly. The result shows normalized amounts, VAT treatment, classification, destination, warnings, and any condition that prevents a complete import. Previewing never imports or changes the order.

Automatic Source Attribution

VAT Engine applies the same source-attribution rules to order preview, import, and automatic sync.

• If the Shopify integration is already linked to a VAT Engine source profile, that mapping stays the first choice.
• If you maintain source aliases, VAT Engine can also match the verified Shopify store through its shop domain, Shopify shop ID, store/display label, supported Shopify channel labels, or fulfillment-location labels when Shopify exposes fulfillment-order routing for the order.
• Source profiles can now also carry a Shopify channel default such as owned store, marketplace, subscription, POS, wholesale, or test. The order preview shows that default next to the resolved source match and compares it with Shopify's observed order channel before import.
• The order preview now shows which source profile match VAT Engine would use before import, so an operator can correct aliases or the integration mapping before filing-relevant data lands.
• If Shopify omits or truncates that routing evidence, VAT Engine keeps the affected source or dispatch decision reviewable instead of guessing from a partial warehouse signal.

VAT Engine now also schedules periodic Shopify reconciliation in the background for eligible storefronts and still lets operators queue one manually from the same activity page when a faster recheck is needed.

For larger or older history, the same activity page now has a separate historical backfill control that uses Shopify Bulk Operations instead of deep normal pagination. That control is only available when the connected Shopify install has the approved read_all_orders scope, because Shopify limits older-order access otherwise.

The historical coverage state distinguishes the permission the app asks for from the permission Shopify has actually granted to the store:

• Recent-window only means the connection continues to use Shopify's normal recent 60-day order access and no historical permission is currently requested.
• Approval required means historical access is requested but is not yet granted to this installation. Requesting a permission is not treated as approval.
• Ready means read_all_orders is granted and the historical import can be queued.
• Queued or Running means historical work already exists; refresh its status instead of starting duplicate work.
• Completed confirms the latest historical import finished.
• Failed allows the historical import to be retried after reviewing the failure.

In Shopify App Home, open Activity and find Historical orders. The action shown there follows the current state: Import older orders appears only when access is ready, Check historical import status appears for queued or running work, and Retry historical import appears after a failed attempt. Recent-window, approval-required, and completed states do not show a start action. The import activity below the section shows the resulting job and its safe progress or failure summary.

VAT Engine also validates the signed bulk-result destination and size automatically, so malformed or unexpectedly large upstream result files fail closed instead of importing partial data silently. Historical backfill retains Shopify duties and additional-fee signals for the order and line items. VAT Engine records whether each signal set was actually returned. If a declared bulk snapshot omits a signal required for imported-goods treatment, the affected event stays in review instead of treating the missing value as zero.

Shopify Bulk Operations impose query-shape limits. App-owned product metafield matching is available for order preview, direct import, and recent-order sync, while historical backfill currently relies on product, variant, SKU, tag, and category signals.

Currency And Presentment

Shopify can store the same order amounts in two currency views: the store's shop currency and the customer's presentment currency. VAT Engine imports the shop-currency amounts as the canonical VAT ledger amounts because those are the stable values Shopify exposes for reconciliation across order, refund, shipping, duty, fee, and adjustment records.

If a customer paid in another presentment currency, VAT Engine keeps that presentment currency and amount evidence in the Shopify order preview so operators can explain the storefront/customer view. It does not replace the canonical shop-currency amount used for VAT classification. Normal filing currency conversion still happens later in VAT Engine's reporting layer.

The same activity page now also shows a Historical coverage status for the store. Use that area to confirm whether the store is still limited to Shopify's default recent 60-day order window, has requested historical access that still needs approval, has the granted read_all_orders scope and is ready to import, already has queued or running historical work, has completed a historical backfill, or can retry a failed attempt. That keeps the older-history boundary explicit without marking every normal read_orders-only install as generically unhealthy.

Historical bulk backfill also fails closed when Shopify's bulk snapshot is incomplete for filing-relevant correction data. If refund transactions or refund order adjustments were truncated in the bulk result, VAT Engine now blocks that order import instead of guessing whether the correction was a settled refund, a credit note, or an incomplete discrepancy adjustment.

The same activity page now also exposes a Shopify Admin API throttle panel. That panel shows the last observed GraphQL cost snapshot, current bucket availability, restore rate, recent wait time, and whether VAT Engine has delayed requests for that store recently. VAT Engine applies this pacing automatically; the panel helps explain why a synchronization may take longer than expected.

The activity page also shows a Shopify webhook subscriptions block. VAT Engine uses Shopify's shop-scoped Admin API webhook subscriptions for operational order/refund/uninstall topics, verifies that they still point at the current receiver URL, requests only the stable identifier fields VAT Engine needs for supported operational topics, and offers a repair action if Shopify lost authorization or still has a stale receiver URL from an older setup. If Shopify rejects a repair or reconnect attempt, the activity page now shows Shopify's returned reason directly instead of a generic webhook-registration failure. If Shopify says it cannot create the specified topic, review the app's API access requests in Partner Dashboard before retrying.

Current Install Flow And Distribution Boundary

VAT Engine already supports a guided Shopify install flow on supported deployments:

1. For a Shopify-distributed install, open VAT Engine from Shopify Admin. Shopify starts the authorization flow from that Shopify-owned surface, then VAT Engine asks you to sign in or create the account that will own the store connection. In a public App Store deployment, this is the only install and reconnect entry point: VAT Engine does not ask for a shop domain in its dashboard.
2. For a controlled custom-app dashboard connection, start from Dashboard -> Integrations, choose the source profile, and use the permanent .myshopify.com domain supplied by Shopify.
3. Review and approve the requested Shopify scopes.
4. Sign in or create a VAT Engine account if needed, then explicitly confirm that the Shopify store should be linked to that account.

After install, merchants can also open VAT Engine from Shopify Admin App Home to review connection health, sync controls, and webhook status for that same store.

How merchants reach that install flow is a separate Shopify distribution question:

• Some VAT Engine deployments can support Shopify public distribution, which is the path tied to App Store review and listing.
• Other deployments can use Shopify custom distribution or another controlled install path.
• VAT Engine's dashboard and App Home behavior do not, by themselves, guarantee that the app is publicly listed in the Shopify App Store.

If you manage multiple client accounts, do not connect a client store while signed in to your own personal or another customer's VAT Engine account. The integration should be created inside the account that owns that store's reporting data.

Field Mapping For Controlled Dashboard Connections

These fields apply only to a controlled custom-app deployment. Public App Store connections inherit their verified Shopify identity, permissions, and tokens from Shopify Admin; the dashboard lets the account owner maintain reporting metadata or disconnect the connection. Disconnecting revokes VAT Engine's stored Shopify credentials and stops connector work, but keeps retained imports, review history, and privacy records attributable to the original store. A disconnected public connection can be opened directly in Shopify Admin from the VAT Engine connection dialog to authorize it again.

How To Get The Right Shopify Values

Store Domain

Use the store's permanent Shopify domain:

• your-store.myshopify.com

Do not use:

• a storefront custom domain
• a staff login email
• a contact email
• an /admin URL

Granted Permissions

VAT Engine obtains the authorization it needs through Shopify's approval flow. You do not need to copy or paste a Shopify access token.

For a controlled dashboard connection:

• start the connection from Dashboard -> Integrations
• approve the requested scopes in Shopify
• return to VAT Engine after Shopify confirms the granted permissions

Do not paste storefront passwords, user passwords, API credentials, or webhook topics into Shopify connection fields. Reconnect from Shopify Admin, or use Reconnect Shopify when that action is available for your controlled dashboard connection.

External Shop ID

VAT Engine records the verified Shopify shop ID automatically from the connected install. If you reconnect an older manual Shopify integration and VAT Engine rejects the submitted shop identity, use the shop.id and shop.myshopifyDomain returned by Shopify as the source of truth.

Webhook Expectations

After connecting Shopify, open the integration activity page to review webhook health. VAT Engine manages the required webhook connection automatically; merchants do not need to configure webhook URLs manually.

• VAT Engine manages the operational Shopify webhook connection automatically after installation or reconnect. Use the activity page to confirm that required topics are registered and repair them when the page reports drift.
• Order and refund notifications trigger a fresh Shopify order check before VAT Engine applies a filing-relevant change.
• Supported order, refund, permission-change, and uninstall notifications are processed automatically.
• VAT Engine also runs a periodic reconciliation pass against recently updated Shopify orders so a delayed or missed webhook does not have to be the only path that refreshes VAT Engine data.
• Mandatory Shopify privacy topics such as customers/data_request, customers/redact, and shop/redact are handled automatically. Their status is available from the integration activity page. customers/redact requests complete automatically when no exact retained imported evidence matches the provided Shopify order IDs and switch to legal-retention state when retained filing evidence still exists. customers/data_request requests auto-complete only when no exact retained filing evidence matches the provided Shopify order IDs. When retained filing evidence does match, VAT Engine prepares a minimized VAT-evidence export for the account owner to download and deliver to the store owner. The export excludes customer contact data and connection credentials. shop/redact removes Shopify connection data while keeping VAT evidence only where legal retention applies. Requests that cannot be resolved safely remain available for review.

If Shopify sends app/uninstalled, VAT Engine now disconnects that storefront automatically, revokes the stored Shopify access credentials, cancels queued or running sync work for that storefront, and leaves any already received webhook records in the audit trail instead of deleting them. Reconnecting the same shop through VAT Engine's Shopify authorization flow requires confirmation from the VAT Engine account that owns the previous connection, then clears that disconnected state and lets VAT Engine register the operational webhook set again for the restored install.

If Shopify sends app/scopes_update, VAT Engine verifies the store's current granted permissions. When one or all required permissions are missing, the connection becomes Action required. VAT Engine finishes the active connection check safely and pauses affected sync work until the merchant restores the requested permissions and reconnects through Shopify Admin. An empty permission grant is treated as a complete revocation rather than as temporary missing information. Editing the integration name or source settings does not dismiss an existing permission or webhook warning. Complete the action shown for that warning; VAT Engine clears it only after the matching repair succeeds.

If VAT Engine is opened in more than one Shopify Admin tab during installation, an older tab may ask you to try again. Reopen or refresh App Home and complete the newest flow.

For an already connected store, VAT Engine safely saves renewed Shopify authorization before leaving App Home. Routine VAT Engine deployments do not require you to reconnect the store.

Source-profile choices are shown only for the currently verified Shopify connection. If the store is disconnected, replaced, or linked again under another account, refresh App Home and reconnect when prompted before choosing a VAT source. VAT Engine does not show profile names from the prior account while that connection change is being completed.

App Home Activity And Order Preview

Shopify App Home includes a private Activity view for the connected store. Import jobs load in bounded newest-first pages, and page refreshes or retries keep the current position without mixing results from another store. Queued or running historical imports can be cancelled individually. If Shopify cannot immediately confirm its corresponding remote cancellation, VAT Engine keeps the warning visible and provides a retry action after the Activity view is reloaded. If an earlier retry was interrupted, the action becomes available again after its short processing window. A confirmed cancellation is not reopened by a later temporary error, and cancellation state from an older historical import attempt does not hide a newer one. Activity reports whether the local historical import was cancelled, a Shopify cancellation retry started, Shopify confirmed the cancellation, or the retry still needs attention. The status shown after an action reflects the latest saved cancellation result immediately. When a failed historical import needs another Shopify cancellation attempt, the warning describes that retry without implying that the failed local import was newly cancelled.

The Order preview screen is read-only. Enter a numeric Shopify order ID or full Shopify Order GID to see the normalized VAT treatment, amounts, classification, warnings, and import blockers before importing. Editing the order ID or changing stores clears the previous result. Preview responses do not include customer contact details, street addresses, or stored classification evidence. Changing the connected store also clears any prior loading or error state before the new store is shown.

Unresolved VAT review cards show counts for the connected store only. Opening a card takes you to the signed-in VAT Engine review queue only after the store filter has been verified against your account. The first review request is already limited to that verified store.

Common Mistakes

• Connecting the store while signed in to the wrong VAT Engine customer account
• Using a custom storefront domain instead of your-store.myshopify.com
• Pasting a staff email or store contact email into the shop-domain fields
• Trying to paste legacy manual credentials into a new Shopify OAuth connection

Related Docs

• Integrations Overview
• Sources
• Authentication