Aurora API: Product

Product

Add

Deferred: No

🚧
This method is deferred if requests are made without a limit or paging applied.

Products are unique in the API in that the Update and Add commands are nearly interchangeable. If you send a product to 'ProductAdd' that already exists, then it will be updated. This is not true of sending new products to the 'ProductUpdate' command. When updating the product must already exist or the request will fail.

The reason existing products are updated in the Add command is simply to provide a more convenient transition for our existing Product CSV Import users. You can simply send your entire product database to the 'ProductAdd' command and it will deal with what needs updating and adding for you.

The ProductAdd command supports some required field values to be used as defaults when adding new products but leaves the values of existing products untouched. This is done via the attribute "default_only" for certain fields

Example XML fragments:

....

<ProductName default_only="1">Test web description product</ProductName>

....<DisplayProduct default_only="1">1</DisplayProduct>
....
<Categories default_only="1">
	<Category>Clothing</Category>
	<Category>Clothing | Tops</Category>
	<Category>Top 10</Category>
</Categories>

....

see http://api_url/api_version/aurora.xsd for full details

Example request:

 <?xml version="1.0" encoding="utf-8"?>
 <AuroraRequestEnvelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
     <Header>
         <AuthToken>...</AuthToken>
     </Header>
     <Requests>
         <Request>
             <Product>
                 <Add>
                     <ProductReference>PRODUCTSKU1</ProductReference>
                     <ProductName>Test web description product</ProductName>
                     <DisplayProduct>1</DisplayProduct>
                     <ProductStock>0</ProductStock>
                     <Categories>
                         <Category>Clothing</Category>
                         <Category>Clothing | Tops</Category>
                         <Category>Top 10</Category>
                     </Categories>
					 <MainCategory>Clothing</MainCategory>
					 <MainSubcategory>Clothing | Tops</MainSubcategory>
                     <ProductCopy>Test web description</ProductCopy>
                     <ProductPrices>
                         <Currency>
                             <ISO>GBP</ISO>
                             <Price>24.99</Price>
                             <PriceRRP>24.99</PriceRRP>
                         </Currency>
                     </ProductPrices>
                     <TaxBand>Band A</TaxBand>
                     <Variations>
                         <Variation>
                             <VariationReference>VARIAITONSKU1</VariationReference>
                             <VariationEAN>12345678901</VariationEAN>
                             <VariationStyleCode>STYLE1</VariationStyleCode>
                             <VariationStock>2</VariationStock>
                             <VariationBinNumber>A21-21A</VariationBinNumber>
                             <VariationPrices>
                                 <Currency>
                                     <ISO>GBP</ISO>
                                     <Price>20.99</Price>
                                     <PriceRRP>20.99</PriceRRP>
                                 </Currency>
                             </VariationPrices>
                             <VariationDimensionsWidth>10</VariationDimensionsWidth>
                             <VariationDimensionsLength>15</VariationDimensionsLength>
                             <VariationDimensionsHeight>5</VariationDimensionsHeight>
                             <VariationDimensionsMeasurement>cm</VariationDimensionsMeasurement>
                             <VariationWeight>250</VariationWeight>
                             <VariationWeightMeasurement>grams</VariationWeightMeasurement>
                             <Attributes>
                                 <Attribute>
                                     <Name>Colour</Name>
                                     <Value>Red</Value>
                                 </Attribute>
                                 <Attribute>
                                     <Name>Size</Name>
                                     <Value>Small</Value>
                                 </Attribute>
                             </Attributes>
                         </Variation>
                     </Variations>
                 </Add>
             </Product>
         </Request>
     </Requests>
 </AuroraRequestEnvelope>

Example Response:

 <?xml version="1.0" encoding="utf-8"?>
 <AuroraResponseEnvelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
     <Header>
         <AuthTokenValidation>
             <AuthTokenIsValid>1</AuthTokenIsValid>
             <IPAddressValidation>
                 <IPAddressIsValid>1</IPAddressIsValid>
                 <IPAddressValidationFor>192.168.1.1</IPAddressValidationFor>
             </IPAddressValidation>
             <WebsiteValidation>
                 <WebsiteIsValid>1</WebsiteIsValid>
             </WebsiteValidation>
             <UserKeyValidation>
                 <UserKeyIsValid>1</UserKeyIsValid>
             </UserKeyValidation>
             <AuthenticatedDomainToken>1</AuthenticatedDomainToken>
         </AuthTokenValidation>
     </Header>
     <Responses>
         <Response>
             <Product>
                 <ProductID>1003</ProductID>
                 <ProductWasAdded>1</ProductWasAdded>
                 <Variations>
                     <Variation>
                         <VariationID>1024</VariationID>
                         <VariationWasAdded>1</VariationWasAdded>
                     </Variation>
                 </Variations>
             </Product>
         </Response>
     </Responses>
 </AuroraResponseEnvelope>

