AutoSync Documentation

AutoSync is a Shopify-embedded app for automotive parts merchants. It reads your product catalog, identifies which vehicles each part fits using AI, and pushes that fitment data back to Shopify as native tags, metafields, and smart collections.

Once your catalog is mapped, eight Theme App Extension widgets let shoppers find the right parts by Year/Make/Model/Engine, by registration plate (UK), by VIN, or by wheel specs.

• Not a black box. AutoSync uses AI to map each part to the vehicles it fits, but you review and approve every mapping, and nothing publishes to your store until you push it.
• Not destructive. AutoSync only writes to its own _autosync_* tags and its own $app:vehicle_fitment metafield namespace. Your existing tags, descriptions, prices, and inventory are never touched.
• Not a re-platform. The app sits inside your Shopify admin. The storefront widgets sit inside your existing theme. You keep everything you already have.

1. 1
   Install from the App Store

   Open the Shopify App Store, search for AutoSync, click Install, and approve the requested permissions. The app requests 12 OAuth scopes - all are required for the features described in this documentation.
2. 2
   First-time onboarding

   When the app loads for the first time, you'll see the dashboard with an onboarding checklist. The checklist walks you through fetching your products, mapping fitment, and pushing data to Shopify.
3. 3
   Choose a plan

   The Free plan is active by default. Upgrade from the Plans page when you need more products, fitments, providers, or features like Auto-Extraction or storefront widgets.

1. 1
   Fetch your Shopify products

   From the Products page, click Fetch Products. AutoSync pulls all variants, tags, descriptions, and images from your Shopify Admin API and stores them locally for fitment mapping.
2. 2
   Map fitment

   On Growth and above, Auto-Extraction runs automatically and maps high-confidence products. On any plan, the Manual Mapping queue lets you assign vehicles by hand using a cascading Year/Make/Model/Engine selector.
3. 3
   Push to Shopify

   Once products are mapped, the Push page writes _autosync_* tags, $app:vehicle_fitment metafields, and smart collections back to Shopify. This is the step that makes your data visible on the storefront.
4. 4
   Add storefront widgets

   Open your theme editor and add one of the eight AutoSync blocks (YMME Search, Fitment Badge, Compatibility Table, and so on). Each block is fully customizable and the customer's selected vehicle persists across all of them.

A fitment is a single compatibility row linking one product to one vehicle. A product with 5 fitments is compatible with 5 different vehicles. A vehicle with 200 fitments has 200 compatible products in your catalog.

A vehicle is a specific combination of Make, Model, Year, and Engine. "BMW 3 Series 2018-2024 B58 3.0L" is one vehicle. The same model fitted with the B48 2.0L engine is a different vehicle.

Every product carries one status. The status determines whether tags get pushed, whether the product appears in the Manual queue, and how it counts toward plan limits.

AutoSync ships with a curated YMME database covering hundreds of makes, thousands of models, and tens of thousands of engine variants. This is the canonical reference - your fitments are validated against it and your storefront dropdowns are populated from it.

The database is shared across all merchants. Your private fitment data (which product fits which vehicle) is scoped to your shop only.

Shopify limits tags to 250 per product and list metafields to 128 items. AutoSync routes data to the right layer automatically:

Stale fitment data is one of the biggest pain points in this category. AutoSync solves it with three overlapping mechanisms so you never need to manually clean anything.

1. 1
   Instant cleanup inside AutoSync

   Deleting from any AutoSync page immediately recounts totals, removes empty makes from YMME dropdowns, marks orphaned vehicle pages, and schedules a background job to strip stale tags and metafields from Shopify.
2. 2
   Webhook detection from Shopify

   If you delete on Shopify directly, AutoSync receives a webhook within seconds. The product is removed from the database and a cleanup job is created. Rapid deletions are batched into a single Bulk Operations API call for efficiency.
3. 3
   Continuous safety net

   Every 2 minutes, a background scheduler scans for drift, miscounted totals, stale makes, and orphaned vehicle pages. Anything out of sync is corrected automatically. Jobs themselves fire instantly via database triggers - the scan is a safety net for webhook failures.

