Home > Webservices > Import products

Importing products

Webservice URL : https://sws.spartoo.com/mp/xml_import_products.php

This webservice creates and updates products on the Spartoo website.
For each product sent, the webservice will send back an error code to indicate whether everything is ok or not. Certain errors are serious (fatal), others are not (warning).

This webservice creates products and updates your catalogue. It can be used to send the whole catalogue or only a few products.

Frequency of use:
- When using this webservice to update the whole catalogue, we advise that you do this once every 6 hours.
- When using this webservice to update only part of the catalogue (for a few products only), you can do this up to every 10 minutes.

This webservice functions in an "Update" mode rather than a "Overwriting" mode, meaning that the products not included in the XML file will not be deleted.
To take a product offline, you must put the stock to 0.

List of Parameters

The settings of this webservice must be registered in POST

Settings	Description
partner	Must contain your unique code :
xml	XML character string containing the list of elements to be created or updated

Optional settings that can be passed in POST

Settings	Description
force_description	Set to 1 if you want to force product descriptions to be updated: delete existing descriptions, edit the description of a product with zero stock, etc.
force_overwrite	Set to 1 if you want to remove stock errors from the catalogue. Be careful to send the rest of the catalogue without overwriting immediately afterwards.
async	Set to 1 if you wish to use the asynchronous method

XML parameter format

The text fields must be protected by CDATA tags if they contain special characters that would make the XML invalid.

Format single country

<root>
	<products>
		<product>
			<reference_partenaire>string</reference_partenaire>
			<product_name>string</product_name>
			<manufacturers_name>string</manufacturers_name>
			<product_sex>char</product_sex>
			<product_price>float</product_price>
			<product_quantity>int</product_quantity>
			<color_id>int</color_id>
			<product_style>int</product_style>
			<product_description>string</product_description>
			<product_color>string</product_color>
			<heel_height>float</heel_height>
			<country_origin>int</country_origin>
			<code_hs>int</code_hs>
			<size_list>
				<size>
					<size_name>string</size_name>
					<size_quantity>int</size_quantity>
					<size_reference>string</size_reference>
					<ean>string</ean>
					<code_hs>int</code_hs>
					<product_price>float</product_price>
					<discount>
						<startdate>timestamp</startdate>
						<stopdate>timestamp</stopdate>
						<price_discount>float</price_discount>
						<rate>int</rate>
						<sales/>
					</discount>
				</size>
				<!-- ... Multiple "size" tags possible ... -->
			</size_list>
			<product_composition>int</product_composition>
			<voering_composition>int</voering_composition>
			<first_composition>int</first_composition>
			<zool_composition>int</zool_composition>
			<photos>
				<url1>url</url1>
				<url2>url</url2>
				<url3>url</url3>
				<url4>url</url4>
				<url5>url</url5>
				<url6>url</url6>
				<url7>url</url7>
				<url8>url</url8>
			</photos>
			<discount>
				<startdate>timestamp</startdate>
				<stopdate>timestamp</stopdate>
				<price_discount>float</price_discount>
				<rate>int</rate>
				<sales>0/1</sales>
			</discount>
			<extra_infos>
				<info>
					<id>int</id>
					<value>float</value>
				</info>
				<!-- ... Multiple "info" tags possible ... -->
			</extra_infos>
			<selections>
				<selection>int</selection>
				<!-- ... Multiple "selection" tags possible ... -->
			</selections>
		</product>
		<!-- ... Multiple "product" tags possible ... -->
	</products>
</root>

Format multi country