Search

Example request:

 <?xml version="1.0" encoding="utf-8"?>
 <AuroraRequestEnvelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
     <Header>
         <AuthToken>...</AuthToken>
     </Header>
     <Requests>
         <Request>
             <Product>
                 <Search>
                     <Path>/mens/s:boot/</Path>
                     <ABTestingValue>42</ABTestingValue>
                     <DeviceType>mobile</DeviceType>
                     <OpenField>BoldText</OpenField>
                     <DetailLevel>Minimum</DetailLevel>
                     <Language>en-gb</Language>
                     <Paging>
                         <Limit>30</Limit>
                         <Page>2</Page>
                     </Paging>
                     <OrderBy>1</OrderBy>
                 </Search>
             </Product>
         </Request>
     </Requests>
 </AuroraRequestEnvelope>

Example Response:

 <?xml version="1.0" encoding="utf-8"?>
 <AuroraResponseEnvelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
     <Header>
         <AuthTokenValidation>
             <AuthTokenIsValid>1</AuthTokenIsValid>
             <IPAddressValidation>
                 <IPAddressIsValid>1</IPAddressIsValid>
                 <IPAddressValidationFor>192.168.1.1</IPAddressValidationFor>
             </IPAddressValidation>
             <WebsiteValidation>
                 <WebsiteIsValid>1</WebsiteIsValid>
             </WebsiteValidation>
             <UserKeyValidation>
                 <UserKeyIsValid>1</UserKeyIsValid>
             </UserKeyValidation>
             <AuthenticatedDomainToken>1</AuthenticatedDomainToken>
         </AuthTokenValidation>
     </Header>
     <Responses>
         <Response>
             <Data>
                 <Products>
                     <Product>
                         <ProductID>101</ProductID>
                         <ProductReference>PRODUCTSKU1</ProductReference>
                     </Product>
                     <Product>
                         <ProductID>102</ProductID>
                         <ProductReference>PRODUCTSKU2</ProductReference>
                     </Product>
                 </Products>
                 <Categories>
                     <Category>
                         <CategoryID>125</CategoryID>
                         <CategoryName>Shoes</CategoryName>
                         <Path>/mens/s:boot/shoes/</Path>
                         <ProductCount>24</ProductCount>
                     </Category>
                     <Category>
                         <CategoryID>175</CategoryID>
                         <CategoryName>Accessories</CategoryName>
                         <Path>/mens/s:boot/accessories/</Path>
                         <ProductCount>7</ProductCount>
                     </Category>
                 </Categories>
                 <Filters>
                     <Filter>
                         <FilterName>Size</FilterName>
                         <Abbreviation>si</Abbreviation>
                         <Values>
                             <Value>
                                 <Raw>6</Raw>
                                 <Clean>6</Clean>
                                 <Path>/mens/s:boot/si:6/</Path>
                                 <ProductCount>4</ProductCount>
                             </Value>
                             <Value>
                                 <Raw>7</Raw>
                                 <Clean>7</Clean>
                                 <Path>/mens/s:boot/si:7/</Path>
                                 <ProductCount>10</ProductCount>
                             </Value>
                             <Value>
                                 <Raw>8</Raw>
                                 <Clean>8</Clean>
                                 <Path>/mens/s:boot/si:8/</Path>
                                 <ProductCount>15</ProductCount>
                             </Value>
                             <Value>
                                 <Raw>9</Raw>
                                 <Clean>9</Clean>
                                 <Path>/mens/s:boot/si:9/</Path>
                                 <ProductCount>16</ProductCount>
                             </Value>
                             <Value>
                                 <Raw>10</Raw>
                                 <Clean>10</Clean>
                                 <Path>/mens/s:boot/si:10/</Path>
                                 <ProductCount>8</ProductCount>
                             </Value>
                         </Values>
                     </Filter>
                     <Filter>
                         <FilterName>Colour</FilterName>
                         <Abbreviation>co</Abbreviation>
                         <Values>
                             <Value>
                                 <Raw>Black</Raw>
                                 <Clean>black</Clean>
                                 <Path>/mens/s:boot/co:black/</Path>
                                 <ProductCount>16</ProductCount>
                             </Value>
                             <Value>
                                 <Raw>Brown</Raw>
                                 <Clean>brown</Clean>
                                 <Path>/mens/s:boot/co:brown/</Path>
                                 <ProductCount>4</ProductCount>
                             </Value>
                             <Value>
                                 <Raw>Tan</Raw>
                                 <Clean>tan</Clean>
                                 <Path>/mens/s:boot/co:tan/</Path>
                                 <ProductCount>10</ProductCount>
                             </Value>
                             <Value>
                                 <Raw>Grey</Raw>
                                 <Clean>grey</Clean>
                                 <Path>/mens/s:boot/co:grey/</Path>
                                 <ProductCount>1</ProductCount>
                             </Value>
                         </Values>
                     </Filter>
                 </Filters>
                 <Paging>
                     <Page>2</Page>
                     <TotalProducts>31</TotalProducts>
                     <IsMore>0</IsMore>
                     <TotalPages>2</TotalPages>
                 </Paging>
                 <MetaData>
                     <Path>/mens/s:boot/</Path>
                 </MetaData>
             </Data>
             <Summary>
                 <RequestWasRedirected>0</RequestWasRedirected>
                 <TrackingCode>CODE1</TrackingCode>
             </Summary>
         </Response>
     </Responses>
 </AuroraResponseEnvelope>