• Product and fitment counts on the dashboard
• YMME dropdowns - makes with zero products are removed automatically
• Shopify tags - _autosync_* prefixed tags are removed from affected products
• Shopify metafields - vehicle fitment data is removed when a product no longer has fitments
• Smart collections - empty collections for makes/models with zero products are cleaned up
• Vehicle specification pages - pages for engines with zero products are marked for removal
• Wheel fitments - removed automatically when wheel products are deleted

Fetching is how AutoSync learns about your catalog. The fetch process pulls titles, descriptions, variants, tags, and images from your Shopify Admin API and stores them locally so fitment mapping works without round-tripping the API on every operation.

You can re-fetch at any time to pick up new products or changes. Existing fitment mappings are preserved on re-fetch. AutoSync also watches Shopify webhooks for product create/update/delete events, so most catalog changes are picked up automatically without an explicit re-fetch.

The number of products you can fetch is capped by your plan. The fetch will load up to the cap and stop. The dashboard shows your current usage against the cap so you can see when an upgrade is needed.

Providers are external data sources that supply product or fitment information. AutoSync supports four source types with a unified import pipeline.

After uploading or fetching a sample, AutoSync shows the first 50 rows and a smart column mapping. The mapper remembers your choices for the next import from the same provider, so recurring feeds become one-click.

Paid plans include scheduled imports. Growth, Professional and Business get a weekly auto-fetch; Enterprise runs daily. The Custom plan can ratchet the cadence up to every 6 hours.

Auto-Extraction uses AI to read every product's title and description and identify the make, model, year range, generation, and engine it fits, checked against the YMME database of makes, models, and engines. Auto mapping is AI-generated, so always review it before relying on it.

Every extraction gets a confidence score. High-confidence matches are auto-approved into auto_mapped status. Medium-confidence matches flow into Smart Suggestions for one-click confirmation. Anything low-confidence or contradictory is flagged for the Manual queue.

Auto-Extraction is available on the Growth plan and above. Free and Starter plans use manual fitment mapping only.

When Auto-Extraction is reasonably sure but not certain, the candidate fitments are queued in Smart Suggestions. You see the product, the suggested vehicles, and the reason for each match. Click Confirm to promote them to smart_mapped, or Skip to bounce the product into Manual.

Smart Suggestions is the source of truth: whatever it returns is what gets persisted. There are no bypass paths or shadow matchers writing different data behind your back.

Products without auto-mapped fitments appear in the Manual Mapping queue. For each product, a cascading selector lets you choose Year → Make → Model → Engine from the global YMME database. You can attach multiple vehicles to a single product.

Auto-extractions with lower confidence also appear in the queue for manual review. You can approve a row to promote it from flagged to smart_mapped, modify a vehicle to fix the matcher, or reject the suggestion entirely.

Mapping a fitment inside AutoSync does not make it visible on your storefront. Push is the explicit step that propagates your mapping to Shopify so customers and Shopify's smart collections can use it.

Vehicle make and model names are written as app-prefixed tags - _autosync_BMW, _autosync_3 Series, and so on. These power smart collections that automatically group products by vehicle. Tags are capped by Shopify at 250 per product; AutoSync routes overflow data to metafields automatically.

Structured fitment data (make, model, generation, year range) is stored in app-owned metafields under the $app:vehicle_fitment namespace. App-owned metafields are protected by Shopify, so they cannot be accidentally edited by other apps or theme code.

AutoSync can create and manage smart collections that automatically include products matching specific makes, models, years, wheel PCDs, or wheel diameters. Granularity depends on your plan.

The push pipeline runs five concurrent worker IIFEs against the Shopify Admin GraphQL API, each pulling work from a shared queue. Compared to the previous sequential implementation we measured a 25x speedup: a 2,559-product push went from 1,667 seconds to 66 seconds on the autosync-9 demo store.

Concurrency is set to 5 to stay safely inside Shopify's Standard plan budget (1000 cost/sec restore rate, 20K bucket). The fetch helper handles 429 + Retry-After backoff automatically so per-call rate limiting is invisible to the rest of the code.

