Overview

This manual covers all features provided by the base Aurora API. If your site or the site you are connecting to has any bespoke features implemented in their version of the Aurora API, instructions for these will not be found here. Please contact your Aurora Account Manager (or the support contact you have been issued at the company in question) for more information.

👍

Get some help from an AI

Why not try out Aurora's new AI Training Packages specifically designed to allow you to train your AI of choice in how to interact with the Aurora APIs.

Get more information here and enjoy gaining insight into how Aurora works instantly!

The Aurora API is an XML interface provided to Aurora Sites to allow third party providers to integrate directly with it. Some of the capabilities of this API include:

• Manage and List:
  • Products
  • Stock
  • Orders
  • Customers
• Activate specific user-related emails

This interface is provided based on a few of the principles of the RESTful systems architecture, to allow optimum balance between reliability for the client's hosting services and a consistent service for the user of the API. The main feature of the architecture to have been adopted is the idea that between requests, the server is able to rest as it sees fit and deal with client requests as resources become available. Because of this, most (but not all, as detailed later in this document) API calls will only give a short prompts reply to a client request to confirm that the request was received and perhaps valid. The client must then wait and check for the reply from the server by way of the response reports. Other companies that have adopted this approach include Amazon and eBay, among many others.

This guide is intended for use by a technical team with the intention of integrating with the Aurora API. Because of this, the reader is assumed to have the following:

• advanced knowledge of PHP or some other form of Web development language (examples may be provided in PHP, but the API should work with any client language)
• a working knowledge of XML and XSD
• a working knowledge of the use of MTOM within XML/SOAP environments
• a working knowledge of the principles of a client/server relationship
• a limited understanding of Aurora's data types

Something to make note of regarding this service is that it has NOT been implemented as a standard SOAP service. For this reason there is no WSDL available for it and requests are best made in client generated XML rather than SOAP requests. This being said, it may be possible to deal with the requests for this service using a standard SOAP client as an effort has been made to use common standards. This service may be moved to a fully integrated SOAP service at some point in the future, but this is not yet the case.

Getting Started

To make use of the API, you must first contact your Aurora Account Manager to ensure that the required set-up procedures have been performed, including Aurora Updates and configuration of the API domain.

Quick example (PHP)

<?php
try {
    $auth_token = '1234567890';
    $request_content = <<<REQUEST
<?xml version="1.0" encoding="utf-8"?>
    <AuroraRequestEnvelope>
        <Header>
            <AuthToken>$auth_token</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>
REQUEST;
    $request_methods = 'ProductGet';
    $api_url = 'https://api.demo.auroracommerce.com/1.5/';
    // test environments usually are under http auth, in this case the $api_url will look like this:
    // $api_url = 'http://http_user:[email protected]/1.5/';
    
    $md5 = base64_encode(md5($request_content, true));

	// curl request
    $curl = curl_init();
    curl_setopt($curl, CURLOPT_URL, $api_url);
    curl_setopt($curl, CURLOPT_POST, 1);
    curl_setopt($curl, CURLOPT_POSTFIELDS, $request_content);
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($curl, CURLOPT_TIMEOUT, 60);
    curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, FALSE);
    curl_setopt($curl, CURLOPT_HTTPHEADER, array(
        "X-AURORA-AUTH-TOKEN: " . $auth_token,
        "X-AURORA-REQUEST-METHODS: " . $request_methods,
        "Transfer-Encoding: chunked",
        "Content-Type: text/xml; charset=utf-8",
        "Content-MD5: {$md5}",
    ));
   
    //the next line will return XML if the response is smaller than 10k characters long and string otherwise
    $response = curl_exec($curl); // more details here: https://docs.auroracommerce.com/display/PUB/Aurora+API+Guide#AuroraAPIGuide-MTOMandCompressedResponses

    // parsing the response
    libxml_use_internal_errors(true); // temporary disable libxml errors
    if(!($responseXml = simplexml_load_string($response))) {
        // enable libxml errors
        libxml_use_internal_errors(false);
        // response is not an xml, most probably its compressed response, let's extract the xml from it because it contains the attachment id
        if(preg_match('#<AuroraResponseEnvelope(?:\s+[^>]+)?>(.*?)</AuroraResponseEnvelope>#s', $response, $matches)) {
            $main_xml_data = str_replace('xop:', '', $matches[0]); // remove this part because it makes the xml data invalid
            $responseXml = new SimpleXMLElement($main_xml_data);
        }
    }
 
	// at this point we should have a SimpleXMLElement object with the response
    if (isset($responseXml->Header) && $responseXml->Header->Summary->Ack == 'OK') { // if the response is valid
        // verify if the response has an attachment, this only happens if the response was big (more than 10k characters)
        foreach($responseXml->Responses->Include as $element) {
			// get the attachment id
            $attachment_id = (string) $element['href']; 
            $attachment_id = str_replace('cid:', '', $attachment_id);
 
            // parse the response to get the encoded attachment
            preg_match('#<'.$attachment_id.'>(.*?)$#s', $response, $matches);
			
			// decode the attachment data and this should return a valid xml string
            $attachment_xml = gzuncompress(base64_decode($matches[1]));
			
			// parse the xml string
            $responseXml = new SimpleXMLElement($attachment_xml);
        }
		
		// print out the response object
        print_r($responseXml);
    }
} catch(Exception $e) {
    echo $e->getMessage();
}