<root>
	<products>
		<product>
			<reference_partenaire>string</reference_partenaire>
			<manufacturers_name>string</manufacturers_name>
			<product_sex>char</product_sex>
			<product_quantity>int</product_quantity>
			<color_id>int</color_id>
			<product_style>int</product_style>
			<heel_height>float</heel_height>
			<country_origin>int</country_origin>
			<code_hs>int</code_hs>
			<languages>
				<language>
					<code>string</code>
					<product_name>string</product_name>
					<product_description>string</product_description>
					<product_color>string</product_color>
					<product_price>float</product_price>
					<discount>
						<startdate>timestamp</startdate>
						<stopdate>timestamp</stopdate>
						<price_discount>float</price_discount>
						<rate>int</rate>
						<sales />
					</discount>
				</language>
				<!-- ... Multiple "language" tags possible ... -->
			</languages>
			<size_list>
				<size>
					<size_name>string</size_name>
					<size_quantity>int</size_quantity>
					<size_reference>string</size_reference>
					<ean>string</ean>
					<code_hs>int</code_hs>
					<languages>
						<language>
							<code>string</code>
							<product_price>float</product_price>
							<discount>
								<startdate>timestamp</startdate>
								<stopdate>timestamp</stopdate>
								<price_discount>float</price_discount>
								<rate>int</rate>
								<sales/>
							</discount>
						</language>
						<!-- ... Multiple "language" tags possible ... -->
					</languages>
				</size>
				<!-- ... Multiple "size" tags possible ... -->
			</size_list>
			<product_composition>int</product_composition>
			<voering_composition>int</voering_composition>
			<first_composition>int</first_composition>
			<zool_composition>int</zool_composition>
			<photos>
				<url1>url</url1>
				<url2>url</url2>
				<url3>url</url3>
				<url4>url</url4>
				<url5>url</url5>
				<url6>url</url6>
				<url7>url</url7>
				<url8>url</url8>
			</photos>
			<extra_infos>
				<info>
					<id>int</id>
					<value>float</value>
				</info>
				<!-- ... Multiple "info" tags possible ... -->
			</extra_infos>
			 <selections>
				<selection>int</selection>
				<!-- ... Multiple "selection" tags possible ... -->
			</selections>
		</product>
		<!-- ... Multiple "product" tags possible ... -->
	</products>
</root>

Entry XML field description

Tag	Description	Required
reference_partenaire	Merchant product code. It is the sku that identifies a product of a brand in a precise color The product code may only contain alphanumeric characters as well as the following symbols: - (hyphen); _ (underscore); and . (full stop).	Yes
product_name	Style name Must not contain the category, colour, or brand of the product	No
manufacturers_name	Name of the product brand	Yes
product_sex	Product gender > See all possible values	Yes
product_price	Product price in euros (not compulsory for size prices)	Yes / Non
color_id	Colour for menu filters If the colour is not specified, the product will not show up if a customer uses the filter by colour > See all possible values	No
product_style	Product category > See all possible values	Yes
product_description	Product description. Appears on the product page.	No
product_color	Text field for the colour. Appears on the product page.	No
product_quantity	Total stock of a product Ignore if one or more size_quantity markers are detected for the product. For one-size products, a product_quantity marker is necessary when the size_quantity is not given.	No
size	List of sizes and their stock. Optional for products with sizes (Bags/Accessories). Otherwise required.	Non / Oui
size_name	Size name > See all possible values	Yes
size_quantity	For each size, the number in stock must be specified. To deactivate a product, set the stock at 0. The product will then no longer appear on Spartoo.	Yes
size_reference	Reference of product size. This field is only used for the exporting of orders and returns. A good idea is to generate this reference by combining the fields reference_partenaire and size_name with an underscore "_".	No
ean	EAN of product size	No
photos	List of photos and their url. At least one photo is needed. However, we recommend a minimum of 3 photos. A maximum of 8 photos can be included. The photo will only be uploaded once, then stored on our servers once it has been resized to fit Spartoo dimensions. Photos must be in jpg format, square and a minimum of 350x350 pixels. If they are above or equal to 800x800 pixels, a zoom will be available on the site.	Yes
url1, url2 ... url8	Links to the photos You must provide one link per photo. Only alphanumeric characters and the characters "-" (dash), "_" (underscore) and"." (full stop) can be included in the file name. Spaces and accented letters (e.g. é, à, ñ) are not allowed.	Yes
heel_height	Heel height in centimetres (cm). Only for women's shoes. Must be a multiple of 0,5.	No
product_composition	Material of the product upper. Only for shoes. > See all possible values	No
voering_composition	Material of the product lining. Only for shoes. > See all possible values	No
first_composition	Material of the product insole. Only for shoes. > See all possible values	No
zool_composition	Material of the product outer sole. Only for shoes. > See all possible values	No
discount	Allows you to apply a promotion to a product or size. The field rate in the discount field applies to the discount by percentage with regards to the field product_price. The field price_discount in the discount concerns the discounted price of the fixed product. The discount percentage displayed will be calculated. If both fields are present, the price_discount field takes precedence over the rate field. If the discount is to start immediately, there's no need to fill in the field start date. If the stopdate field is not specified, the promotion will have a default duration of one month. If the field sales is specified, the offer will be a sales discount. Otherwise, it will be a standard offer. By defining this parameter, the item will appear on the sale page during the sales.	No
extra_infos	Specify additional information depending on the type of product. Each information is constituted by an id ( > See values ) and a numerical value.	No
selections	Specify the context of use thanks to a id list All the possible id are available here.	No