Bulk cleanup operations use Shopify's Bulk Operations API: instead of updating products one-by-one, AutoSync scans your catalog, builds a single batch file, and uploads it to Shopify for server-side processing. 10,000-product cleanups complete in minutes.

Smart collections turn your tagged products into native Shopify collection pages keyed by vehicle. The Collections page lets you pick a strategy that controls granularity and volume:

If Include SEO is enabled, each collection gets a generated meta title, meta description, H1, structured H2/H3 body content, and JSON-LD schema markup tuned for vehicle-search keywords. All SEO content is produced by a single deterministic pipeline so it cannot drift between routes.

Vehicle pages are Shopify metaobject-backed pages that render a rich specification view for any vehicle - engine specs, dimensions, performance, fuel economy - plus a list of compatible products from your catalog. They give long-tail traffic a destination to land on and click through.

Vehicle pages are available on the Professional plan and above and require the Vehicle Spec Detail storefront widget to render. Empty vehicle pages (engines with zero products) are automatically removed by the cleanup pipeline.

AutoSync ships a Theme App Extension with eight storefront blocks. Every block is fully customizable from the theme editor and every block shares the same vehicle context - the customer's selected vehicle persists across all blocks via localStorage.

Widgets call back to the app through an App Proxy route, signed with your store's Shopify API secret. There is no separate API key for you to manage and no third-party CDN.

1. 1
   Open your theme editor

   From Shopify admin go to Online Store > Themes > Customize on your live theme (or a draft theme if you want to preview first).
2. 2
   Add a section or block

   Click Add section or Add block on the page where the widget should appear. Scroll to the Apps category and pick the AutoSync block you want.
3. 3
   Customize

   Every block exposes 15+ settings - colors, border radius, button labels, font sizes, layout direction. The block previews live as you edit.
4. 4
   Save and publish

   Save the theme to push the change live. Customers immediately see the widget on the storefront and their selected vehicle persists across pages and sessions.

AutoSync uses Shopify's managed billing API. Every charge is approved by you inside the Shopify admin and appears on your normal Shopify invoice. There is no separate credit card or third-party billing portal.

From the Plans page, click any tier to start the Shopify approval flow. After approving the charge, your new plan takes effect immediately and your usage caps lift on the next dashboard refresh.

Downgrading is also done from the Plans page. If your current usage exceeds the destination plan's caps, the app will keep working but new operations that would push you further over the cap are blocked until you delete enough data to fit.

The Free plan is permanent. It lets you map up to 25 products and 100 fitments using Manual Mapping, then push them to Shopify. Auto-Extraction, Smart Suggestions, providers, and storefront widgets are gated to paid plans.

The Free plan is intended as a way to validate that your catalog parses cleanly before committing to a paid tier, not as a free-forever solution for a large catalog.

AutoSync's AI needs at least one anchor in the title or description: a make name, a chassis code, a generation code, or a specific engine code. Without any anchor, the title cannot be tied to a specific vehicle and the product stays in unmapped or moves to no_match.

• The title only contains the part name ("Brake Pads", "Oil Filter") with no vehicle reference - this is correct behavior, that product is universal-fit.
• The make is a custom name your supplier uses internally ("BMW M Performance Division" instead of "BMW") - add the alias to your provider's column mapping.
• The model name collides with a non-automotive word ("Focus" the part, not the Ford Focus) - the matcher will flag rather than guess; review in Manual.
• The chassis code is for a generation we don't have curated yet - tell us via support@autosync.app and we'll add it.

Mapping a fitment in AutoSync does not push it to Shopify. The Push page is the explicit propagation step. Check the Push page for the count of "unpushed" products and run a push.

If you have pushed and the tags still don't appear, check that Push Tags is enabled in the Push settings - it's owned by the Push page (not the global Settings page) and can be disabled if you prefer metafields-only.

Installing the app does not modify your storefront. You have to open the theme editor and add the relevant AutoSync block to the page where you want it. Until a block is added, no widget renders.

If the block is added but still blank, the most common cause is that the customer hasn't selected a vehicle yet - widgets like Fitment Badge and Compatibility Table are vehicle-conditional. Add YMME Search alongside them.