Request Fields

Field	Values	API Version	Description	Required
Path	String	1.4+	This path should reflect the URL for the desired product listings page, including all categories and filters. This path can be obtained from the "Path" elements returned within all Category and Filter response XML provided by the "ProductSearch" method, as described later in this document.	No
ABTestingValue	Integer 1 to 100	1.4+	This is the value used by Aurora when deciding with A/B Testing Action Groups to deploy to a request. See the Merchandising Rules Support Article for more information regarding Action Groups and A/B Testing.	No
DeviceType	[ desktop \| mobile ]	1.4+	This describes whether the requested data is being displayed on a desktop or mobile device and is used by the Merchandising Rules system when checking it's conditions.	No
OpenField	String	1.4+	This is an open test field that can contain any desired, plain text value and is used exclusively by the Merchandising Rules system when checking it's conditions.	No
ChannelCode	Restricted String	1.4+	The Internal Channel Code Aurora has configured for a Product Channel in the Aurora Back-end. If specified, this will return products for the specified channel only and no others. Otherwise it will return the products found in the 'desktop' channel if it exists or just 'all' products currently available if it is not. To find out what values are permitted here, please refer to the API's XSD file, which can be found on your API URL as http://api_url/api_version/aurora.xsd	No
CategoryID	Integer	1.4+	The Internal ID Aurora uses to identify a Product Category. If specified, this will override any category passed in the "Path" element, but all other filters will still be applied. It is recommended that the "Path" element is used instead of this "CategoryID" field to specify the category as it is better optimised for this purpose. This field is provided only for when the Category Path is unknown.	No
SearchTerm	String	1.4+	This can be any string value to run through the Aurora product search. Results will be filtered by this term as they would via the website front-end.	No
LocaleCode	String	1.5+	The Locale Code allows you to tell Aurora which Locale it should perform this search upon. If no locale is provided, then the Store's default locale will be used.	No
DetailLevel	Detail Levels	1.4+	This allows the client to request varying volumes of data when receiving data back from the server.	No
Language	Restricted String	1.4+	This should be the Language ISO Code that the Filter, Category and Meta information should be returned in. To find out what values are permitted here, please refer to the API's XSD file, which can be found on your API URL as http://api_url/api_version/aurora.xsd	No (Defaults to "en-gb", English)
Paging	Container	1.4+		No
Paging.Limit	Integer > 0	1.4+	The number of results to return in the page being requested	No
Paging.Page	Integer > 0	1.4+	The page number to return the results for	No
OrderBy	Restricted Integer	1.4+	This value is the ID of the Order By set that you would like to use. These are customisable in Aurora and configured by every client independently, so it is important to check what values you need to use here using the XSD or contact the client for more information. To find out what values are permitted here, please refer to the API's XSD file, which can be found on your API URL as http://api_url/api_version/aurora.xsd	No

Response fields