XML parameter example

<root>
	<products>
		<product>
			<reference_partenaire>98</reference_partenaire>
			<product_name><![CDATA[ALL STAR HI]]></product_name>
			<manufacturers_name><![CDATA[Converse]]></manufacturers_name>
			<product_sex>M</product_sex>
			<product_price>64.99</product_price>
			<product_quantity>5</product_quantity>
			<color_id>8</color_id>
			<product_style>10010</product_style>
			<product_description><![CDATA[A legend among legends, the Chuck Taylor All Star from Converse is a classic!
Here you'll find the high-top version with a classic printed upper that gives them a stylish and classic look. 
]]></product_description>
			<product_color><![CDATA[Red]]></product_color>
			<country_origin>73</country_origin>
			<code_hs>64059090</code_hs>
			<size_list>
			 <size>
				<size_name>38</size_name>
				<size_quantity>4</size_quantity>
				<size_reference>98_38</size_reference>
				<ean>123456789011></ean>
			 </size>
			 <size>
				<size_name>39</size_name>
				<size_quantity>1</size_quantity>
				<size_reference>98_39</size_reference>
				<ean>123456789012></ean>
			 </size>
			</size_list>
			<product_composition>4</product_composition>
			<photos>
				<url1>https://imgext.spartoo.com/photos/98/98/98_350_A.jpg</url1>
				<url2>https://imgext.spartoo.com/photos/98/98/98_350_B.jpg</url2>
				<url3>https://imgext.spartoo.com/photos/98/98/98_350_C.jpg</url3>
				<url4>https://imgext.spartoo.com/photos/98/98/98_350_D.jpg</url4>
				<url5>https://imgext.spartoo.com/photos/98/98/98_350_E.jpg</url5>
				<url6>https://imgext.spartoo.com/photos/98/98/98_350_F.jpg</url6>
				<url7>https://imgext.spartoo.com/photos/98/98/98_350_G.jpg</url7>
				<url8>https://imgext.spartoo.com/photos/98/98/98_350_H.jpg</url8>
			</photos>
			<discount>
				<startdate>1199170800</startdate>
				<stopdate>1204354800</stopdate>
				<rate>20</rate>
			</discount>
		</product>
	</products>
</root>

XML format returned

<root>
	<products>
		<product>
			<reference_partenaire>string</reference_partenaire>
			<status>string</status>
			<action>string</action>
			<errors>
				<error>
					<id>int</id>
					<description>string</description>
					<level>string</level>
				</error>
				<!-- ... Multiple "error" tags possible ... -->
			</errors>
		</product>
		<!-- ... Multiple "product" tags possible ... -->
	</products>
	<errors>int</errors>
</root>

List of webservice error codes

Code	Description
1	No error with parameters
-1	The parameter partenaire has not been set up or it is empty
-2	The parameter partenaire does not exist
-11	The parameter xml has not been set up or it is empty
-15	XML syntax error, verify your XML file
-428	Your account has been deactivated. You will no longer have access to our online services.
-429	You have made too many online requests during this 1-hour time period.

