Spartwoo, the bridge between WooCommerce and the Spartoo marketplace.
Complete installation, configuration and usage documentation. From your first catalog synchronization to the daily management of orders and returns.
What is Spartwoo
Spartwoo is a WordPress plugin that connects your WooCommerce store to the European Spartoo marketplace, specialized in footwear and leather goods. It automates the synchronization of your catalog, stock, prices and orders — with no manual entry in two systems.
What Spartwoo does
- Automatic catalog export: generation of the XML feed expected by Spartoo, with photos, descriptions, variations, EAN, prices and stock.
- Stock synchronization: regular update of quantities on the Spartoo side (every 30 minutes by default).
- Order import: retrieval of Spartoo orders into WooCommerce, with automatic creation of the customer and order lines.
- Cancellation handling: automatic transition to cancelled status and creation of a WooCommerce accounting refund.
- Alert system : détection proactive des fiches produits non conformes avant rejet par Spartoo.
- Flexible mapping: fine-grained correspondence between your WooCommerce attributes and Spartoo fields (color, gender, brand, size, etc.).
What Spartwoo does not do
- It does not send refunds to Spartoo (the Spartoo API does not provide this endpoint — financial refunds are handled directly by the marketplace when a return is validated).
- It does not create categories on Spartoo — you must use those already available on the marketplace side.
- It does not synchronize customer reviews (feature not available in the Spartoo API).
Technical requirements
To work correctly, Spartwoo requires a recent technical stack. Verify compliance before installation.
| Component | Minimum version | Recommended |
|---|---|---|
| WordPress | 6.0 |
6.4+ |
| WooCommerce | 7.0 |
8.0+ with HPOS enabled |
| PHP | 7.4 |
8.1+ |
| PHP memory | 128 MB | 256 MB ou plus |
| PHP extensions | curl, simplexml, mbstring, gd |
|
On the Spartoo side
You must have an active Spartoo seller account with webservices access. The marketplace provides two essential credentials that we will use at the configuration step:
- Shop ID: the unique identifier of your shop on Spartoo.
- API Key: the authentication key that allows Spartwoo to call Spartoo webservices on your behalf.
If you don't have these credentials yet, contact your Spartoo commercial representative. The activation delay is usually 24 to 48 hours.
Installation and activation
Installation follows the standard WordPress plugin procedure. Allow less than five minutes for the initial setup.
- Download the
woo-spartoo-connect.zipfile provided with your license. - In WordPress, go to Plugins → Add New then Upload Plugin.
- Select the ZIP file and click Install Now.
- Activate the plugin with the Activate button.
- A new Spartoo menu appears in the dashboard sidebar.
Before any major installation or update, perform a complete backup of your site (database + files). Plugin data is stored in the database and is not affected by updates, but a backup remains the professional reference practice.
Updating from a previous version
When updating, WordPress simply replaces the plugin files. Your configurations (profiles, mappings, API credentials, enriched product pages) are stored in the database and remain intact. No manual reinstallation is needed.
Initial configuration
The first step is to connect Spartwoo to your Spartoo account via the webservice credentials. This is a one-time operation that remains valid until revocation on the marketplace side.
- Go to Spartoo → Accounts in the WordPress sidebar.
- Click Add Account.
- Enter your Shop ID and Spartoo API Key.
- Choose the main language of the account (FR, EN, IT, DE, ES depending on your market).
- Click Test Connection. If everything is fine, a green message confirms communication with Spartoo.
- Click Save.
Synchronization scheduling
Once the account is created, go to Spartoo → Schedulers to schedule automatic tasks. Four crons are available:
| Cron | Role | Recommended frequency |
|---|---|---|
| Stock sync | Updates quantities on Spartoo | Every 30 minutes |
| Orders fetch | Fetches new Spartoo orders | Every 6 minutes |
| Catalog sync | Resends the full catalog | Once a day |
| Existing products sync | Updates already-published listings | Every 2 hours |
For high-volume sites (more than 1,000 products), it may be useful to use the Linux system cron rather than the WordPress wp-cron, which depends on traffic. Ask your host to add a crontab entry: */5 * * * * curl -s https://yoursite.com/wp-cron.php
Profile creation
A profile in Spartwoo is a mapping configuration that applies to a group of products sharing the same export rules. For example, you will typically have one profile per product category: "Women's sandals", "Men's sneakers", "Dresses", etc.
Each profile defines, for the relevant Spartoo category:
- Which WooCommerce field to send in
manufacturers_name(the brand) - Which WC attribute corresponds to the Spartoo color
- Which WC attribute corresponds to the size
- Where the EAN/barcode comes from (custom postmeta)
- How to build the product name sent to Spartoo
Creating a profile
- Go to Spartoo → Profiles.
- Click Add Profile.
- Give the profile a clear name (e.g. Women's summer sandals).
- Choose the target Spartoo category from the hierarchical list.
- Click Save Profile.
- Once created, click the profile to open the mapping editor.
Field mapping
The profile editor displays all Spartoo fields available for this category. For each field, choose the source on the WooCommerce side:
- Product attribute: one of the declared WooCommerce attributes (taxonomy or local).
- Custom postmeta: a custom field (e.g.
_alg_ean,_gtin). - Fixed value: identical value for all products in the profile (useful for gender, for example).
Enabling/disabling a profile
Each profile can be enabled or disabled via the toggle switch (introduced in v1.5.48). A disabled profile retains its configuration but is no longer applied during synchronizations.
Start by creating a single test profile on a category with 5 to 10 products. Validate the result in the XML export before generalizing to your entire catalog. This prevents discovering a bad mapping after sending hundreds of listings.
Category mapping
For a WooCommerce product to be sent to Spartoo with the correct profile, it must be associated with a WooCommerce category that is itself mapped to a Spartoo profile. This WC Category → Spartoo Profile → Spartoo Category chain determines the routing of each listing.
- Go to Spartoo → Categories.
- For each listed WooCommerce category, select the corresponding Spartoo profile in the dropdown.
- Click Save mapping.
A product belonging to several WC categories will be processed with the profile of the first mapped category found. If none of the product's categories has a mapped profile, the product is excluded from synchronization and appears in the Spartoo profile not assigned alerts.
Product-level profile
For special cases, you can also assign a profile directly on the product page, which overrides the category mapping. Use this option for hybrid products or one-off exceptions.
Product page preparation
A product listing sent to Spartoo must follow a few precise rules. The alert system (section 10) automatically flags non-compliant listings, but here are the points to verify from the very start.
Essential fields
Product name
The name sent to Spartoo must be short, descriptive and bare. It must not contain color, brand, product type or size — Spartoo handles this information in dedicated fields and may reject or double-categorize if they appear in the name.
If your WooCommerce title contains these elements (often the case for SEO), use the Spartoo product name metabox located above the description editor. Fill it with a short and clean version (ideally the model name or internal reference). Then enable the Use the name product spartoo mode in the relevant profile.
Colors (Blue, Black, Rosa…), brands (Nike, Adidas…), product types (Dress, Coat, Sneaker, Sandal…), sizes (XS, S, 38, 42…). The alert system automatically detects these terms and raises a warning.
Description and short description
Spartwoo automatically cleans descriptions of AI editor residue (attributes data-start, data-end, data-is-last-node) and invalid HTML entities. So you can copy-paste from ChatGPT, Notion or Claude without worry.
EAN / barcode
Spartoo requires one EAN (or GTIN) per variation. If you use the Cost of Goods plugin or another that stores the EAN in custom postmeta, specify the metakey in the profile (the EAN field of the mapping).
Images
A quality main image is required (critical alert otherwise). Spartwoo automatically encodes URLs (spaces, accents, apostrophes) before transmitting them to Spartoo, which guarantees the marketplace can download them.
Variations
For variable products, each variation must have its size attribute filled. A variation without a size is automatically skipped at export to prevent it from showing up on Spartoo as "Unique" (which distorts the total stock).
Additional recommended fields
- Gender (man/woman/unisex) via WC attribute
- Color via WC attribute mapped in the profile
- Material composition (leather, textile, synthetic)
- Country of origin (dedicated field on the Spartwoo product page)
Catalog synchronization
Once the profiles are created and listings prepared, two synchronization modes are available: manual and automatic.
Manual synchronization
- Go to Spartoo → Products.
- Filter the products to send (by category, status, type).
- Check Select all products to export on spartoo or select products individually.
- In the Bulk actions dropdown menu, choose Upload / Update Products.
- Click Apply.
- The spinner indicates progress. A notification confirms the end of the upload.
Automatic synchronization
Once the schedulers are enabled (see section 4), Spartwoo automatically synchronizes:
- Stock every 30 minutes (file
inventory.xml) - The complete catalog once a day (file
product.xml) - New orders every 6 minutes
Les fichiers XML générés sont stockés dans wp-content/uploads/techcommerce/spartoo/ et restent accessibles pour vérification ou debug.
Verify the synchronization
Three ways to check that a synchronization went well:
- WooCommerce → Statut → Logs : sources
spartoo-http,spartoo-export,spartoo-stock. Chaque appel API y est tracé avec la réponse Spartoo. - Spartoo back-office: log into your Spartoo seller account, the My products tab lists imported listings with their status (published, pending, rejected).
- Page Diagnostic dans Spartwoo : un récapitulatif synthétique de la dernière synchronisation et des erreurs éventuelles.
Order management
Spartoo orders are imported automatically into WooCommerce as if they were native orders. This lets you use all your usual tools (preparation, shipping, invoicing, accounting) without changing systems.
Order lifecycle
| Statut Spartoo | Statut WooCommerce | Action attendue |
|---|---|---|
| Nouveau | processing |
Préparer et expédier |
| Expédié | completed |
Suivi de livraison côté Spartoo |
| Annulation Confirmée | cancelled + refund automatique |
Restock automatique côté WC |
| Retour en cours | processing (note ajoutée) |
Vérifier état du produit reçu |
Auto-refund WooCommerce
When a Spartoo order moves to Cancellation Confirmed while it already existed in WooCommerce with a processing or completed status, Spartwoo automatically creates a full WooCommerce refund. This maintains accounting consistency: your revenue report accurately reflects real transactions.
The WC refund automatically includes:
- The full order amount (all lines + taxes)
- Une note explicative dans la commande
- Un restock automatique des produits remboursés
- Un log dans
WooCommerce → Statut → Logs → spartoo-refund
The actual refund to the customer is handled directly by Spartoo on the marketplace side (the Spartoo API has no refund endpoint). The WooCommerce refund created by Spartwoo is only an accounting trace; it does not transfer money.
Alert system
The Spartoo → Alerts dashboard centralizes problems detected on your product listings before they are sent to the marketplace. Each alert type indicates a risk of rejection or non-compliance.
Available alert types
| Alerte | Severity | How to fix |
|---|---|---|
| Prix manquant | Critical | Renseigner un prix régulier sur la fiche WooCommerce. |
| SKU manquant | Critical | Renseigner un SKU unique (référence envoyée à Spartoo). |
| Catégorie Spartoo non mappée | Critical | Mapper la catégorie WC dans Spartoo → Catégories. |
| Titre WordPress par défaut | Critical | Renseigner un vrai titre (le titre est resté sur AUTO-DRAFT). |
| Stock non géré | Warning | Activer la gestion du stock sur le produit ou ses variations. |
| Image manquante | Warning | Ajouter une image principale à la fiche produit. |
| Profil Spartoo non assigné | Warning | Mapper la catégorie WC du produit ou assigner un profil sur la fiche. |
| Genre manquant | Warning | Ajouter un attribut genre/sexe au produit. |
| Couleur non mappée | Warning | Configurer le mapping couleur dans le profil correspondant. |
| Nom de produit non conforme | Warning | Le nom contient des termes interdits (couleur, marque, type, taille). Renseigner un nom propre dans la metabox Spartoo product name. |
Recommended workflow
- Click Rescan now in the Alerts dashboard.
- First filter by severity Critical: these products will be rejected by Spartoo.
- Click each problematic product to open its WooCommerce listing and fix it.
- Once critical alerts are handled, move on to Warnings to optimize listing quality.
- Relancez un scan pour confirmer que les alertes ont disparu.
Best practices
Before the first synchronization
- Faites une sauvegarde complète du site (BDD + fichiers).
- Testez d'abord sur 5 à 10 produits pilotes avant d'envoyer tout le catalogue.
- Make sure your EANs are unique and in the correct format (13 digits for shoes).
- Standardisez vos tailles (préférez « 36 » à « FR 36 » ou « EU 36 »).
Day-to-day
- Check the Alerts dashboard every morning before automatic synchronizations.
- To add a new Spartoo product, duplicate an existing well-mapped product. It's faster than creating everything from scratch.
- Pour les produits saisonniers ou en rupture, désactivez-les côté WooCommerce (statut brouillon). Ils seront retirés du flux Spartoo automatiquement.
Performance and maintenance
- Utilisez WooCommerce avec HPOS activé (High-Performance Order Storage) pour de meilleures performances sur les commandes.
- Enable a cache system (WP Rocket, WP Super Cache) — Spartwoo does not interfere with public page caching.
- Monitor the size of
wp-content/uploads/techcommerce/. For large catalogs, this folder can reach several hundred MB.
Security
- Ne partagez jamais votre API Key Spartoo. Elle donne accès à vos données vendeur.
- Limitez l'accès à la page Spartoo → Comptes aux administrateurs uniquement.
- Monitor the
spartoo-httplogs to detect abnormally numerous calls.
Frequently asked questions
wp-content/plugins/woo-spartoo-connect/. Vos données restent intactes. Une sauvegarde reste néanmoins recommandée par principe.
spartoo-stock logs to identify the responsible variation.