Field	Values	API Version	Description	Detail Levels
Products	Container	1.4+		Minimum +
Products.ProductID	Integer > 0	1.4+	The Internal ID Aurora uses to identify a Product.	Minimum +
Products.ProductReference	String	1.4+	The main Product Reference (usually the SKU) assigned to the Product.	Minimum +
Categories	Container	1.4+	Contains all 'next-level' (sub-)categories that are available within the results of the current request.	Minimum +
Categories.Category	Container	1.4+		Minimum +
Categories.Category.CategoryID		1.4+	The Internal ID Aurora uses to identify a Product Category.	Minimum +
Categories.Category.CategoryName		1.4+	The name of the Category as displayed contains all 'next-level' (sub-)categories that are available within the results of the current request.	Minimum +
Categories.Category.Path		1.4+	The new path value required to view this categories products. This value can be passed back to the ProductSearch Method as it is to retrieve the products from that category.	Minimum +
Categories.Category.ProductCount		1.4+	The number or products within the current request that fall within this (sub-)category.	Minimum +
Filters	Container	1.4+	Contains all filters and the values that are still available for them within the results of the current request.	Minimum +
Filters.Filter	Container	1.4+		Minimum +
Filters.Filter.FilterName	String	1.4+	The name of the Filter as displayed to the Customer on the Website front-end.	Minimum +
Filters.Filter.Abbreviation	String	1.4+	The short (usually 2-3 characters) abbreviation string used to identify the Filter.	Minimum +
Filters.Filter.Values	Container	1.4+	Contains all values that are still available for this filter within the results of the current request.	Minimum will exclude values from the results where they would contain no products. Full will show all values, providing the values that were applicable, but are no longer available.
Filters.Filter.Values.Value	Container	1.4+		Minimum +
Filters.Filter.Values.Value.Raw	String	1.4+	The unformatted value as displayed to the Customer on the Website front-end.	Minimum +
Filters.Filter.Values.Value.Clean	String	1.4+	The sanitized (URL-safe) version of the value. This is used when passing the desired filter values to the Website and API via the "Path" property.	Minimum +
Filters.Filter.Values.Value.Path	String	1.4+	The new path value required to view products matching this filter value. This value can be passed back to the ProductSearch Method as it is to retrieve the matching products.	Minimum +
Filters.Filter.Values.Value.ProductCount	Integer	1.4+	The number or products within the current request that match this filter value.	Minimum +
Paging	Container	1.4+		Minimum +
Paging.Page	Integer > 0	1.4+	The current page being returned.	Minimum +
Paging.TotalProducts	Integer	1.4+	The total number of pages available for the current request.	Minimum +
Paging.IsMore	1 or 0	1.4+	A simple flag to indicate whether or not there are more pages to be fetched after the current one.	Minimum +
Paging.TotalPages	Integer	1.4+	The total number of pages available for the current request.	Minimum +
MetaData	Container	1.4+	This data is provided for reference only and is based on the values normally generated for the searches being performed on the Website front-end.	Minimum +
MetaData.Path	String	1.4+	The path value describing the current request in full. This value can be passed back to the ProductSearch Method as it is to retrieve these results again. This value can be attached to a valid Client Domain Name to view the results of the request within the Website front-end itself, e.g. Path of "/mens/co:blue/" can be access as "https://demo.auroracommerce.com/mens/co:blue/"	Minimum +
Summary	Container	1.4+	Contains a summary of any information pertaining to this specific request.	Minimum +
Summary.RequestWasRedirected	0 or 1	1.4+	This will be 0 (Zero) if no Search Redirects were applied to the request and 1 if there was. Please see the Search Redirects User Guide for more details regarding what Search Redirects are and how to use them.	Minimum +
Summary.RedirectionURL	String	1.4+	This will detail the Path/URL provided in the original request in the event a Search Redirection occurred. When a Search Redirect is triggered, all other filters and categories specified for the request are disregarded as the redirect takes precedence. It is important to use the URLs provided in the resulting Filters.Filter section(s) to avoid being continually redirected when attempting to apply filters, i.e. you should not simply re-submit the request with the search phrase again when further filtering a redirected request.	Minimum +
Summary.RequestedURL	String	1.4+	This will detail the Path/URL used for the response in the event a Search Redirection occurred.	Minimum +
Summary.TrackingCode	String	1.5+	This will be the Tracking Code assigned in the Merchandising Rules (considering the A/B testing rules where applicable). See the Merchandising Rules Support Article for more information regarding Action Groups and A/B Testing.	Minimum +

You may notice that the Detail Level allows the retrieval of Values for Filters that no longer provide any results. This is useful for displaying what options might once have been available but are now disabled. The Website front-end normally uses this to display all options while 'greying out' the now irrelevant ones.

Errors

Error: The requested Path is not a valid Product listing Path.
Code: -1
Severity: FATAL
API Version: 1.4+

This occurs when the request being made is attempting to access a Path or combination of settings that do not result in a valid product listing.

This can occurs when an invalid Category or Path is provided, among other things.

👍
If you see this error, check that your request is:

using a valid Path and/or Category

not being redirected to an invalid location using a Search Redirect

Error: The Path "/example_url/" was redirected to "/example_redirected_url/" by the Aurora Search Redirects configuration.
Code: -13
Severity: WARNING
API Version: 1.4+

This occurs when the Search Redirects system is used to redirect an API request to another URL.

This is only ever returned when some other error occurs that prevents the request from working. If the request runs without any other fatal errors, then this warning is not returned at all (please see the Search section in this support article for further detail regarding dealing with this under normal circumstances, i.e. when no actual error has occurred).

Updated about 1 month ago