FTP Integration

The FTP integration lets your team move data between WizCommerce and your own system using files dropped onto a secure FTP server, instead of a direct API connection. You upload entity files (products, inventory, customers, addresses, contacts, categories, collections, orders) from your system to WizCommerce, and WizCommerce pushes orders and customers back to your FTP server using UUIDs as reference IDs.

This article walks through how the connection is set up, what data flows in both directions, the file naming and validation rules, and what to do when something doesn't import the way you expected.

Table of Contents

Before You Begin

1. Confirm with WizCommerce team that FTP integration is enabled for your account. WizCommerce team will provide the FTP credentials.
2. During the design and scoping discussion, it will be decided which entities will be imported via FTP (Products, Inventory, Customers, Addresses, Contacts, Categories, Collections, Orders) and which entities will be exported from WizCommerce to the FTP server (Orders, Customers).
3. Set up your side to generate files in the WizCommerce templates, and to consume the exported files using UUIDs as reference IDs.

A. How FTP Connection Works

When you onboard, WizCommerce provides secure FTP credentials:

• Host - the FTP server URL
• Port - typically 21 (or as specified by your CSM)
• Username and Password

The end-to-end flow works like this:

1. File upload. Your system generates and uploads entity files to the WizCommerce FTP server. Each file follows the naming convention ENTITY_NAME_DD_MM_YYYY (for example, PRODUCT_18_09_2024.csv). Each entity has its own folder on the FTP server.
2. FTP scheduler. WizCommerce periodically checks the FTP server for new files. When a file is detected, the import is triggered and the file is moved to a processed files folder. Different entities can be on different schedules. For example, product imports could run every 24 hours while inventory runs every 30 minutes.
3. Import queue. Once picked up, the data enters the WizCommerce import queue. The system validates content and format, checks for errors or inconsistencies, and processes the file.
4. Email notification. When the import completes, whether successfully or with errors, WizCommerce sends an email with the import status, so you can address any failures quickly.

For exports, the flow is simpler: when an order or customer is created in WizCommerce, the export is initiated almost instantly. WizCommerce writes the CSV(s) into a UUID-based subfolder on your FTP server. Your system polls the FTP server or uses an event-driven mechanism to pick up the new files.

B. What Data You Can Import via FTP

FTP import supports multiple data types. Below is a quick overview of what you can import, the key fields involved, and important notes for each.

» Best practices for the initial import

1. Skip System IDs on first import. System IDs are generated by WizCommerce. Upload the file without them on the first run.
2. Export after the first import. Pull the exported file from WizCommerce to get the System IDs and store them in your system for future updates.
3. Use the official templates for each entity. WizCommerce team will share the template URLs (Products, Inventory, Categories, Collections, Customers, Customer Addresses, Customer Contacts, Orders).
4. Automate uploads. Set up automated FTP uploads at the right interval for each entity. Inventory updates often need a much faster cadence than product or category updates.

C. What Data WizCommerce Exports to Your FTP

When an order or customer is created in WizCommerce, the data is exported to your FTP server in near real time. Exports use UUIDs as the reference ID; universally unique identifiers that prevent collisions across systems.

The folder structure looks like this:

WizCommerce Export/
├── Orders/
│   ├── order_<UUID>/
│   │   ├── order_data_<UUID>.csv
│   │   └── order_items_<UUID>.csv
│
├── Customers/
│   ├── customer_<UUID>/
│       └── customer_data_<UUID>.csv

• Each order gets its own subfolder named after the order UUID, containing order_data and order_items CSVs.
• Each new customer gets its own subfolder named after the customer UUID, containing the customer data CSV.

Your system can poll the FTP server on a schedule, or use event-driven mechanisms to pick up new files as soon as they're written.

D. Sync Timing

• Imports are picked up by the WizCommerce FTP scheduler. Each entity can be on its own schedule (for example, products every 24 hours, inventory every 30 minutes). WizCommerce team will help you decide the right cadence for each entity.
• Exports are near real-time. The moment an order or customer is created in WizCommerce, the export file is written to your FTP server.

E. Troubleshooting and Common Issues

» My import file wasn't picked up

• Confirm the file is in the correct entity folder on the FTP server.
• Confirm the filename follows the ENTITY_NAME_DD_MM_YYYY convention.
• Check the processed files folder — if the file is already there, the scheduler picked it up and the import has already run (look for the email notification with the result).

» My product import is failing on duplicates

Uniqueness is enforced by both SKU_ID and Reference ID. If a product exists with the same SKU_ID but a different Reference ID (or vice versa), the import flags it as a conflict and requires manual resolution. Open the import error report, identify the conflicting rows, and either correct the SKU/Reference pairing or include the System_ID so WizCommerce knows it's an update.

» Inventory updates are being silently dropped

The most common cause is an unknown SKU. The inventory import expects each SKU_ID to already exist in the product catalog. Rows with invalid SKU_IDs are logged as errors and skipped, while valid rows continue processing. Import the missing products first, then re-run the inventory import.

» A customer was created as a duplicate

The customer match priority is: System ID → Reference ID → Company Name. If you didn't include System ID or Reference ID and another customer with the same Company Name already existed, the import may have created a duplicate. Run an export to find both records, decide which to keep, and clean up. For future imports, always include System ID or Reference ID for known customers.

» A category didn't import the way I expected

Categories are hierarchical, using > to define parent-child relationships (for example, Electronics > Mobile Phones > Accessories). Make sure your hierarchy is consistent across rows, and that no parent in the chain is missing.

» An order didn't push (export) to my FTP

Order exports are near real-time, so a missing export is unusual. Check the WizCommerce end first and confirm the the order is in Confirmed status. If the order is confirmed but not on the FTP server after a few minutes, contact help@wizcommerce.com with the order ID.

» I am seeing import failures in the email notification

Open the error report attached to (or linked from) the email. Most errors fall into:

• Duplicate keys - same SKU_ID/Reference ID/Customer ID used in conflicting ways.
• Unknown references - for example, inventory rows pointing to SKUs that don't exist, or address rows pointing to customers that don't exist.
• Format errors - column ordering or data type that doesn't match the template.

Fix the rows flagged in the report and re-upload only the corrected rows, or the full file again — the scheduler will pick it up on the next pass.

FAQs

1. Do I need to include System IDs on every import?

A. Not on the first import, WizCommerce generates them. After the first import, export the data, store the System IDs in your system, and include them on future updates to avoid duplicates.

2. What's the difference between System ID and Reference ID?

A. System ID is the UUID WizCommerce assigns to a record internally. Reference ID is your system's identifier, used to map between the two systems. Both can be used to identify records, with System ID taking priority when both are present.

3. How fast are exports?

A. Near real-time. The moment an order or customer is created in WizCommerce, the export is written to your FTP server.

4. What happens if my FTP server is briefly unreachable?

A. Exports retry, and imports won't break but if your FTP server is down for an extended period, contact help@wizcommerce.com so support can review the queue.

5. Can different entities run on different schedules?

A. Yes. Each entity can be configured with its own schedule. Inventory often runs every 30 minutes, while products and categories can run every 24 hours.