SyncA2Z Documentation

Welcome to the SyncA2Z help centre. SyncA2Z is a Shopify embedded app for bulk importing, exporting, and syncing store data. This documentation covers everything from installation to advanced field transforms.

If you're looking for quick answers, the FAQ page may be faster. For anything else, email support@synca2z.com.

Installation

1. 1
   Find SyncA2Z on the Shopify App Store and click Add app.
2. 2
   Review the permission request and click Install. SyncA2Z requests read/write access to products, inventory, orders, and collections.
3. 3
   You'll be redirected into your Shopify admin with SyncA2Z open. Click New Integration to create your first sync job.

Key Concepts

There are three fundamental concepts in SyncA2Z:

Import Overview

An import integration reads a file from a source, parses it, optionally filters and transforms rows, then pushes the data into Shopify using bulk mutations. The pipeline is:

Source (FTP/SFTP/URL/Upload) → Parse → Filter rows → Map fields → Push to Shopify → Report

Source Types

File Formats

SyncA2Z supports CSV, Excel (XLSX), JSON, and XML for both import and export. The format is auto-detected from the file extension. CSV files support comma, semicolon, and tab delimiters automatically.

Field Mapping

Field mapping connects your source file's columns to Shopify fields. The mapper shows your source column headers on the left and a dropdown of available Shopify fields on the right.

Key fields

For UPSERT imports, you must mark at least one field as a Key Field by checking the checkbox. The key field is used to look up existing records. For products, the lookup priority is SKU → barcode. For multi-variant products, it's always the handle.

Multi-target mapping

One source column can map to multiple Shopify fields. Click Add target on any mapping row to add a second destination. Each target can have its own transform. Example: map "Product Name" to both title and handle (with a slugify transform on the handle).

Importing Products

Single-variant products

Each row in your file becomes one product with one variant. Map standard fields like title, vendor, variants.sku, variants.price, variants.inventoryQuantity, and so on.

Multi-variant products

To import multi-variant products, your file needs one row per variant. Add a column that groups rows belonging to the same product (e.g. a shared handle). Map that column to the special key variants.groupBy. SyncA2Z will group rows automatically and create one product per group.

Option names are read from column headers following this pattern:

variants.option1.Size
variants.option2.Color
variants.option3.Material

INSERT vs UPSERT

Metafields

Add metafield columns to your file using this header format:

metafields.custom.launch_date:date
metafields.custom.material:single_line_text_field

Metafields are set after the product is created/updated. Errors during metafield writes are non-fatal — the product row is still counted as successful.

Importing Inventory

Inventory import updates available quantities by SKU. Required columns: sku and inventoryQuantity. Optionally include locationName to target a specific location.

The app uses optimistic locking — it reads the current quantity before adjusting, so concurrent updates don't conflict.

Importing Collections

Collections import supports both create and update (UPSERT by handle, then by title). Supported fields: title, handle, descriptionHtml, sortOrder, tag.

Export Overview

An export integration queries your Shopify store using the Bulk Operations API, extracts the rows you need, applies optional filters, and writes the output to a file. The pipeline is:

Build query → Bulk query Shopify → Download JSONL → Filter rows → Extract fields → Write file → Upload (optional)

Field Picker

The field picker shows all available Shopify fields grouped by category. Check the fields you want and optionally rename the column header. The query is built automatically from your selection — you don't write any GraphQL.

Supported export data types: Orders (with line items and fulfillments), Products (with variants), Collections.

Export Filters

Filters are applied to the raw Shopify records before the file is written. Field names in export filters use Shopify GraphQL names (e.g. title, vendor, displayFinancialStatus). 10 operators are available: equals, not equals, contains, not contains, starts with, ends with, greater than, less than, is empty, is not empty.

Transform Sandbox

Every field mapping can include an optional JavaScript transform that runs on the field value before it's sent to Shopify. The sandbox exposes two variables:

Common examples

// Add 25% markup to cost price
VALUE = (parseFloat(VALUE) * 1.25).toFixed(2)

// Combine Brand + Model columns into title
VALUE = ROW["Brand"] + " " + ROW["Model"]

// Build a URL slug from a title
VALUE = VALUE.toLowerCase().replace(/\s+/g, '-').replace(/[^a-z0-9-]/g, '')

// Conditional: different markup by category
const cost = parseFloat(ROW["Cost"]);
VALUE = (cost * (ROW["Category"] === "Electronics" ? 1.15 : 1.20)).toFixed(2)