XML response field description

Tag	Description
reference_partenaire	Merchant product code
status	OK if the product is registered in database KO if the product has not been registered
action	List of possible actions : created: the product was created. not created: the product was not created. Note: a product can have a status 'OK' but not have been created after some 'Warning'. updated: the product was updated. not updated: the product was not updated. Note : a product can have a status 'OK' but not have been updated after some 'Warning'.
errors	List of processing errors: id : Product error code level: error level Warning: does not block product integration Fatal: blocks product integration description: error text description

List of product error codes

Code	Level	Description
1	Fatal	The partner reference is not long enough
2	Fatal	The partner reference is not valid, it can only contain alphanumeric characters
3	Warning	Product name is not specified
4	Fatal	The brand is not specified
5	Fatal	The type XXX is not valid, the only possible values are: H , F , M, K , G , B
6	Fatal	The price must be a number
7	Fatal	the price is negative or not indicated
8	Warning	The price seems very large ( > £1000 )
81	Fatal	Price cannot be higher than 180 €
9	Fatal	The amount must be a whole number
10	Fatal	The amount must be positive
11	Warning	The colour xxx does not exist: the product will not be available through the colour filters
13	Fatal	The category xxx does not exist
14	Warning	The product description is empty
15	Warning	The colour description is empty
16	Warning	No size list: use a single size
17	Warning	The composition is specified, but is invalid
18	Fatal	Photo 1 is required
19	Warning	The rate of discount must be between 0 and 100, the discount will not be taken into account
20	Warning	The size xxx does not exist
201	Fatal	EAN code is required
202	Fatal	The EAN code xxx on the reference xxx in size xxx is already used by the reference: xxx
205	Fatal	Partner reference too long
23	Warning	The photo xxx is smaller than 350x350: it will be of poor quality on the website
24	Warning	The photo xxx is smaller than 350x350: it will not be displayed on the website
25	Fatal	Size xxx: Unable to regulate stock
26	Fatal	Not in stock: Product will not be created
27	Fatal	Unable to access photo 1 (url xxx)
28	Warning	Unable to access photo xxx (url xxx)
30	Fatal	The amount of the size xxx is too large (Max amount: xxx)
33	Fatal	A xxx product cannot be put under the category xxx
34	Fatal	The word xxx is blacklisted and it should not appear in the product name, nor in the product description.
35	Fatal	Product name too long, it must only contain the name of the model. Error(s) on: xxx
341	Fatal	The word xxx is blacklisted and should not appear in the product description.
36	Fatal	Unable to upload the product: the size/colour couple of the product has been duplicated
37	Fatal	You have not provided valid language information for this product
38	Fatal	The size xxx can only be set once for the reference xxx
39	Warning	The partner reference is present several times in the flow, duplicates have been ignored
451	Fatal	No price for size xxx in country xxx. (required for a discount)
452	Warning	End date of the discount exceeded for the size xxx of the country xxx.
453	Fatal	"rate" (xxx) invalid for the size xxx of the country xxx.
454	Fatal	"rate" (xxx) > 85% for the size xxx of the country xxx.
455	Warning	The size xxx has a price on a country (xxx) not defined for the product.
456	Warning	Size xxx has a price on xxx identical to the global price on this country.

XML return examples

Example of a response to a web service request KO :

<root>
	<products></products>
	<errors>-1</errors>
</root>

Example of a response to a web service request OK :

<root>
	<products>
		<product>
		<reference_partenaire>EEAJBCC</reference_partenaire>
		<status>KO</status>
		<action>not created</action>
		<errors>
			<error>
				<id>14</id>
				<description>The product description is empty</description>
				<level>warning</level>
			</error>
			<error>
				<id>4</id>
				<description>The brand is not specified</description>
				<level>fatal</level>
			</error>
		</errors>
		</product>
		<product>
			<reference_partenaire>KJHGFDS</reference_partenaire>
			<status>OK</status>
			<action>created</action>
		</product>
	</products>
	<errors>1</errors>
</root>

Files XSD

Files XSD Multiple countries