MTOM_Example.pdf

.NET Note

An Aurora partner who has previously implemented the above example using .NET has advised that the standard GZIP libraries within .NET cannot be used to decompress an Aurora API compressed response, instead the ZLib library should be used.

Server Details

Here is an example Aurora API URL:

https://api.demo.auroracommerce.com/1.5/

This URL will connect to version 1.1 of the Aurora API. You should not use the URL given above for your integration, as this is for illustration only. The API URL for your integration can be found on the 'api' sub-domain of the site you are trying to connect to, as shown above for the www.aurorademo.co.uk domain.

You can select which version of the API you wish to connect to by specifying the version number in the URL. While you can switch versions at any time, different versions are only created when backward comparability can no longer be guaranteed, so this should be done with great care. Also, using the 'head' version of the API is not recommended and will not be supported if issues are encountered as this is considered to be unstable and still in development at all times.

The XML data request should be sent as the document body

All API calls are performed over SSL to help ensure maximum security for your data and your credentials.

API Auth Tokens and User Accounts

Once you have the API URL ready and some test requests to run, you will need to get an Auth Token for use as described in the Headers section of this Article. To do this you should contact your API support team or see Aurora API User Management [API User Management] for details regarding how to manage your Aurora API User accounts and Auth Tokens.

Testing Requests

There is a method available to allow you to validate and even run your API requests through the Aurora API from the Aurora Back-end. This interface take your request and the API version you would like to run it against and then returns the results.

This interface can be found in the Users > API Users > Test API section, but should be used responsibly to avoid causing disruption to a Live site.

If you do not provide a URL to submit the request to, then the request will be dealt with by Aurora's internal API interface. This can produce a slightly different behaviour than submitting you requests directly to an API URL, but the data itself will be the same. One such difference is that requests are never DEFERRED when being processed internally.

The username and password requested when providing an API URL are NOT related to your API User Account in any way and simply allow you to provide login details required by some test servers.

❗️

Requests passed over this interface WITHOUT a "API URL" value are run immediately and are not subject to Aurora API's usual load balancing efforts and so should be used responsibly and carefully on Live environments to avoid causing disruption to the site.

Debugging

🚧

This feature requires version 1.5 or higher of the API to be used.

Some methods will return debug information for you to use when trying to see what is going on behind the scenes in the even you run into trouble.

By default this data is not exposed to reduce overheads, as the production of the debug information can reduce performance of the commands involved.

❗️

No guarantees or backward compatible support is offered for this feature or its data. All XML returned can change without warning to accommodate testing and debug information needed as it is needed and so this data should not in any way be incorporated into your regular processes and instead only used for manual debugging when required.

To tell Aurora to include the debug information for your requests, please simply include the debug="1" attribute on your Request tag, as shown below.