// Clean a SKU
VALUE = VALUE.trim().toUpperCase()

Safe globals available in transforms: parseFloat, parseInt, Number, Boolean, String, Math, Date, JSON, Array, Object, RegExp.

AI Mapping Assistant

The AI Assistant lets you set up field mappings, transforms, and filters by describing your goal in plain English, without clicking through dropdowns.

How to use it

1. 1
   Upload your source file so the AI can read your column headers.
2. 2
   Open the AI Assistant panel and type what you want — for example: "Map Item Code to SKU, set selling price as Trade Cost plus 20%, skip rows with zero stock."
3. 3
   The AI generates the full mapping table, writes any required transform code, and sets up filters.
4. 4
   Review everything in the mapper. Edit any row manually if needed, then save.

Scheduling

Integrations can run manually (Run Now) or on a cron schedule. The scheduler runs server-side every 15 minutes and fires any integrations that are due.

Setting a schedule

In the wizard's Schedule step, pick a frequency (every N hours, daily, weekly) or enter a custom cron expression. The next run time is shown on the integration detail page.

Erase Data

Erase Data integrations permanently delete Shopify records (products or collections) that match a set of filters. This is irreversible.

Safety controls

• Erase integrations can never be scheduled — they are always manual.
• Every run requires confirmation in a modal before it starts.
• A per-row erase report is available after the job so you can see exactly what was deleted.

Config Export & Import

You can export any integration's configuration as a JSON file and import it on another store. This is useful for replicating the same setup across multiple stores without rebuilding the wizard from scratch.

Exporting a config

Open the integration detail page and click Export Config. A JSON file is downloaded to your machine. Passwords and encrypted credentials are automatically stripped from the export.

Importing a config

From the integrations list, click Import Config and upload a previously exported JSON file. You'll see a preview of the integration (type, mode, field count, filter count) and can rename it before creating it. Imported integrations are always created as inactive so you can review and configure credentials before activating.

Supplier API Connections Business Plan

When your supplier provides an API rather than a file feed, SyncA2Z's Business Plan lets you connect directly to it. A dedicated integration engineer builds and maintains the connector — you don't write any code.

RESTful APIs

REST connectors support any HTTP-based API returning JSON or XML. The engineer configures:

• Base URL and endpoint paths (including paginated endpoints)
• Request method, headers, and query parameters
• Response parsing — field extraction from nested JSON or XML structures
• Pagination strategy (page-based, cursor-based, Link header)
• Rate limit handling and automatic retry with backoff

SOAP / XML APIs

SOAP connectors work with legacy XML web services that expose a WSDL definition. The engineer handles:

• WSDL parsing and operation selection
• SOAP envelope construction (SOAP 1.1 and 1.2)
• Complex XML namespace handling and XPath-based field extraction
• Fault response detection and error propagation

Authentication Methods

All common authentication patterns are supported. Credentials are encrypted at rest and never stored in plain text.

Dedicated Integration Engineer

Every Business Plan API connection is built and supported by a named integration engineer assigned to your account. The engagement follows this process:

1. 1
   Discovery call — the engineer reviews your supplier's API docs and maps their data model to your Shopify fields.
2. 2
   Connector build — the engineer builds the custom connector in a staging environment and handles all authentication configuration.
3. 3
   Testing — end-to-end test runs are performed in your store with sample data before go-live.
4. 4
   Go-live — schedule is set up and the first live sync is confirmed with you before handing over.
5. 5
   Ongoing support — the engineer remains your point of contact for API changes, field mapping updates, and any issues.

Predefined Connectors

Connectors are ready-made integrations for named third-party systems. Instead of building an integration with the wizard, you just enter your credentials and the connector handles everything else — source, field mapping, schedule, and data type.

Find connectors in the Connector Catalog tab on the integrations list page.

Tradebox

Category: OMS (Order Management System). Source: FTP. Capabilities: import inventory, import prices, export orders. Default schedule: every 6 hours.

Required credentials: FTP host, FTP username, FTP password, file path.

Linnworks

Category: OMS. Source: API. Capabilities: import inventory, import tracking numbers. Default schedule: every 4 hours.

Required credentials: Linnworks Application ID, Application Secret, API token.

Generic FTP / SFTP Supplier

Category: Supplier feed. Source: FTP or SFTP. Capabilities: import inventory, import prices, import products, import tracking. Default schedule: every 12 hours.

Use this connector for any supplier that provides a feed file over FTP/SFTP when there's no dedicated connector for their system.