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>
<AttributeName>Size</AttributeName>
<AttributeValue>S/M</AttributeValue>
<AttributeValueAbbreviation>sm</AttributeValueAbbreviation>
<UseAsFilter>1</UseAsFilter>
<DisplayAttribute>1</DisplayAttribute>
<AttributeAbbreviation>si</AttributeAbbreviation>
</Attribute>
</Attributes>
</Variation>
<Variation>
<VariationReference>VARIAITONSKU2</VariationReference>
<VariationEAN>12345678902</VariationEAN>
<VariationStyleCode>STYLE1</VariationStyleCode>
<VariationStock>1</VariationStock>
<VariationBinNumber>A21-21A</VariationBinNumber>
<VariationPrices>
<Currency>
<ISO>GBP</ISO>
<Price>24.99</Price>
<PriceRRP>24.99</PriceRRP>
</Currency>
</VariationPrices>
<Attributes>
<Attribute>
<AttributeName>Size</AttributeName>
<AttributeValue>M/L</AttributeValue>
<AttributeValueAbbreviation>ml</AttributeValueAbbreviation>
<UseAsFilter>1</UseAsFilter>
<DisplayAttribute>1</DisplayAttribute>
<AttributeAbbreviation>si</AttributeAbbreviation>
</Attribute>
</Attributes>
</Variation>
</Variations>
</Add>
</Product>
</Request>
</Requests>
</AuroraRequestEnvelope>
Example response:
<?xml version="1.0" encoding="utf-8"?>
<AuroraResponseEnvolope>
<Header>
<Summary>
<Ack>OK</Ack>
<RequestsProcessed>1</RequestsProcessed>
<RequestsSucceeded>1</RequestsSucceeded>
<RequestErrors>0</RequestErrors>
</Summary>
</Header>
<Responses>
<Response>
<RequestID>1</RequestID>
<Ack>OK</Ack>
<Data>
<ProductID>261538</ProductID>
<ProductReference>5051741167878</ProductReference>
<Variations>
<Variation>
<VariationID>96781</VariationID>
<VariationReference>5051741167878</VariationReference>
</Variation>
<Variation>
<VariationID>96782</VariationID>
<VariationReference>5051741167885</VariationReference>
</Variation>
</Variations>
</Data>
</Response>
</Responses>
</AuroraResponseEnvolope>
Request Fields
This section only covers a few of the unique request fields that are applicable only to this method. All other fields are described with the ProductGet method.
| Field | Values | API Version | Description | Required |
|---|---|---|---|---|
| tracking | none or sent | 1.4+ | This is an attribute on the top level method element (i.e. or ) that can be used to explicitly set a product as sent. | No |
Update
Deferred: Yes
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>
<Update>
<ProductReference>PRODUCTSKU1</ProductReference>
<ProductPrices>
<Currency>
<ISO>GBP</ISO>
<Price>15.99</Price>
</Currency>
</ProductPrices>
</Update>
</Product>
</Request>
</Requests>
</AuroraRequestEnvelope>
Example response:
<AuroraResponseEnvolope>
<Summary>
<Ack>OK</Ack>
<RequestsProcessed>1</RequestsProcessed>
<RequestsSucceeded>1</RequestsSucceeded>
<RequestErrors>0</RequestErrors>
</Summary>
</Header>
<Responses>
<Response>
<RequestID>1</RequestID>
<Ack>OK</Ack>
<Data>
<ProductID>261538</ProductID>
<ProductReference>5051741167878</ProductReference>
</Data>
</Response>
</Responses>
</AuroraResponseEnvolope>
Updating Additional Field Data
When updating additional fields in Aurora over the API you can specify to:
- Remove all existing values, using the 'existing="remove"' attribute (see the example below).
- Add your new values into the selection of existing values already in place, but omitting the 'existing="remove"' attribute completely.
- Update the existing value from one value to another by providing the "ValueID" field.
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>
<Update>
<ProductReference>PRODUCTSKU1</ProductReference>
<AdditionalFields existing="remove">
<AdditionalField>
<FieldID>1183</FieldID>
<FieldName>ebay_buy_now_only</FieldName>
<FieldValues>
<FieldValue>
<Value language="en-gb">1</Value>
</FieldValue>
</FieldValues>
<UseAsFilter>0</UseAsFilter>
<DisplayField>0</DisplayField>
</AdditionalField>
</AdditionalFields>
</Update>
</Product>
</Request>
</Requests>
</AuroraRequestEnvelope>
Get
Deferred: Conditional
Products returned by this call are currently always ordered by the date they were last modified. This may change, so you should consider specifying the sort order of your results if this is going to effect your systems performance in the future.
Example Request:
<?xml version="1.0" encoding="utf-8"?>
<AuroraRequestEnvelope>
<Header>
<AuthToken>...</AuthToken>
</Header>
<Requests>
<Request>
<Product>
<Get>
<RequestID>1</RequestID>
<Interval>P1Y</Interval>
<Limit>100</Limit>
<Paging>
<Limit>20</Limit>
<Page>1</Page>
</Paging>
</Get>
</Product>
</Request>
</Requests>
</AuroraRequestEnvelope>
Example response:
<?xml version="1.0" encoding="UTF-8"?>
<AuroraResponseEnvelope>
<Header>
<Version>head</Version>
<Timestamp>2016-09-14T09:52:05+01:00</Timestamp>
<RequestDetails>
<URL>/ajax/Ajax_API/processRequestXml</URL>
</RequestDetails>
<Summary>
<Ack>OK</Ack>
<RequestsProcessed>1</RequestsProcessed>
<RequestsSucceeded>1</RequestsSucceeded>
<RequestErrors>0</RequestErrors>
</Summary>
</Header>
<Responses>
<Response>
<RequestID>1</RequestID>
<Ack>OK</Ack>
<Paging>
<Token>86c526ea28bc09844b33f88c352eb0c69</Token>
</Paging>
<Data>
<Product>
<ProductID>1</ProductID>
<ProductReference>TOIDVD</ProductReference>
<ProductEAN>844665086791</ProductEAN>
<ProductStyleCode>DVD</ProductStyleCode>
<ProductName language="en-gb">Bobbyz</ProductName>
<DisplayProduct>1</DisplayProduct>
<ProductStock>34</ProductStock>
<BinNumber />
<Categories>
<Category>
<ID>1</ID>
<Name>DVDs</Name>
<NamePath>DVDs</NamePath>
<URL>dvds</URL>
</Category>
</Categories>
<ProductCopy language="en-gb"><![CDATA[<p>My selling text goes in here</p>]]></ProductCopy>
<ProductDescription language="en-gb"><![CDATA[<p>The film recreates the ambiance of the era and invokes the hopes inspired by Kennedy through the use of actual newsreel footage of the senator intercut with dramatic sequences involving mostly fictional characters. It uses an ensemble plot device similar to that employed in the 1932 film Grand Hotel, and later used by Robert Altman in Nashville.</p>]]></ProductDescription>
<MetaTitle language="en-gb" />
<GoogleBaseCategory />
<MetaDescription language="en-gb" />
<MetaKeywords language="en-gb" />
<ProductUPC />
<ProductFilename>/dvds/bobby-dvd.html</ProductFilename>
<ProductPrices>
<Currency>
<ISO>GBP</ISO>
<Price>49.99</Price>
<PriceRRP>60.00</PriceRRP>
<PriceWas>0.00</PriceWas>
<PriceBundle>5.00</PriceBundle>
</Currency>
</ProductPrices>
<PriceBuyin>0.00</PriceBuyin>
<ProductSales>57</ProductSales>
<StockControlEnabled>1</StockControlEnabled>
<StockActionOnZero>3</StockActionOnZero>
<StockWarningLevel>0</StockWarningLevel>
<NormalRestockDays>0</NormalRestockDays>
<RestockDate>0000-00-00</RestockDate>
<ShippingMessage language="en-gb" />
<ProductDimensionsWidth>0.0000</ProductDimensionsWidth>
<ProductDimensionsLength>0.0000</ProductDimensionsLength>
<ProductDimensionsHeight>0.0000</ProductDimensionsHeight>
<ProductDimensionsMeasurement />
<ProductWeight>0.0000</ProductWeight>
<ProductWeightMeasurement>grams</ProductWeightMeasurement>
<MinShippingDay>0</MinShippingDay>
<MaxShippingDay>0</MaxShippingDay>
<NoStockMinShippingDay>0</NoStockMinShippingDay>
<NoStockMaxShippingDay>0</NoStockMaxShippingDay>
<ShippingGroups>
<ShippingGroup>
<Name>Default/None</Name>
</ShippingGroup>
</ShippingGroups>
<ShippingRestrictions>
<CountriesExcluded>
<Country>
<ID>31</ID>
<ISO>dk</ISO>
<Name>Denmark</Name>
</Country>
<Country>
<ID>11</ID>
<ISO>fr</ISO>
<Name>France</Name>
</Country>
</CountriesExcluded>
<CountriesIncluded />
<ShippingSKUsExcluded>
<SKU>SKUEurope</SKU>
</ShippingSKUsExcluded>
</ShippingRestrictions>
<TaxRate>20.00</TaxRate>
<TaxBand />
<IsSearchable>1</IsSearchable>
<ProductTemplate>0</ProductTemplate>
<SendToEbay>0</SendToEbay>
<EbayItemID />
<SendToAmazon>0</SendToAmazon>
<Rating>0</Rating>
<AbsoluteRating>0.00</AbsoluteRating>
<ReviewCount>1</ReviewCount>
<AdditionalFields>
<AdditionalField>
<FieldID>1183</FieldID>
<FieldName>ebay_buy_now_only</FieldName>
<FieldValues>
<FieldValue>
<ValueID>31739</ValueID>
<Value language="en-gb">1</Value>
</FieldValue>
</FieldValues>
<UseAsFilter>0</UseAsFilter>
<DisplayField>0</DisplayField>
<FilterAbbreviation />
</AdditionalField>
<AdditionalField>
<FieldID>23</FieldID>
<FieldName>ebay_reserve_price</FieldName>
<FieldValues>
<FieldValue>
<ValueID>31743</ValueID>
<Value language="en-gb">0</Value>
</FieldValue>
</FieldValues>
<UseAsFilter>0</UseAsFilter>
<DisplayField>0</DisplayField>
<FilterAbbreviation />
</AdditionalField>
</AdditionalFields>
<Variations>
<Variation>
<VariationID>64</VariationID>
<VariationReference>TOIDVD_1:3_2:5bedea5f3</VariationReference>
<VariationEAN />
<VariationStyleCode>GROUP1</VariationStyleCode>
<VariationUPC />
<VariationStock>11</VariationStock>
<VariationPrices>
<Currency>
<ISO>GBP</ISO>
<Price>49.99</Price>
<PriceRRP>60.00</PriceRRP>
</Currency>
</VariationPrices>
<VariationPreOrderStock />
<BinNumber />
<VariationTaxRate>20.00</VariationTaxRate>
<VariationTaxBand />
<VariationStockWarningLevel />
<VariationIsLive>1</VariationIsLive>
<VariationWeight>250</VariationWeight>
<VariationWeightMeasurement>grams</VariationWeightMeasurement>
<Attributes>
<Attribute>
<AttributeID>1</AttributeID>
<AttributeName>Colour</AttributeName>
<AttributeValue language="en-gb">White</AttributeValue>
<AttributeValueAbbreviation language="en-gb">white</AttributeValueAbbreviation>
<AttributeValueID>3</AttributeValueID>
<UseAsFilter>1</UseAsFilter>
<DisplayAttribute>1</DisplayAttribute>
<AttributeAbbreviation>colo</AttributeAbbreviation>
<AttributeOrder>8</AttributeOrder>
</Attribute>
</Attributes>
</Variation>
</Variations>
<Images>
<Image>
<Name>bobby.jpg</Name>
<AltText />
<URL>/images/ac_product_images/product_image_data/1</URL>
<Order>1</Order>
</Image>
</Images>
<CrossSells>
<Product>
<ProductID>3228</ProductID>
<Order>2</Order>
</Product>
</CrossSells>
<UpSells>
<Product>
<ProductID>3228</ProductID>
<Order>2</Order>
</Product>
<Product>
<ProductID>3647</ProductID>
<Order>1</Order>
</Product>
</UpSells>
<RelatedProducts>
<Product>
<ProductID>3647</ProductID>
<Order>1</Order>
</Product>
<Product>
<ProductID>3228</ProductID>
<Order>2</Order>
</Product>
</RelatedProducts>
<Bundles>
<Bundle>
<BundleName>Test</BundleName>
<BundlePrice>49.99</BundlePrice>
<BundleAccumulatedPrice>49.99</BundleAccumulatedPrice>
<Order>0</Order>
<Products>
<Product />
</Products>
</Bundle>
</Bundles>
<DateCreated>2010-07-09T12:50:27+01:00</DateCreated>
<DateModified>2016-09-14T09:51:39+01:00</DateModified>
</Product>
</Data>
</Response>
</Responses>
</AuroraResponseEnvelope>
Request Fields
| Field | Values | API Version | Description | Required |
|---|---|---|---|---|
| Interval | String interval | 1.0+ | P indicates the period (required) nY indicates the number of years nM indicates the number of months nD indicates the number of days T indicates the start of a time section (required if you are going to specify hours, minutes, or seconds) nH indicates the number of hours nM indicates the number of minutes nS indicates the number of seconds | Only one of 'Interval' or 'DateStart' is permitted |
| DateStart | yyyy-mm-dd | 1.0+ | Only one of 'Interval' or 'DateStart' is permitted | |
| DateEnd | yyyy-mm-dd | 1.0+ | No | |
| ProductReferences | Container | 1.0+ | Only one of 'ProductReferences' or 'ProductIDs' is permitted | |
| ProductReferences:search | all | products | variations | 1.0+ | Defaulting to "all", this attribute of the "ProductReferences" tag controls whether both the Main Product References and the Variation References should be searched, or just one or the other. | No |
| ProductReferences.ProductReference | String | 1.0+ | Any number of product references can be provided using a separate 'ProductReference' tag for each | Only if 'ProductReferences' is provided |
| ProductEANs | Container | 1.2+ | Only one of 'ProductReferences' or 'ProductIDs' is permitted | |
| ProductEANs.ProductEAN | String | 1.2+ | Any number of product EANs can be provided using a separate 'ProductEAN' tag for each | Only if 'ProductEANs' is provided |
| VariationReferences | Container | 1.0+ | Only one of 'ProductReferences' or 'ProductIDs' is permitted | |
| VariationReferences.**VariationReference** | String | 1.3+ | Any number of variation references can be provided using a separate 'VariationReference' tag for each | Only if 'VariationReferences' is provided |
| ProductIDs | Container | 1.0+ | Only one of 'ProductReferences' or 'ProductIDs' is permitted | |
| ProductIDs.ProductID | Integer > 0 | 1.0+ | Any number of product IDs can be provided using a separate 'ProductID' tag for each | Only if 'ProductIDs' is provided |
| ProductStyleCodes | Container | 1.5+ | No | |
| ProductStyleCodes.ProductStyleCode | String | 1.5+ | Any number of product style codes can be provided using a separate 'ProductStyleCode' tag for each | Only if 'ProductStyleCodes' is provided |
| CategoryIDs | Container | 1.4+ | No | |
| CategoryIDs.CategoryID | Integer > 0 | 1.4+ | Any number of category IDs can be provided using a separate 'CategoryID' tag for each | Only if 'CategoryIDs' is provided |
| AdditionalField | Container | 1.4+ | No | |
| AdditionalField.FieldID | Integer > 0 | 1.4+ | The Aurora ID of the Product Field. | Only if 'AdditionalField' is provide and only one of 'FieldID' or 'FieldValue' is required |
| AdditionalField.FieldName | String | 1.4+ | The name of the product field. Please ensure you keep your field names limited to a finite selection of possibilities, i.e. do not create unique field names for every item, or this will have detrimental impact on the performance of several Aurora services. | Only if 'AdditionalField' is provide and only one of 'FieldID' or 'FieldValue' is required |
| AdditionalField.FieldValues | Container | 1.4+ | Only if 'AdditionalField' is provided | |
| AdditionalField.FieldValues.FieldValue | String | 1.4+ | Any number of field values can be provided using a separate 'FieldValue' tag for each | Only if 'AdditionalField' is provided |
| DisplayProduct | 0 | 1 | 1.4+ | Stipulate that you wish only to see Live products (1) or not (0). By default, both live and non-live products are returned. | No |
| DetailLevel | Full, Language or Minimum Identifiers | 1.4+ | This allows the client to request varying volumes of data when receiving data back from the server.* Full return all product information Language returns only multilingual information * Minimum Identifiers returns only product IDs | No |
| Limit | Integer > 0 | 1.0+ | The number of products to return before beginning to page | No |
| Paging | Container | 1.0+ | No | |
| Paging.Token | String | 1.2+ | This is the Token string issued from any previous OrderGet call featuring paging. Providing this will have the API collect the data from the previously generated set of data, ensuring accurate and consistent dataset results for every page. You cannot change the request properties previously provided when using a Token, so these are ignored by the API. | No |
| Paging.Limit | Integer > 0 | 1.0+ | The number of results to return in the page being requested | No |
| Paging.Page | Integer > 0 | 1.0+ | The page number to return the results for | No |
| OrderBy | String | n/a | This is provided for future use, but currently is not effective | No |
Response fields
| Field | Values | API Version | Description |
|---|---|---|---|
| ProductID | Integer > 0 | 1.0+ | The Internal ID Aurora uses to identify a Product. |
| ProductReference | String | 1.0+ | |
| ProductRetailerCode | String | 1.0-1.4 | This is deprecated and will no longer be available in versions 1.5+ of the Aurora API. |
| ProductStyleCode | String | 1.5+ | This replaces the ProductRetailerCode and facilitates product grouping by style code. |
| ProductName | String | 1.0+ | |
| DisplayProduct | 1 or 0 | 1.0+ | |
| Searchable | 1 or 0 | 1.1+ | This describes whether this product can be found via the 'Search' on the website and whether it features in the category listing pages. |
| ProductStock | Integer | 1.0+ | |
| BinNumber | String | 1.4+ | This is the BIN Number (or Pick Location Reference) assigned to the product. |
| Categories | Container | 1.0+ | |
| Categories.Category | String | 1.0 to 1.2 | |
| Categories.Category | Container | 1.3+ | |
| Categories.Category.ID | ID | 1.3+ | The Internal ID Aurora uses to identify a Product Category. |
| Categories.Category.Name | String | 1.3+ | The name of the category. |
| Categories.Category.NamePath | String | 1.3+ | The name of the category and each of its parents as a pipe delimited string. |
| Categories.Category.URL | String | 1.3+ | The full URL path for the category, as can be used to access the category's product listings on the front-end. |
| MainCategory | String | 1.5+ | The name of the top level main category i.e. Clothing Where the MainCategory element is omitted, empty or invalid, the product main category will be automatically set as the top level category of the first defined category within the Categories list. |
| MainSubcategory | String | 1.5+ | A single pipe (|) separated category path i.e.<br>Clothing | Tshirts<br>Where the MainSubcategory element is omitted, empty or invalid (i.e. the category does not exists in the database or the Categories list) the Main Subcategory will be set to be nothing. |
| ProductCopy | String | 1.0+ | |
| ProductDescription | String | 1.0+ | |
| MetaTitle | String | 1.0+ | |
| GoogleBaseCategory | 1.0+ | ||
| MetaDescription | String | 1.0+ | |
| MetaKeywords | String | 1.0+ | |
| ProductEAN | Alpha-numeric String | 1.0+ | |
| ProductUPC | Alpha-numeric String | 1.0+ | |
| ProductFilename | String | 1.0+ | |
| ProductPrices | Container | 1.0+ | Contains all the details of the product's base prices. |
| ProductPrices.Currency | Container | 1.0+ | Contains all the details for a particular currency. |
| ProductPrices.Currency.ISO | 3 Character String | 1.0+ | |
| ProductPrices.Currency.Price | Float | 1.0+ | |
| ProductPrices.Currency.PriceRRP | Float | 1.0+ | |
| ProductPrices.Currency.PriceWas | Float | 1.0+ | |
| ProductPrices.Currency.PriceBundle | Float | 1.0+ | |
| ProductPriceBuyin | Float | 1.0+ | |
| ProductSales | 1.0+ | ||
| StockControlEnabled | 1 or 0 | 1.0+ | |
| StockActionOnZero | 0 to 3 | 1.0+ | |
| StockWarningLevel | 1.0+ | ||
| NormalRestockDays | Integer | 1.0+ | |
| RestockDate | 1.0+ | ||
| ShippingMessage | String | 1.0+ | |
| ProductDimensionsWidth | Float | 1.0+ | |
| ProductDimensionsLength | Float | 1.0+ | |
| ProductDimensionsHeight | Float | 1.0+ | |
| ProductDimensionsMeasurement | cm or mm or inch or feet | 1.0+ | |
| ProductWeight | Float | 1.0+ | |
| ProductWeightMeasurement | grams or kg or lb | 1.0+ | |
| MinShippingDay | Integer | 1.0+ | |
| MaxShippingDay | Integer | 1.0+ | |
| NoStockMinShippingDay | Integer | 1.0+ | |
| NoStockMaxShippingDay | Integer | 1.0+ | |
| ShippingGroups | Container | 1.4+ | Container for shipping groups |
| ShippingGroups.ShippingGroup | Container | 1.4+ | Container for shipping group |
| ShippingGroups.ShippingGroup.Name | String | 1.4+ | The name of the shipping group |
| ShippingRestrictions | Container | 1.4+ | Container for shipping restrictions |
| ShippingRestrictions.CountriesExcluded | Container | 1.4+ | Container for excluded countries. Please note that the products can not have both included and excluded country restrictions at the same time. |
| ShippingRestrictions.CountriesExcluded.Country | Container | 1.4+ | Container for excluded country |
| ShippingRestrictions.CountriesExcluded.Country.ID | Integer | 1.4+ | The id of the excluded country |
| ShippingRestrictions.CountriesExcluded.Country.ISO | String | 1.4+ | The iso code of the excluded country |
| ShippingRestrictions.CountriesExcluded.Country.Name | String | 1.4+ | The name of the excluded country |
| ShippingRestrictions.CountriesIncluded | Container | 1.4+ | Container for included countries. Please note that the products can not have both included and excluded country restrictions at the same time. |
| ShippingRestrictions.CountriesIncluded.Country | Container | 1.4+ | Container for included country |
| ShippingRestrictions.CountriesIncluded.Country.ID | Integer | 1.4+ | The id of the included country |
| ShippingRestrictions.CountriesIncluded.Country.ISO | String | 1.4+ | The iso code of the included country |
| ShippingRestrictions.CountriesIncluded.Country.Name | String | 1.4+ | The name of the included country |
| ShippingSKUsExcluded | Container | 1.4+ | Container for excluded shipping SKUs |
| ShippingSKUsExcluded.SKU | String | 1.4+ | The name of the shipping SKU |
| TaxRate | 1.0+ | ||
| TaxBand | Restricted String | 1.2+ | |
| AbsoluteRating | Float | 1.3+ | This is the absolute average rating for a product based on all applicable approved reviews. |
| Rating | Restricted String | 1.3+ | This is a string representation of the absolute rating, allowing for simpler representation of a product's rating. It usually will be 1, 2, 3, 4 or 5, however some clients allow 1_5, 2_5, 3_5 and 4_5 also for showing 'half' ratings. It is suggested support for both is considered or discussed with the client before use. |
| ReviewCount | Integer | 1.3+ | This is the number of approved reviews a product has. |
| ProductTemplate | Integer | 1.0+ | The Internal ID Aurora uses to identify a Product Template (Do not use this field unless otherwise agreed) |
| SendToEbay | 1 or 0 | 1.0+ | |
| EbayItemID | Integer | 1.0+ | |
| SendToAmazon | 1 or 0 | 1.0+ | |
| AdditionalFields | Container | 1.0+ | |
| AdditionalFields.AdditionalField | Container | 1.0+ | |
| AdditionalFields.AdditionalField.FieldID | Integer > 0 | 1.0+ | |
| AdditionalFields.AdditionalField.FieldName | String | 1.0+ | Please ensure you keep your field names limited to a finite selection of possibilities, i.e. do not create unique field names for every item, or this will have detrimental impact on the performance of several Aurora services. |
| AdditionalFields.AdditionalField.FieldValues | Container | 1.0+ | |
| AdditionalFields.AdditionalField.FieldValues.FieldValue | String | 1.0+ | |
| AdditionalFields.AdditionalField.UseAsFilter | 1 or 0 | 1.0+ | |
| AdditionalFields.AdditionalField.DisplayField | 1 or 0 | 1.0+ | |
| AdditionalFields.AdditionalField.FilterAbbreviation | 1.0+ | ||
| Variations | Container | 1.0+ | |
| Variations.Variation | Container | 1.0+ | |
| Variations.Variation.VariationReference | String | 1.0+ | |
| Variations.Variation.VariationRetailerCode | String | 1.0-1.4 | This is deprecated and will no longer be available in versions 1.5+ of the Aurora API. |
| Variations.Variation.VariationStyleCode | String | 1.5+ | This replaces the VariationRetailerCode and facilitates variation grouping by style code. |
| Variations.Variation.VariationEAN | Alpha-numeric String | 1.0+ | |
| Variations.Variation.VariationUPC | Alpha-numeric String | 1.0+ | |
| Variations.Variation.VariationStock | Integer | 1.0+ | |
| Variations.Variation.**VariationBinNumber** | String | 1.4+ | This is the BIN Number (or Pick Location Reference) assigned to the variation. Variation BIN Numbers can vary from the value assigned to the master product, but most often do not. |
| Variations.Variation.VariationPrice | Float | 1.0+ | |
| Variations.Variation.VariationPriceRRP | Float | 1.0+ | |
| Variations.Variation.VariationPreOrderStock | Integer | 1.0+ | |
| Variations.Variation.VariationTaxRate | 1.0+ | ||
| Variations.Variation.VariationStockWarningLevel | Integer | 1.0+ | |
| Variations.Variation.VariationIsLive | 1 or 0 | 1.0+ | |
| Variations.Variation.VariationDimensionsWidth | Float | 1.2+ | |
| Variations.Variation.VariationDimensionsLength | Float | 1.2+ | |
| Variations.Variation.VariationDimensionsHeight | Float | 1.2+ | |
| Variations.Variation.VariationDimensionsMeasurement | String | 1.2+ | |
| Variations.Variation.VariationWeight | Float | 1.2+ | |
| Variations.Variation.VariationWeightMeasurement | Restricted String | 1.2+ | |
| Variations.Variation.Attributes | Container | 1.0+ | |
| Variations.Variation.Attributes.Attribute | Container | 1.0+ | |
| Variations.Variation.Attributes.Attribute.AttributeID | Integer > 0 | 1.0+ | The Internal ID Aurora uses to identify an Attribute, e.g. Size or Colour. This can be used when working with the Aurora Basket. |
| Variations.Variation.Attributes.Attribute.AttributeName | String | 1.0+ | |
| Variations.Variation.Attributes.Attribute.AttributeValue | String | 1.0+ | |
| Variations.Variation.Attributes.Attribute.AttributeValueID | Integer > 0 | 1.4+ | The Internal ID Aurora uses to identify an Attribute Value, e.g. UK6 (a size) or Red (a colour). This can be used when working with the Aurora Basket. |
| Variations.Variation.Attributes.Attribute.UseAsFilter | 1 or 0 | 1.0+ | |
| Variations.Variation.Attributes.Attribute.DisplayAttribute | 1 or 0 | 1.0+ | |
| Variations.Variation.Attributes.Attribute.AttributeAbbreviation | String <= 5 Chars | 1.0+ | |
| Variations.Variation.Attributes.Attribute.AttributeOrder | Integer | 1.1+ | This controls the order Attributes are presented to the user on the website when selecting Attributes on the Product Details page. |
Search
Deferred: No
This method is intended for real-time retrieval of product listing results and not data import/export. Please use the ProductGet method to get full product details.
The "ProductSearch" method allows for the retrieval of lists of products according to any category, selection of filters or search-term. The products are returned with a bare minimum of data and are ordered by the Sort Order provided in the request. The order of the products is fully integrated with the Category, Filter Headers and Merchandising Rules systems and will replicate the results returned by the website front-end exactly.
In the example below, the products for the "Men's" category are returned filtered by the Brand (br) "Asolo" where they feature the word "Boot".
Example Request:
<?xml version="1.0" encoding="utf-8"?>
<AuroraRequestEnvelope>
<Header>
<AuthToken>...</AuthToken>
</Header>
<Requests>
<Request>
<Product>
<Search>
<RequestID>1</RequestID>
<Path>/mens/br:asolo/</Path>
<SearchTerm>Boot</SearchTerm>
<LocaleCode>fr-fr</LocaleCode>
<DetailLevel>Minimum</DetailLevel>
<Paging>
<Limit>2</Limit>
<Page>1</Page>
</Paging>
</Search>
</Product>
</Request>
</Requests>
</AuroraRequestEnvelope>
Example Response:
<?xml version="1.0" encoding="utf-8"?>
<AuroraResponseEnvelope>
<Header>
<Summary>
<Ack>OK</Ack>
<RequestsProcessed>1</RequestsProcessed>
<RequestsSucceeded>1</RequestsSucceeded>
<RequestErrors>0</RequestErrors>
</Summary>
</Header>
<Responses>
<Response>
<RequestID>1</RequestID>
<Ack>OK</Ack>
<Data>
<Products>
<Product>
<ProductID>123456</ProductID>
<ProductReference>SKU0001</ProductReference>
</Product>
<Product>
<ProductID>123457</ProductID>
<ProductReference>SKU0002</ProductReference>
</Product>
</Products>
<Categories>
<Category>
<CategoryID>1234</CategoryID>
<CategoryName>Men's Casual</CategoryName>
<Path>/mens/mens-casual/</Path>
<ProductCount>2</ProductCount>
</Category>
<Category>
<CategoryID>1235</CategoryID>
<CategoryName>Men's All-weather</CategoryName>
<Path>/mens/mens-all-weather/</Path>
<ProductCount>1</ProductCount>
</Category>
</Categories>
<Filters>
<Filter>
<FilterName>Size</FilterName>
<Abbreviation>si</Abbreviation>
<Values>
<Value>
<Raw>7</Raw>
<Clean>7</Clean>
<Path>/mens/si:7/</Path>
<ProductCount>2</ProductCount>
</Value>
<Value>
<Raw>8</Raw>
<Clean>8</Clean>
<Path>/mens/si:8/</Path>
<ProductCount>3</ProductCount>
</Value>
<Value>
<Raw>10</Raw>
<Clean>10</Clean>
<Path>/mens/si:10/</Path>
<ProductCount>1</ProductCount>
</Value>
</Values>
</Filter>
<Filter>
<FilterName>Price</FilterName>
<Abbreviation>p</Abbreviation>
<Values>
<Value>
<Raw>100-150</Raw>
<Clean>100-150</Clean>
<Path>/mens/p:100-150/</Path>
<ProductCount>2</ProductCount>
</Value>
<Value>
<Raw>150-200</Raw>
<Clean>150-200</Clean>
<Path>/mens/p:150-200/</Path>
<ProductCount>1</ProductCount>
</Value>
</Values>
</Filter>
<Filter>
<FilterName>Brand</FilterName>
<Abbreviation>br</Abbreviation>
<Values>
<Value>
<Raw>ASOLO</Raw>
<Clean>asolo</Clean>
<Path>/mens/br:asolo/</Path>
<ProductCount>1</ProductCount>
</Value>
<Value>
<Raw>Ben Hill</Raw>
<Clean>ben-hill</Clean>
<Path>/mens/br:ben-hill/</Path>
<ProductCount>2</ProductCount>
</Value>
</Values>
</Filter>
</Filters>
<Paging>
<Page>1</Page>
<TotalProducts>3</TotalProducts>
<IsMore>1</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 its 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 its 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 sanitised (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: -13Severity: 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 over 2 years ago