<?xml version="1.0" encoding="utf-8"?>
<AuroraRequestEnvelope>
  <Header>
    <AuthToken>...</AuthToken>
  </Header>
  <Requests>
    <Request debug="1">
      <Product>
        <Search>
          <RequestID>1</RequestID>
          <Path>/p:40-100/</Path>
          <ABTestingValue>30</ABTestingValue>
          <DetailLevel>Minimum</DetailLevel>
          <Paging>
            <Limit>4</Limit>
            <Page>1</Page>
          </Paging>
          <OrderBy>8</OrderBy>
        </Search>
      </Product>
    </Request>
  </Requests>
</AuroraRequestEnvelope>

You should expect a response something like this in return.

<?xml version="1.0" encoding="utf-8"?>
<AuroraResponseEnvelope>
  <Header>
    <Version>head</Version>
    <Timestamp>2017-03-22T17:28:14+00:00</Timestamp>
    <RequestDetails></RequestDetails>
    <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>3299</ProductID>
            <ProductReference>TDVD030</ProductReference>
          </Product>
        </Products>
      </Data>
      <Summary>
        <RequestWasRedirected>0</RequestWasRedirected>
      </Summary>
      <Debug>
        <Properties>
          <Property>
            <Name>Is using default Order By?</Name>
            <Value>1</Value>
          </Property>
          <Property>
            <Name>Product Listing Context</Name>
            <Value>
              <AuroraEnvironment>api</AuroraEnvironment>
              <DeviceType>desktop</DeviceType>
              <DateTime>2017-03-22T17:37:11+00:00</DateTime>
              <ChannelType>web</ChannelType>
            </Value>
          </Property>
          <Property>
            <Name>MR Action: tracking_code</Name>
            <Value></Value>
          </Property>
        </Properties>
      </Debug>
    </Response>
  </Responses>
</AuroraResponseEnvelope>

Headers

❗️

The Aurora API does not currently support requests made over HTTP/2.

Please use HTTP/1.1 with uppercase headers.

There is a collection of headers accepted by the Aurora API. These are detailed bellow:

MTOM and gZip Compressed Responses

When a response is larger than 10k characters long, the response will be compressed using gzip compression in an MTOM envelope.

❗️

You will need to decode the MimeType headers and separate the gzip data and the XML response to begin to reassemble the response data.

Example MTOM response:

--MIMEBoundary
content-type: application/xop+xml; charset=UTF-8; type="text/xml";
content-transfer-encoding: binary
content-id: <mtom_xml_main>

<?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>
    <xop:Include href="cid:1337963608_data" />
</Responses>
</AuroraResponseEnvolope>
--MIMEBoundary
content-type: application/xop+xml; charset=UTF-8; type="text/xml";
content-transfer-encoding: binary
content-id: <1337963608_data>

eJyzCUotLsjPK04ttrOBMUGswtLU4hJPFzsDG30Ex8YxOdvO39tGH0TbuCSWJNrZuKWmpgClzG30oSwbfYiEPsI4fYQlAICpJfY=--MIMEBoundary--

As you can see the response is split into two sections, one containing the main XML response and the other the compressed results data. The main XML response section will always have a content ID of 'mtom_xml_main' and always be the first block in the message. The second block will contain the base64 encoded compressed (gziped) XML data.

The '<xop:Include href="cid:1337963608_data" />' tag marks the place where the data should be extracted to, should you wish to do so.
Alternatively, you can decode and process the XML in the compressed section on its own.

🚧

Please be aware that when extracting the data and placing it into the non compressed XML, you must replace the '<xop:Include href="cid:1337963608_data" />' with the decompressed content to prevent having duplicated/nested Responses tags. That is because compressed content is also wrapped in Responses XML tag.

API Call Reference

Request XSD

While our best effort has been made to ensure this document is up to date, you should follow and validate against the following XSD file for all requests to the API. You should treat the XSD as the 'master' where any inconsistencies exist between it and this document.

https://api.demo.auroracommerce.com/head/aurora.xsd

As per previous examples, you should change the host name and version number to that of the site and API to which you are connecting.

Many of the Aurora data services follow the same basic framework:

• Update: Will update or add (if not already present) an item to the database and return a success report.
• Get: Will fetch data regarding one or many items, this service is also often paged for large data-sets and may use (and allow the use of in requests) MTOM for large data-sets, but this will be specified where it is applicable on the documents below.

Request Tracking

This refers to the tracking of individual data items and their progress through the API. This is currently only implemented on some Get API methods, like the OrderGet method. This allows the API to track the items it sends and then not send them again if not required. This is particularly useful for Orders, where only newly placed orders may be required.

The tracking is controlled per API User, so the marking of an item by one user does not effect the availability of that item to other API users.

Where this it implemented, the 'tracking' attribute of the Method tag can be used to instruct Aurora to mark the data it is sending as 'sent'. Aurora can then be prevented from sending this data to again by providing the 'Tracking' tag in the requests. The 'Tracking' tag accepts one of these values:

• sent - returns only items marked as not previously sent
• unsent - returns only items marked as previously sent
• changed - returns only items marked as not previously sent or items which has changed

If the 'Tracking' tag is not provided at all, then Aurora will ignore any tracking restrictions.

Please see an example OrderGet request with tracking enabled. This request will only return orders from the past day that have not previously been sent and will record the ones it does send for future reference.

 <AuroraRequestEnvelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
     <Header>
         <AuthToken>...</AuthToken>
     </Header>
     <Requests>
         <Request>
             <Order>
                 <Get tracking="automatic">
                     <RequestID>1</RequestID>
                     <Interval>P1D</Interval>
                     <Tracking>unsent</Tracking>
                 </Get>
             </Order>
         </Request>
     </Requests>
 </AuroraRequestEnvelope>

Detail Levels

Some methods allow the use of the 'DetailLevel' element. This allows the client to request varying volumes of data when receiving data back from the server. If this can be used with a method, it will be clearly described in the 'Request fields' section of the related documentation.

When 'DetailLevel' is permitted, the 'Request fields' will be described along with a 'Detail Levels' column, that will describe at what level or levels each individual field will appear. This column can be described as:

• a single level, e.g. 'Full', meaning it will only appear in that one specific level and no others.
• a comma delimited list of levels, e.g. 'Reduced, Full', meaning it will appear in each of these level but no others.
• a level followed by a '+' sign, e.g. 'Minimum +', meaning the field will appear in this level and all others of a greater detail level.

The levels and their relative order are described below (from least to most data):

1. Minimum
2. Language
3. Full

Paging

Where paging is supported (which is currently only in some 'Get' methods) the results of the request can be fetched in batches of up to 200 results per 'page'. When this is done, the API issues a Pagination Token back to the client to be used for all subsequent page requests. Making use of this Pagination Token ensures that all data returned in the result-set is always represented on the page it was found in when the request was originally made. For example, if you make a request ordered by the date a product was last modified and collect the first page 5 times over an hour, the same products will always be returned for that page for the Token issued with the original request, even if the date modified field is updated in the mean time.

If a Pagination Token is not given, then the result set is fetched anew.

❗️

It is very important that you consider using the API Paging Tokens when making large requests as this ensures the results you receive are consistent.

If you do not use the Token, then the request is generated anew with every page you request and could lead to new items appearing in your results between the first page and any subsequent page request and so produce unwanted results (e.g. data being included multiple time across different pages of data).

Think of this as 'live' vs 'cached' results. The Paging Token allows you to get the results as they were when you made your initial request for data while leaving the token out will give you the results as they are right now (including any newly created results).

If the 'Paging' system is not made use of in the request, then no Pagination Token is generated or returned, just a full set of results (where this does not trigger a Deferred request).

Example Request (original):

 <?xml version="1.0" encoding="utf-8"?>
 <AuroraRequestEnvelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
     <Header>
         <AuthToken>...</AuthToken>
     </Header>
     <Requests>
         <Request>
             <Product>
                 <Get>
                     <Interval>P1Y</Interval>
                     <Paging>
                         <Limit>20</Limit>
                         <Page>1</Page>
                     </Paging>
                 </Get>
             </Product>
         </Request>
     </Requests>
 </AuroraRequestEnvelope>

Example Response:

<AuroraResponseEnvolope>
    <Header>
        <Summary>
            <Ack>OK</Ack>
            <RequestsProcessed>0</RequestsProcessed>
            <RequestsSucceeded>0</RequestsSucceeded>
            <RequestErrors>0</RequestErrors>
        </Summary>
    </Header>
    <Responses>
        <Response>
            <RequestID>0</RequestID>
            <Ack>OK</Ack>
            <Paging>
                <Token>aaaaaaaaaaaaaaaaaaaaaaaaaa</Token>
            </Paging>
            <Data>
                <Product>...</Product>
            </Data>
        </Summary>
    </Responses>
</AuroraResponseEnvolope>

Example Request (with Token): Version 1.2+ only

 <?xml version="1.0" encoding="utf-8"?>
 <AuroraRequestEnvelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
     <Header>
         <AuthToken>...</AuthToken>
     </Header>
     <Requests>
         <Request>
             <Product>
                 <Get>
                     <Paging>
                         <Token>aaaaaaaaaaaaaaaaaaaaaaaaaa</Token>
                         <Limit>20</Limit>
                         <Page>2</Page>
                     </Paging>
                 </Get>
             </Product>
         </Request>
     </Requests>
 </AuroraRequestEnvelope>

🚧

Notice that there is no need to provide the filter elements ('Interval' in these examples) when fetching a result-set by Pagination Token. The reason for this is that the query has already been resolved and so the results already decided. If you do provide any filters the API will ignore them and issue a warning to this effect, though this bears no ill effect on the results returned and so can be ignored if desired.

Deferred Requests

As a RESTful API, requests may often be deferred by the server to prevent server load from becoming unmanageable. Certain methods will always be deferred (normally where time is not a factor) while others will simply allow the option.

If your request is not time sensitive, then you should consider deferring it using the 'X-AURORA-FORCE-DEFFERAL' header. This will allow the server to better balance its load and avoid risking time-outs due to lengthy waiting times for your request scripts.

When a request is made and deferred, this means the server has saved the request to then be processed at a later date. Under normal load, this should take no longer than a few minutes to complete. When a request is deferred, you will notice that the request summary will return 0 (zero) in the 'RequestsProcessed' field to let you know and there will be a Feed ID returned for you to record and use to fetch the results later.

Example Response:

 <AuroraResponseEnvolope>
     <Header>
         <Summary>
             <Ack>OK</Ack>
             <RequestsProcessed>0</RequestsProcessed>
             <RequestsSucceeded>0</RequestsSucceeded>
             <RequestErrors>0</RequestErrors>
         </Summary>
     </Header>
     <Responses>
         <Response>
             <RequestID>0</RequestID>
             <Ack>OK</Ack>
             <Data>
                 <FeedID>...</FeedID>
             </Data>
         </Summary>
     </Responses>
</AuroraResponseEnvolope>

As described, some methods may always be deferred, while other are only deferred under certain circumstances, such as large and unlimited queries for product data under version 1.2+ of the API. Such requests are deferred to prevent load issues. To find out if or when a method is deferred, you can refer to the documentation for the method in question and see this detailed at the top of each method section.

To check on the status of your deferred requests you must use the 'DeferredGet' method as described below.

Get

Deferred: No

This method accepts one field named 'FeedID'. If this field is present, then the results for this request are returned, otherwise a list of all recent requests (by their Feed ID) are returned for you to process.

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>
             <Deferred>
                 <Get>
                     <FeedID>...</FeedID>
                 </Get>
             </Deferred>
         </Request>
     </Requests>
 </AuroraRequestEnvelope>

F.A.Q.

Q: Why am I getting the 'Unrecognised Method Requested' error when my XML is correct?

A: This normally happens if you are not specifying the X-AURORA-REQUEST-METHODS header correctly.

Q: Do all products have both an ID and a reference/SKU? What’s the difference?

A: The ID is the absolute unique number issued to the product/variation by the internal Aurora systems, whereas the Reference is a code set by the website owner to represent the product (normally this is a SKU, but this is entirely down to the website owner).

Q: My request is not returning any data, why?

A: The two most common procedures to follow here are as follows:

1. Have you been issued a FeedID in the response? If you have, then your request has been deferred and you should use the DeferredGet method described in this support article to get your full response.
2. What errors have been sent to you in the request? Aurora will make an effort to tell you what is wrong when a request fails and so quite often, you can quickly tell what elements of your request Aurora did not like and even get a hint as to what it was expecting in its place.