Guide
Start typing to search…

Aurora API: Order

Order

Using this controller you can add, edit and retrieve all order information. This includes updating order payment transactions, addresses and all other order related values. You may also reserve Order IDs to later pass into the OrderAdd method using the OrderGenerateID method. This can be useful for use with Payment Processing attempts done before order placement but requiring an order reference/ID.

Generate ID

This method allows for the reservation of Order IDs in Aurora for later use when creating orders using the OrderAdd method. The IDs cannot be specified by the client as Aurora must maintain control over its internal IDs and once 'reserved' they cannot be released.

To request a new and Unique ID from Aurora for an order, please see the example requests and response samples below.

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>
      <Order>
        <Generate>
          <ID>
            <RequestID>1</RequestID>
          </ID>
        </Generate>
      </Order>
    </Request>
  </Requests>
</AuroraRequestEnvelope>

Example response:

<?xml version="1.0" encoding="utf-8"?>
<AuroraResponseEnvelope>
    <Header>
        <Version>1.4</Version>
        <Timestamp>2014-09-10T13:59:57+01: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>
                <OrderID>1000000</OrderID>
            </Data>
        </Response>
    </Responses>
</AuroraResponseEnvelope>

Add

Deferred: No

🚧

When adding an order using the Order Add API method, Aurora can be set to perform validations against ordered items:

  • Are all of the products live?
  • Do all of the products/variations have sufficient stock?

This validation will be disabled by default, so the Order Add API process will run as before. It will be possible to enable this validation in Aurora backend UI > Store > Settings > Aurora > API Settings.

This validation will be performed before order creation, so if any validation fails against any ordered item, the Order Add API process will be stopped, and an error message returned in the API response identifying the reason. Possible error messages include:

  • Product [id] is not live and can not be purchased
  • Product [id] does not have sufficient stock. Requested [quantity], available [available]
  • Variation [variation id] of a product [product id] is not live and can not be purchased
  • Variation [variation id] of a product [product id] does not have sufficient stock. Requested [quantity], available [available]

When adding an order, the 'send_confirmation' attribute can be used to denote whether or not an automatic confirmation email should be sent for the order. The email sent will be generated from the usual Aurora email templates for Order Confirmation.

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>
             <Order>
                 <Add send_confirmation="yes">
                     <CustomerID>120575</CustomerID>
                     <OrderStatus>Despatched</OrderStatus>
                     <PaymentType>card</PaymentType>
                     <Addresses>
                         <Address>
                             <CustomerID>120575</CustomerID>
                             <StorageType>I</StorageType>
                             <AddressType>BT</AddressType>
                             <EmailAddress>[email protected]</EmailAddress>
                             <OptOut>0</OptOut>
                             <Gender>male</Gender>
                             <CompanyName></CompanyName>
                             <FirstName>John</FirstName>
                             <LastName>Doe</LastName>
                             <AddressLine1>25 Street</AddressLine1>
                             <AddressLine2>Place</AddressLine2>
                             <Town>Town</Town>
                             <County>County</County>
                             <PostCode>WN7 1TX</PostCode>
                             <Country>United Kingdom</Country>
                             <PhoneNumber>0101010101</PhoneNumber>
                             <MobileNumber>0202020202</MobileNumber>
                         </Address>
                         <Address>
                             <CustomerID>120575</CustomerID>
                             <StorageType>I</StorageType>
                             <AddressType>ST</AddressType>
                             <EmailAddress>[email protected]</EmailAddress>
                             <OptOut>0</OptOut>
                             <Gender>male</Gender>
                             <CompanyName></CompanyName>
                             <FirstName>John</FirstName>
                             <LastName>Doe</LastName>
                             <StoreReference>STO1</StoreReference>
                         </Address>
                     </Addresses>
                     <CourierName>Royal Mail</CourierName>
                     <TrackingNumber></TrackingNumber>
                     <Currency>GBP</Currency>
                     <TaxRate>20.00</TaxRate>
                     <ShippingSku>6001008727</ShippingSku>
                     <ShippingCost>0.00</ShippingCost>
                     <ShippingTax>0</ShippingTax>
                     <CustomShippingCost>0</CustomShippingCost>
                     <CustomShippingLabel></CustomShippingLabel>
                     <OrderTotal>89.95</OrderTotal>
                     <OrderSubtotal>86.97</OrderSubtotal>
                     <OrderTax>2.98</OrderTax>
                     <CouponCode>10OFF</CouponCode>
                     <CouponDiscount>10.00</CouponDiscount>
                     <OrderDiscount>0.00</OrderDiscount>
                     <PriceBreakDiscount>0</PriceBreakDiscount>
                     <LoyaltyDiscount>0.00</LoyaltyDiscount>
                     <TotalDiscount>10.00</TotalDiscount>
                     <InvoiceNotes></InvoiceNotes>
                     <CustomerNotes></CustomerNotes>
                     <DateDeliveryEstimate>2012-11-09T16:56:47+01:00</DateDeliveryEstimate>
                     <DateShipped>2012-11-09T16:56:47+01:00</DateShipped>
                     <DateCreated>2009-04-04T16:56:47+01:00</DateCreated>
                     <Items>
                         <Item>
                             <VariationReference>SKU123</VariationReference>
                             <BundleID></BundleID>
                             <Price>12.01</Price>
                             <Tax>2.98</Tax>
                             <Discount>2.98</Discount>
                             <TaxRate>20.00</TaxRate>
                             <Quantity>1</Quantity>
                             <QuantityReturned>0</QuantityReturned>
                             <LineOrder>1</LineOrder>
                             <LineStatus>
                                 <StatusCode>DES</StatusCode>
                             </LineStatus>
						 </Item>
                         <Item>
                             <VariationReference>SKU234</VariationReference>
                             <BundleID></BundleID>
                             <Price>10.99</Price>
                             <Tax>0.00</Tax>
                             <Discount>1.23</Discount>
                             <TaxRate>0.00</TaxRate>
                             <Quantity>2</Quantity>
                             <QuantityReturned>0</QuantityReturned>
                             <LineOrder>2</LineOrder>
                             <LineStatus>
                                 <Quantity>1</Quantity>
                                 <StatusCode>CAN</StatusCode>
                                 <ReasonCode>Customer Cancellation</ReasonCode>
                             </LineStatus>
							 <DiscountList>
                                <DiscountItem>
                                    <Type>
                                        <BasketPromotion>
                                            <Id>1</Id>
                                        </BasketPromotion>
                                    </Type>
                                    <DiscountAmount>1.23</DiscountAmount>
                                </DiscountItem>
                            </DiscountList>
						 </Item>
                         <Item>
                             <VariationReference>SKU345</VariationReference>
                             <BundleID></BundleID>
                             <Price>26.99</Price>
                             <Tax>0.00</Tax>
                             <Discount>0.46</Discount>
                             <TaxRate>0.00</TaxRate>
                             <Quantity>1</Quantity>
                             <QuantityReturned>0</QuantityReturned>
                             <LineOrder>3</LineOrder>
							 <DiscountList>
                                <DiscountItem>
                                    <Type>
                                        <BasketPromotion>
                                            <PromotionName>ABC</PromotionName>
                                        </BasketPromotion>
                                    </Type>
                                    <DiscountAmount>0.12</DiscountAmount>
									<DiscountNumber>1</DiscountNumber>
                                    <PromotionAmount>20</PromotionAmount>
									<PromotionAmountType>percent</PromotionAmountType>
                                </DiscountItem>
								<DiscountItem>
                                    <Type>
                                        <BasketPromotion>
                                            <Id>34</Id>
                                        </BasketPromotion>
                                    </Type>
                                    <DiscountAmount>0.34</DiscountAmount>
									<DiscountNumber>2</DiscountNumber>
                                </DiscountItem>
                            </DiscountList>
						 </Item>
                     </Items>
                     <Transactions>
                         <Transaction>
                             <Amount>79.95</Amount>
                             <Display>1</Display>
                             <NameOnCard>Thomas Cahalan</NameOnCard>
                             <CardNumber>0006</CardNumber>
                             <CardExpiry>0515</CardExpiry>
                             <CardType>VISA</CardType>
                             <Type>PAYMENT</Type>
                             <Status>OK</Status>
                             <StatusDetails>0000 : The Authorisation was Successful.</StatusDetails>
                             <Provider>SagePay</Provider>
                             <ProviderVendorName>verndorname</ProviderVendorName>
                             <ProviderVendorTxCode>123456-12345678900000000000</ProviderVendorTxCode>
                             <ProviderTxID>{C1E34116-47A2-996D-A23B-D132F38E695B}</ProviderTxID>
                             <ProviderSecurityKey>ABCDEFGHIJ</ProviderSecurityKey>
                             <ProviderAuthNumber>1234567</ProviderAuthNumber>
                             <ProviderAddressResult>NOTCHECKED</ProviderAddressResult>
                             <ProviderPostCodeResult>NOTCHECKED</ProviderPostCodeResult>
                             <ProviderCV2Result>NOTCHECKED</ProviderCV2Result>
                             <Provider3DSecureStatus>NOTCHECKED</Provider3DSecureStatus>
                             <DateCreated>2009-04-04T16:58:47+01:00</DateCreated>
                     		 <TransactionAdditionalFields>
								 <TransactionAdditionalField>
								 	<FieldID>123</FieldID>
								 	<FieldValue>Additional Transaction Information</FieldValue>
								 </TransactionAdditionalField>
                     		 </TransactionAdditionalFields>
                         </Transaction>
                     </Transactions>
                     <AdditionalFields>
                         <AdditionalField>
                             <FieldID>39</FieldID>
                             <FieldValue>Warehouse Pallet 2</FieldValue>
                         </AdditionalField>
                         <AdditionalField>
                             <FieldName>New Field</FieldName>
                             <FieldValue>123567</FieldValue>
                         </AdditionalField>
                     </AdditionalFields>
                 </Add>
             </Order>
         </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>
                 <OrderID>695434</OrderID>
                 <Addresses>
                     <Address>
                         <AddressID>1339859</AddressID>
                         <AddressType>BT</AddressType>
                     </Address><Address>
                         <AddressID>1339860</AddressID>
                         <AddressType>ST</AddressType>
                     </Address>
                 </Addresses>
                 <Items>
                     <Item>
                         <ItemID>480237</ItemID>
                         <LineOrder>0</LineOrder>
                     </Item>
                     <Item>
                         <ItemID>480238</ItemID>
                         <LineOrder>0</LineOrder>
                     </Item>
                     <Item>
                         <ItemID>480239</ItemID>
                         <LineOrder>0</LineOrder>
                     </Item>
                 </Items>
                 <Transactions>
                     <Transaction>
                         <TransactionID>123456</TransactionID>
                     </Transaction>
                 </Transactions>
             </Data>
         </Response>
     </Responses>
</AuroraResponseEnvelope>

Add 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 OrderGet method.

Field

Values

API Version

Description

Required

send_confirmation

yes or no

1.1+

When set to yes, an email notification will be sent to the customer where the order status has changed and the specified order status is a despatched status or has a configured email template. Where the order status is despatched, an email notification will only be sent if the customer has not previously received a despatch email.

No

recalculate_order_totals

yes or no

1.4+

When set to yes, the Order Total, Tax and Subtotals are automatically updated in accordance with changes made to the items, e.g. if you cancel an item, the new totals are set with this in mind.

By default and if you set "no", the system assumes you ahve reason not to change the totals at this time and will only play what you explicitly tell it to iun your request.

No

tracking

none or sent

1.4+

This is an attribute on the top level method element (i.e. <Add tracking="sent"> or <Update tracking="sent">) that can be used to explicitly set an order as sent.

No

OrderID

Integer

1.4+

This must be a valid, unused Order ID obtained by way of the OrderGenerateID API method. If any other Integer figure is provided that was not generated in this way by the same API user account (Access Token) then the entire request will be rejected.

No

Addresses

Container

1.0+

This contains all of the addresses pertaining to an order. This will normally include a billing and a shipping address.

No

Addresses.Address

Container

1.0+

This contains all of the fields pertaining to an individual address.

No

Addresses.Address.CustomerID

Integer

1.0+

The Internal ID Aurora uses to identify Users or Customers of the site.

No

Addresses.Address.StorageType

I or U

1.0+

This describes whether an address is an Order Address or a User/Customer Address. User/Customer addresses are addresses that have been saved to a Customers account for convenience and can be removed by the customer while Order Addresses are assigned specifically to Orders made and cannot be removed.

Addresses.Address.AddressType

BT or ST

1.0+

Describes whether an address is for Billing (BT) or Shipping (ST).

Addresses.Address.EmailAddress

String

1.0+

Addresses.Address.OptOut

1 or 0

1.0+

Is used by some mailing and reporting systems to control whether or not the address is used in mail-shots and marketing campaigns.

Addresses.Address.Gender

male or female

1.0+

Addresses.Address.CompanyName

String

1.0+

Addresses.Address.Title

Restricted String

1.0+

The is the User/Customer title, e.g. Mr, Mrs, etc.

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

Addresses.Address.FirstName

String

1.0+

Addresses.Address.LastName

String

1.0+

Addresses.Address.StoreReference

String

1.1+

The internal Store ID/Reference assigned to the store in the Aurora Back-end > Shipping > Stores section. This can be used in place of the customer address details where a product is to be a) shipped to the store for collection or b) no billing address is required as the payment was taken as cash in-store.

If present, the following fields should be omitted: AddressLine1, AddressLine2, Town, County, PostCode, Country

Addresses.Address.AddressLine1

String

1.0+

This field should not be provided where a StoreReference is present.

Addresses.Address.AddressLine2

String

1.0+

This field should not be provided where a StoreReference is present.

Addresses.Address.Town

String

1.0+

This field should not be provided where a StoreReference is present.

Addresses.Address.County

String

1.0+

This field should not be provided where a StoreReference is present.

Addresses.Address.PostCode

String

1.0+

This field should not be provided where a StoreReference is present.

Addresses.Address.Country

Restricted String

1.0+

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

This field should not be provided where a StoreReference is present.

Addresses.Address.PhoneNumber

String

1.0+

Addresses.Address.MobileNumber

String

1.0+

Transactions.Transaction.IsTest

yes or no

1.1+

If the transaction being recorded was placed on a Test environment, then this should be "yes". Otherwise it should be "no".

No

Update

Deferred: No

The 'Update' call is almost identical to the 'Add' call with the only real difference being that most of the fields are now optional. While adding a new order requires that you provide all necessary information at once, when using the 'Update' method, you can just provide the information you wish to change and leave out all of the rest (excluding the relevant ID fields such as OrderID of course which are used to identify the records to be updated).

One example of this would be to change the email address on an address, you would only need to provide the Order ID, Address ID and Address Email fields and all other data can be omitted. The same is true for adding additional items and transactions to an order. Simply provide the Order ID and the relevant data structures for the items or transactions and they will be appended to the order.

When updating an order, the 'send_confirmation' attribute can be used to denote whether or not an automatic confirmation email should be sent for the order update. The email sent will be generated based on the email notification settings defined within the target order status.

When updating an order, the 'recalculate_order_totals' attribute can be used to denote whether or not Aurora should re-calculate the order totals (Value, Tax and Subtotal) when processing your request. You can override any one or all of these values by providing the values you would like to use in your request, e.g. if you set 'recalculate_order_totals=yes' but provide OrderTotal=20, then 20 will be used regardless of what Aurora considers during its calculations.

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>
             <Order>
                 <Update send_confirmation="no" recalculate_order_totals="no">
                     <OrderID>120575</OrderID>
                     <OrderStatus>Despatched</OrderStatus>
                     <PaymentType>card</PaymentType>
                     <Addresses>
                         <Address>
                             <CustomerID>120575</CustomerID>
                             <StorageType>I</StorageType>
                             <AddressType>BT</AddressType>
                             <EmailAddress>[email protected]</EmailAddress>
                             <OptOut>0</OptOut>
                             <Gender>male</Gender>
                             <CompanyName></CompanyName>
                             <FirstName>John</FirstName>
                             <LastName>Doe</LastName>
                             <AddressLine1>25 Street</AddressLine1>
                             <AddressLine2>Place</AddressLine2>
                             <Town>Town</Town>
                             <County>County</County>
                             <PostCode>WN7 1TX</PostCode>
                             <Country>United Kingdom</Country>
                             <PhoneNumber>0101010101</PhoneNumber>
                             <MobileNumber>0202020202</MobileNumber>
                         </Address>
                         <Address>
                             <CustomerID>120575</CustomerID>
                             <StorageType>I</StorageType>
                             <AddressType>ST</AddressType>
                             <EmailAddress>[email protected]</EmailAddress>
                             <OptOut>0</OptOut>
                             <Gender>male</Gender>
                             <CompanyName></CompanyName>
                             <FirstName>John</FirstName>
                             <LastName>Doe</LastName>
                             <StoreID>STO1</StoreID>
                         </Address>
                     </Addresses>
                     <CourierName>Royal Mail</CourierName>
                     <TrackingNumber></TrackingNumber>
                     <Currency>GBP</Currency>
                     <TaxRate>20.00</TaxRate>
                     <ShippingSku>6001008727</ShippingSku>
                     <ShippingCost>0.00</ShippingCost>
                     <ShippingTax>0</ShippingTax>
                     <CustomShippingCost>0</CustomShippingCost>
                     <CustomShippingLabel></CustomShippingLabel>
                     <OrderTotal>89.95</OrderTotal>
                     <OrderSubtotal>86.97</OrderSubtotal>
                     <OrderTax>2.98</OrderTax>
                     <CouponCode>10OFF</CouponCode>
                     <CouponDiscount>10.00</CouponDiscount>
                     <OrderDiscount>0.00</OrderDiscount>
                     <PriceBreakDiscount>0</PriceBreakDiscount>
                     <LoyaltyDiscount>0.00</LoyaltyDiscount>
                     <TotalDiscount>10.00</TotalDiscount>
                     <InvoiceNotes></InvoiceNotes>
                     <CustomerNotes></CustomerNotes>
                     <DateDeliveryEstimate>2012-11-09T16:56:47+01:00</DateDeliveryEstimate>
                     <DateShipped>2012-11-09T16:56:47+01:00</DateShipped>
                     <Items>
                         <Item>
                             <VariationReference>SKU123</VariationReference>
                             <BundleID></BundleID>
                             <Price>12.01</Price>
                             <Tax>2.98</Tax>
                             <Discount>2.98</Discount>
                             <TaxRate>20.00</TaxRate>
                             <Quantity>1</Quantity>
                             <QuantityReturned>0</QuantityReturned>
                             <LineOrder>1</LineOrder>
                             <LineStatus>
                                 <StatusCode>ACK</StatusCode>
                             </LineStatus>
                         </Item>
                         <Item>
                             <VariationReference>SKU234</VariationReference>
                             <BundleID></BundleID>
                             <Price>10.99</Price>
                             <Tax>0.00</Tax>
                             <Discount>0.00</Discount>
                             <TaxRate>0.00</TaxRate>
                             <Quantity>1</Quantity>
                             <QuantityReturned>0</QuantityReturned>
                             <LineOrder>2</LineOrder>
                             <LineStatus>
                                 <StatusCode>ACK</StatusCode>
                             </LineStatus>
							 <DiscountList>
                                <DiscountItem>
                                    <Type>
                                        <BasketPromotion>
                                            <PromotionName>ABC</PromotionName>
                                        </BasketPromotion>
                                    </Type>
                                    <DiscountAmount>0.12</DiscountAmount>
									<DiscountNumber>1</DiscountNumber>
                                    <PromotionAmount>20</PromotionAmount>
									<PromotionAmountType>percent</PromotionAmountType>
                                </DiscountItem>
                            </DiscountList>
                         </Item>
                         <Item>
                             <VariationReference>SKU345</VariationReference>
                             <BundleID></BundleID>
                             <Price>26.99</Price>
                             <Tax>0.00</Tax>
                             <Discount>0.00</Discount>
                             <TaxRate>0.00</TaxRate>
                             <Quantity>1</Quantity>
                             <QuantityReturned>0</QuantityReturned>
                             <LineOrder>3</LineOrder>
                             <LineStatus>
                                 <Quantity>1</Quantity>
                                 <StatusCode>CAN</StatusCode>
                                 <ReasonCode>Supplier Cancellation</ReasonCode>
                             </LineStatus>
                         </Item>
                     </Items>
                     <Transactions>
                         <Transaction>
                             <TransactionID>12345</TransactionID>
                             <Display>1</Display>
                             <Status>OK</Status>
                             <StatusDetails>0000 : The Authorisation was Successful.</StatusDetails>
                             <ProviderVendorName>verndorname</ProviderVendorName>
                             <ProviderVendorTxCode>123456-12345678900000000000</ProviderVendorTxCode>
                             <ProviderTxID>{C1E34116-47A2-996D-A23B-D132F38E695B}</ProviderTxID>
                             <ProviderSecurityKey>ABCDEFGHIJ</ProviderSecurityKey>
                             <ProviderAuthNumber>1234567</ProviderAuthNumber>
                             <ProviderAddressResult>NOTCHECKED</ProviderAddressResult>
                             <ProviderPostCodeResult>NOTCHECKED</ProviderPostCodeResult>
                             <ProviderCV2Result>NOTCHECKED</ProviderCV2Result>
                             <Provider3DSecureStatus>NOTCHECKED</Provider3DSecureStatus>
                     		 <TransactionAdditionalFields existing="remove">
								 <TransactionAdditionalField>
								 	<FieldID>123</FieldID>
								 	<FieldValue>Additional Transaction Information</FieldValue>
								 </TransactionAdditionalField>
                     		 </TransactionAdditionalFields>
                         </Transaction>
                     </Transactions>
                     <AdditionalFields existing="remove">
                         <AdditionalField>
                             <FieldID>39</FieldID>
                             <FieldValue>Warehouse Pallet 2</FieldValue>
                         </AdditionalField>
                         <AdditionalField>
                             <FieldName>New Field</FieldName>
                             <FieldValue>123567</FieldValue>
                         </AdditionalField>
                     </AdditionalFields>
                 </Update>
             </Order>
         </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>
     <Responses>
         <Response>
             <RequestID>1</RequestID>
             <Ack>OK</Ack>
             <Data>
                 <OrderID>695434</OrderID>
                 <Addresses>
                     <Address>
                         <AddressID>1339859</AddressID>
                         <AddressType>BT</AddressType>
                     </Address><Address>
                         <AddressID>1339860</AddressID>
                         <AddressType>ST</AddressType>
                     </Address>
                 </Addresses>
                 <Items>
                     <Item>
                         <ItemID>480237</ItemID>
                         <LineOrder>0</LineOrder>
                     </Item>
                     <Item>
                         <ItemID>480238</ItemID>
                         <LineOrder>0</LineOrder>
                     </Item>
                     <Item>
                         <ItemID>480239</ItemID>
                         <LineOrder>0</LineOrder>
                         <RelatedItems>
                           <Item>
                             <ItemID>2549876</ItemID>
                             <LineOrder>2</LineOrder>
                           </Item>
                         </RelatedItems>
                     </Item>
                 </Items>
                 <Transactions>
                     <Transaction>
                         <TransactionID>12345</TransactionID>
                     </Transaction>
                 </Transactions>
             </Data>
         </Response>
     </Responses>
</AuroraResponseEnvelope>

Update 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 OrderGet method.

Field

Values

API Version

Description

Required

send_confirmation

yes or no

1.1+

When set to yes, an email notification will be sent to the customer where the order status has changed and the specified order status is a despatched status or has a configured email template. Where the order status is despatched, an email notification will only be sent if the customer has not previously received a despatch email.

Default: no

recalculate_order_totals

yes or no

1.4+

When set to yes, the Order Total, Tax and Subtotals are automatically updated in accordance with changes made to the items, e.g. if you cancel an item, the new totals are set with this in mind.

By default and if you set "no", the system assumes you ahve reason not to change the totals at this time and will only play what you explicitly tell it to iun your request.

Default: no

force_confirmation

yes or no

1.5+

When set to yes, an email notification will always been sent, providing the order status is either a despatched status or has a configured email template.

Default: no

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 an order as sent

No

Get

Deferred: Conditional

🚧

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

Orders returned by this call are currently always ordered by the date they were placed. 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 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
         <Header>
                 <AuthToken>...</AuthToken>
         </Header>
         <Requests>
                 <Request>
                         <Order>
                                 <Get tracking="automatic|none">
                                         <RequestID>1</RequestID>
                                         <Interval>P1Y</Interval>
                                         <OrderStatuses>
                                                 <StatusID>2</StatusID>
                                         </OrderStatuses>
                                         <PaymentType condition="is|not">PayPal</PaymentType>
                                         <Limit>100</Limit>
                                         <Paging>
                                                 <Limit>20</Limit>
                                                 <Page>1</Page>
                                         </Paging>
                                 </Get>
                         </Order>
                 </Request>
         </Requests>
 </AuroraRequestEnvelope>

Example Response:

<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>
				<Order>
					<OrderID>12345678</OrderID>
					<CustomerID>12345</CustomerID>
					<OrderStatus>Cancelled</OrderStatus>
					<PaymentType>card</PaymentType>
					<Addresses>
						<Address>
							<AddressID>123456</AddressID>
							<CustomerID>12345</CustomerID>
							<StorageType>I</StorageType>
							<AddressType>BT</AddressType>
							<EmailAddress>...</EmailAddress>
							<OptOut>0</OptOut>
							<Gender>female</Gender>
							<CompanyName></CompanyName>
							<Title>Miss</Title>
							<FirstName>...</FirstName>
							<LastName>...</LastName>
							<AddressLine1>...</AddressLine1>
							<AddressLine2></AddressLine2>
							<Town>...</Town>
							<County></County>
							<PostCode>...</PostCode>
							<Country>
								<ID>1</ID>
								<ISO>gb</ISO>
								<Name>UK</Name>
							</Country>
							<PhoneNumber>...</PhoneNumber>
							<MobileNumber></MobileNumber>
						</Address>
						<Address>
							<AddressID>123457</AddressID>
							<CustomerID>12345</CustomerID>
							<StorageType>I</StorageType>
							<AddressType>ST</AddressType>
							<EmailAddress>...</EmailAddress>
							<OptOut>0</OptOut>
							<Gender>female</Gender>
							<CompanyName></CompanyName>
							<Title></Title>
							<FirstName>...</FirstName>
							<LastName>...</LastName>
							<AddressLine1>...</AddressLine1>
							<AddressLine2></AddressLine2>
							<Town>...</Town>
							<County></County>
							<PostCode>...</PostCode>
							<Country>
								<ID>1</ID>
								<ISO>gb</ISO>
								<Name>UK</Name>
							</Country>
							<PhoneNumber>...</PhoneNumber>
							<MobileNumber></MobileNumber>
						</Address>
					</Addresses>
					<CourierName>Royal Mail</CourierName>
					<ShippingType>Standard</ShippingType>
					<TrackingNumber></TrackingNumber>
					<Currency>GBP</Currency>
					<TaxRate>20.00</TaxRate>
					<ShippingSku></ShippingSku>
					<ShippingCost>8.00</ShippingCost>
					<ShippingTax>2.00</ShippingTax>
					<CustomShippingCost>0</CustomShippingCost>
					<CustomShippingLabel></CustomShippingLabel>
					<OrderTotal>19.99</OrderTotal>
					<OrderSubtotal>16.6600</OrderSubtotal>
					<OrderTax>3.33</OrderTax>
					<CouponCode></CouponCode>
					<CouponDiscount>0.00</CouponDiscount>
					<OrderDiscount>0.00</OrderDiscount>
					<PriceBreakDiscount>0</PriceBreakDiscount>
					<LoyaltyDiscount>0.00</LoyaltyDiscount>
					<TotalDiscount>0.00</TotalDiscount>
					<InvoiceNotes></InvoiceNotes>
					<CustomerNotes></CustomerNotes>
					<CustomerSelectedDeliveryDate>0000-00-00 00:00:00</CustomerSelectedDeliveryDate>
					<DateDeliveryEstimate>2013-02-07 00:00:00</DateDeliveryEstimate>
					<DateShipped>0000-00-00 00:00:00</DateShipped>
					<DateCreated>2013-01-30T14:53:57+00:00</DateCreated>
					<Items>
						<Item>
							<OrderItemID>6543210</OrderItemID>
							<ProductID>123</ProductID>
							<ProductReference>SKU-1</ProductReference>
							<ProductEAN>1234567890</ProductEAN>
							<VariationID>1234</VariationID>
							<VariationReference>SKU-1-GREEN</VariationReference>
							<VariationEAN>1234567890A</VariationEAN>
							<BundleID></BundleID>
							<Price>19.99</Price>
							<Tax>3.33</Tax>
							<Discount>0.00</Discount>
							<TaxRate>20.00</TaxRate>
							<Quantity>1</Quantity>
							<QuantityReturned>0</QuantityReturned>
							<LineOrder>0</LineOrder>
							<LineStatus>
								<StatusCode>Cancelled</StatusCode>
								<ReasonCode>C</ReasonCode>
							</LineStatus>
							<AdditionalFields>
								<AdditionalField>
									<FieldName>An Additional Field Name</FieldName>
									<FieldValue>Additional Field Value</FieldValue>
								</AdditionalField>
							</AdditionalFields>
						</Item>
					</Items>
					<Transactions>
						<Transaction>
							<TransactionID>11223344</TransactionID>
							<Amount>22.98</Amount>
							<Display>1</Display>
							<NameOnCard>...</NameOnCard>
							<CardNumber>0001</CardNumber>
							<CardExpiry>0520</CardExpiry>
							<CardType>VISA</CardType>
							<Type>PAYMENT</Type>
							<Status>OK</Status>
							<StatusDetails>0000 : The Authorisation was Successful.</StatusDetails>
							<Provider>SagePay</Provider>
							<ProviderVendorTxCode>100000-10000000000000000000</ProviderVendorTxCode>
							<ProviderTxID>{00000000-0000-0000-0000-000000000000}</ProviderTxID>
							<ProviderSecurityKey>1000000001</ProviderSecurityKey>
							<ProviderAuthNumber>1000001</ProviderAuthNumber>
							<ProviderRelatedVendorTxCode></ProviderRelatedVendorTxCode>
							<ProviderAVSCV2></ProviderAVSCV2>
							<ProviderAddressResult></ProviderAddressResult>
							<ProviderPostCodeResult></ProviderPostCodeResult>
							<ProviderCV2Result></ProviderCV2Result>
							<Provider3DSecureStatus></Provider3DSecureStatus>
							<DateCreated>2013-01-30 14:53:57</DateCreated>
						</Transaction>
					</Transactions>
					<AdditionalFields>
						<AdditionalField>
							<FieldID>41</FieldID>
							<FieldName>Delivery Estimate</FieldName>
							<FieldValue>07/02/2013</FieldValue>
						</AdditionalField>
					</AdditionalFields>
					<FraudResults>
						<Result>
							<Action>Hold</Action>
							<Score>-51</Score>
							<MID>1693833085</MID>
							<DateCreated>2013-04-24T10:53:33+01:00</DateCreated>
						</Result>
						<Result>
							<Action>Release</Action>
							<Score>8</Score>
							<MID>1694102001</MID>
							<DateCreated>2013-04-23T10:53:33+01:00</DateCreated>
						</Result>
					</FraudResults>
				</Order>
			</Data>
		</Response>
	</Responses>
</AuroraResponseEnvelope>

Request Fields

Only if 'FraudResult' is provided

Field

Values

API Version

Description

Required

Interval

String interval

1.0+

Used to select date/time range from now into the past.

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

Interval:offset

String interval

Upcoming in 1.4+

Format as per "Interval" field. Used to provide a time offset for the "Interval" to end at, rather than now (the current time). The default offset is 10 seconds ( "PT10S" ) to reduce the chance of exporting orders while post purchase updates are being made.

No

Interval:date

Order

Using this con

1.4+

This attribute to the Interval tag allows you to specify which date should be used when performing this check. By default, both the Date the Order was Created and last Modified are checked, but either one can be specified here as desired. When "both" is specified only one of the date fields needs to match the specified interval.

No

DateStart

yyyy-mm-dd

1.0+

Only one of 'Interval' or 'DateStart' is permitted

DateStart:date

Order

Using this con

1.4+

This attribute to the DateStart tag allows you to specify which date should be used when performing this check. By default, both the Date the Order was Created and last Modified are checked, but either one can be specified here as desired. When "both" is specified only one of the dates needs to match the specified interval.

No

DateEnd

yyyy-mm-dd

1.0+

No

DateEnd:date

Order

Using this con

1.4+

This attribute to the DateStart tag allows you to specify which date should be used when performing this check. By default, both the Date the Order was Created and last Modified are checked, but either one can be specified here as desired. When "both" is specified only one of the dates needs to match the specified interval.

No

OrderIDs

Container

1.4+

No

OrderIDs.OrderID

Integer

1.4+

The Internal ID Aurora uses to identify an Order.

No

Cannot be used in conjunction with CustomerID

CustomerID

Integer

1.4+

The Internal ID Aurora uses to identify Users or Customers of the site.

No

Cannot be used in conjunction with OrderIDs

OrderStatuses

Container

1.1+

No

OrderStatuses.StatusID

Integer

1.1+

The status ID to restrict the result to.

Only if 'Statuses' are provided and if Statuses.OrderStatus not provided

OrderStatuses.OrderStatus

String

1.2+

The status string to restrict the result to.

There is a condition attribute which is optional. This can accept "IS" or "NOT" on each status so many conditions can be applied to the filtering.

So you can include or exclude many statuses in one API call.

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

Only if 'Statuses' is provided and if Statuses.StatusID not provided

FraudResult

Container

1.1+

No

FraudResult.Action

Restricted String

1.1+

When checking the Fraud results, only the most recent result is taken into account, for an order. I.e. if an order has been both Released and Held, whichever is the most recent result will take presidents and the other ignored completely.

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 (Cannot by updated/modified)

Only if 'FraudResult' is provided

PaymentType

String

1.1+

No

PaymentType.condition

String

1.2+

Optional attribute of the PaymentType element; values can be:

IS will include all orders of the matching payment type

 NOT will exclude all orders of the matching payment type

No

SourceCode

String

1.5+

The source code of the Order Source to restrict the result to.

No

Product

String

1.3+Container

No

Product.ProductReference

String

1.3+

Restrict the result to orders with products that contain the product reference.

There is a "condition" attribute which is optional. This will accept "IS" or "NOT", by default the behaviour is inclusive e.g. "IS"

Only one of the following is permitted:

ProductReference

 ProductEAN

VariationReference

 VariationEAN

Product.ProductEAN

String

1.3+

Restrict the result to orders with products that contain the product EAN.

There is a "condition" attribute which is optional. This will accept "IS" or "NOT", by default the behaviour is inclusive e.g. "IS"

Product.VariationReference

String

1.3+

Restrict the result to orders with products that contain the variation reference.

There is a "condition" attribute which is optional. This will accept "IS" or "NOT", by default the behaviour is inclusive e.g. "IS"

Product.VariationEAN

String

1.3+

Restrict the result to orders with products that contain the variation EAN.

There is a "condition" attribute which is optional. This will accept "IS" or "NOT", by default the behaviour is inclusive e.g. "IS"

Address

Container

1.4+

Container for address related conditions

No

Address.AddressType

String

1.4+

The Address Type to filter by i.e.

BT Billing address

 ST Shipping address

No

Address.PostCode

String

1.4+

Restrict the result to orders with postcode that match this string.

No

ItemCount

Container

1.4+

Container for item count related conditions

No

ItemCount.Min

Integer

1.4+

Restrict the result to orders with a minimum number of items.

No

ItemCount.Max

Integer

1.4+

Restrict the result to orders with a maximum number of items.

No

DetailLevel

Full or Status

1.4+

This allows the client to request varying volumes of data when receiving data back from the server.

Full will return all order information and date filters are applied to the order _modified date

Status will only return order status information and date filters are applied to the order and order item _last status changed date

No

Tracking

sent, unsent

1.2+

Tracking filters are based on tracking information either automatically set by previous calls to the Order Get API (i.e. when using tracking="automatic") or the Order Update API has been used to explicitly mark an order as sent.

sent will return orders that have previously been marked as sent

 unsent will return orders that have not previously been marked as sent

No

Tracking

sent, unsent or changed

1.4+

Tracking filters are based on tracking information either automatically set by previous calls to the Order Get API (i.e. when using tracking="automatic") or the Order Update API has been used to explicitly mark an order as sent.

sent will return orders that have previously been marked as sent

 unsent will return orders that have not previously been marked as sent

* changed will return orders that have been changed since they were last sent relative to the order modified date

Tracking

sent, unsent, changed, status_changed or item_status_changed

1.5+

Tracking filters are based on tracking information either automatically set by previous calls to the Order Get API (i.e. when using tracking="automatic") or the Order Update API has been used to explicitly mark an order as sent.

sent will return orders that have previously been marked as sent

 unsent will return orders that have not previously been marked as sent

changed will return orders that have been changed since they were last sent relative to the order modified date

 status_changed will return orders that have had their status changed since they were last sent relative to the order status last modified date

* item_status_changed will return orders that have had their item status(s) changed since they were last sent relative to the order status last modified date

No

Limit

Integer > 0

1.0+

The number of products to return before beginning to page

No

OrderLive

1 or 0

1.2+

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

Only if 'Token' is provided

Order Fields ( applies to OrderGet response, OrderAdd request , OrderUpdate request )

Field

Values

API Version

Description

OrderID

Integer

1.0+

The Internal ID Aurora uses to identify an Order.

CustomerID

Integer

1.0+

The Internal ID Aurora uses to identify Users or Customers of the site.

OrderStatus

Restricted String

1.0+

This represents the Order's current status and can only be set to a limited selection of values, as configured by the API administrators.

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

OrderLive

1 or 0

1.2+

(request only)

This marks an order as live ( default is 0 ). The use of this field depends on the agreed order workflow

PaymentType

Restricted String

1.0+

This describes the source of the Order or Payment. When placing new orders via the API, you should make use of the 'api' payment type unless otherwise agreed with the API administrator.

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

Addresses

Container

1.0+

This contains all of the addresses pertaining to an order. This will normally include a billing and a shipping address.

Addresses.Address

Container

1.0+

This contains all of the fields pertaining to an individual address.

Addresses.Address.Address**ID**

Integer

1.0+

The Internal ID Aurora uses to identify a record within the address book.

When updating an address within an existing order, the AddressID may be required depending on which version of the API you are using:

1.0+ requires a valid AddressID for an existing record.
 1.4+ requires either a valid AddressID or AddressType.

Addresses.Address.CustomerID

Integer

1.0+

The Internal ID Aurora uses to identify Users or Customers of the site.

Addresses.Address.StorageType

I or U

1.0+

This describes whether an address is an Order Address or a User/Customer Address. User/Customer addresses are addresses that have been saved to a Customers account for convenience and can be removed by the customer while Order Addresses are assigned specifically to Orders made and cannot be removed.

Addresses.Address.AddressType

BT or ST

1.0+

Describes whether an address is for Billing (BT) or Shipping (ST).

When using version 1.4+ of the Aurora API, the AddressType can be used to identify an order address without specifying the AddressID.

Addresses.Address.EmailAddress

String

1.0+

Addresses.Address.OptOut

1 or 0

1.0+

Is used by some mailing and reporting systems to control whether or not the address is used in mail-shots and marketing campaigns.

Addresses.Address.Gender

male or female

1.0+

Addresses.Address.CompanyName

String

1.0+

Addresses.Address.Title

Restricted String

1.0+

The is the User/Customer title, e.g. Mr, Mrs, etc.

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

Addresses.Address.FirstName

String

1.0+

Addresses.Address.LastName

String

1.0+

Addresses.Address.AddressLine1

String

1.0+

Addresses.Address.AddressLine2

String

1.0+

Addresses.Address.Town

String

1.0+

Addresses.Address.County

String

1.0+

Addresses.Address.PostCode

String

1.0+

Addresses.Address.Country

Restricted String

1.0+

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

Addresses.Address.PhoneNumber

String

1.0+

Addresses.Address.MobileNumber

String

1.0+

CourierName

Restricted String

1.0+

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

CourierCode

Restricted String

1.0+

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. If providing both CourierCode and CourierName, they must reference the same Courier setup within Aurora, if not an error will occur.

TrackingNumber

String

1.0+

ChargedCurrency

String

1.4+

The 3 character ISO code for the currency in which the order was charged and stored.

Currency

String

1.0+

This should be the 3 character ISO code for the currency the order was taken 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

ExchangeRate

Float

1.4+

The exchange rate used at the time the order was created to convert the ChargedCurrency to the Currency.

Order values are always stored within the ChargedCurrency i.e.

Where ChargedCurrency is GBP and Currency is EUR

OrderTotal * ExchangeRate = Value in EUR

TaxRate

Float

1.0+

The Tax percentage (VAT in the UK) that is applicable to the order. This value is used as a 'global' value for the order and is for reference only. For more precise details regarding which items had what levels of Tax allied to them, please see the Order Items data.

ShippingSku

String

1.0+

The SKU of the selected shipping method.

ShippingCost

Float

1.0+

The portion of the Order Total that is attributed to a standard Shipping Cost (less the VAT).

ShippingTax

Float

1.0+

The portion of the Order Total that is attributed to the tax payable on a standard Shipping Cost.

CustomShippingCost

Float

1.0+

This field should not be used unless first approved by the API Administrator. If you do not know why you might need to use this field, then it is most likely that you should simply use the 'ShippingCost' and 'ShippingTax' fields instead.

CustomShippingLabel

String

1.0+

When a 'CustomShippingCost' value is provided, a description for that shipping method must also be provided here.

OrderTotal

Float

1.0+

The total cost of the entire order, not including Shipping or Discounts.

The amount paid by a customer would be:

OrderTotal + ShippingCost + ShippingTax - TotalDiscounts

OrderSubtotal

Float

1.0+

The total cost of the Items ordered, not including Shipping, Discounts or Tax.

OrderTax

Float

1.0+

The proportion of the "OrderTotal" field that is attributed to Tax.

CouponCode

String

1.0+

The Discount/Coupon Code used against this order if there was one.

CouponDiscount

Float

1.0+

The discount gained by the use of the Discount/Coupon Code.

OrderDiscount

Float

1.0+

The discount gained by any other Order related promotions.

PriceBreakDiscount

Float

1.0+

The discount gained through bulk purchase.

LoyaltyDiscount

Float

1.0+

The discount gained by the use of Loyalty Points.

TotalDiscount

Float

1.0+

The total discount applied to the order as a result of all Promotions, Coupons, Loyalty Points and other related systems.

This value does not include the discounts applied to shipping as these are dealt with by simply reducing the shipping value at the basket.

InvoiceNotes

String

1.0+

Note left by the staff pertaining to the order.

CustomerNotes

String

1.0+

Notes left by the customer pertaining to this order or its delivery.

CustomerSelectedDeliveryDate

Date

1.0+

The date the customer selected for the Order to be delivered (if applicable). This field is often blank as the customer may not be given a delivery date option at point of sale.

DateDeliveryEstimate

DateTime

1.0+

The date that the order was predicted to reach the customer at the time of purchase.

DateShipped

DateTime

1.0+

The date that the order was marked as Despatched/Shipped.

DateCreated

DateTime

1.0+

The date that the order was originally placed.

ClickAndCollect

Container

1.0+

Contains all the details of the Click + Collect selected store.

ClickAndCollect.ID

Integer

1.0+

Contains the Aurora store ID.

ClickAndCollect.InternalID

Integer

1.0+

Contains the internal store ID .

ClickAndCollect.Name

String

1.0+

Contains the store name.

ClickAndCollect.Address

String

1.0+

Contains the store address.

ClickAndCollect.Telephone

String

1.0+

Contains the store telephone number.

ClickAndCollect.EmailAddress

String

1.4+

Contains the store email address.

CollectPlus

Container

1.0+

Contains all the details of the Click Plus selected store.

CollectPlus.ID

Integer

1.0+

Contains the Aurora store ID.

CollectPlus.InternalID

Integer

1.0+

Contains the internal store ID .

CollectPlus.Name

String

1.0+

Contains the store name.

CollectPlus.Address

String

1.0+

Contains the store address.

CollectPlus.Telephone

String

1.0+

Contains the store telephone number.

Items

Container

1.0+

Contains all the details of the items ordered.

Items.Item

Container

1.0+

Contains all the information pertaining to a single ordered item.

Items.Item.OrderItemID

Integer

1.0+

The Internal ID Aurora uses to identify an Ordered Item.

Items.Item.ProductID

Integer

1.0+

The Internal ID Aurora uses to identify a Product.

Items.Item.ProductReference

String

1.0+

The unique reference (or SKU) for the Product, if no overruling variation reference is present, this can be used to identify the item that has been ordered.

Items.Item.ProductEAN

String

1.1+

The EAN for the Product, if no overruling variation reference is present, this can be used to identify the item that has been ordered.

Items.Item.VariationID

Integer

1.0+

The Internal ID Aurora uses to identify a Product Variation, such as size or colour.

Not all products have variations, so this field may often be blank. If it is not, then it is important that it be recorded and passed on with or instead of the ProductID field to ensure the correct products are ordered.

Items.Item.VariationReference

String

1.0+

The unique reference (or SKU) for the Product Variation. When this field is populated, the main 'ProductReference' field becomes secondary. With this in mind, you should use this field for reference whenever it is present.

Not all products have variations, so this field may often be blank.

Items.Item.VariationEAN

String

1.1+

The EAN for the Product Variation. When this field is populated, the main 'ProductEAN' field becomes secondary. With this in mind, you should use this field for reference whenever it is present.

Not all products have variations, so this field may often be blank.

Items.Item.BundeID

Integer

1.0+

The Internal ID Aurora uses to identify a Product Bundle. These are set-up specifically by the API Administrators in the Aurora back-end. You can collect what bundles are available to a particular product using the 'ProductGet' method on the API.

Items.Item.Price

Float

1.0+

The item price (excluding any discount, as detailed in "Items.Item.Discount").

The amount the customer was charged for the entire line is:

(Items.Item.Price * Items.Item.Quantity) - Items.Item.Discount

Items.Item.Tax

Float

1.0+

The proportion of the Item Price that is attributed to Tax.

Items.Item.TaxBand

String

Upcoming

Name of the Tax Band for this product from the predefined list defined as "TaxBandType" in the XSD

Items.Item.Discount

Float

1.0+

The total discount applied to the line.

This is not the discount per item, but per line.

For example, if the product quantity is 2 and the product discount is 10, then that is 5 per item to a total of 10 and not 10 per item to a total of 20.

You cannot simply calculate the discount per item by dividing the "Discount" field by the "Quantity" field as this can result in 'lost' funds in the event the total discount is not evenly (to the penny) divisible by the number of products.

For example, for a "Buy Two Get One Free" offer where the products costs £2, the discount would be £2 for the line, but theoretically £0.6666666 per item and so the price cannot be presented including discount 'per item' due to the floating point issue encountered here.

Note: Where necessary Aurora's internal systems accounts for this by listing items separately and having the last item have one entire penny more discount and all others on less, but this is not commonly required.

Items.Item.TaxRate

Float

1.0+

The Tax percentage (VAT in the UK) that is applicable to the order.

Items.Item.Quantity

Integer

1.0+

The number of Products purchased in this line. As items are returned, this value should be depleted.

Items.Item.QuantityReturned

Integer

1.0+

The number of the purchased Products from this line that have been returned. As items are returned, this value should be increased.

Items.Item.LineOrder

Integer

1.0+

This field is sometimes populated to control the order in which the Ordered Items appear.

Items.Item.LineStatus

String

1.0+

Contains all the details of the items line status.

Items.Item.LineStatus.Quantity

String

1.0+

An optional quantity of the ordered item to apply the specified status to. If the quantity is less than the item quantity then the item will be split into two items and the specified status will be applied to the first item.

Items.Item.LineStatus.StatusCode

String

1.0+

The Status Code as defined for the selected line status.

Items.Item.LineStatus.ReasonCode

String

1.0+

The Reason Code as defined for the selected line reason.

Items.Item.AdditionalFields

Container

Upcoming

Contains information about all additional item fields

Items.Item.AdditionalFields.AdditionalField

Container

Upcoming

Contains information about single additional item field

Items.Item.AdditionalFields.AdditionalField.FieldName

String

Upcoming

Additional field name

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.

Items.Item.AdditionalFields.AdditionalField.FieldValue

String

Upcoming

Additional field value

Items.Item.DiscountList

Container

Upcoming

Contain all of the information about discounts applied to the item

Items.Item.DiscountList.DiscountItem

Container

Upcoming

Contain all of the information about single discount applied to the item

Items.Item.DiscountList.DiscountItem.Type

Container

Upcoming

Contain type of discount

Items.Item.DiscountList.DiscountItem.Type.BasketPromotion

Container

Upcoming

Contain all of the information required to pick and match Aurora's promotion

Items.Item.DiscountList.DiscountItem.Type.BasketPromotion.Id

Integer

Upcoming

  • Element to hold id of Aurora Basket Promotion Id.
    _ If the basket promotion cannot be found in Aurora the “OrderAdd” call will not create an order but will return an error detailing that the promotion could not be found.

Items.Item.DiscountList.DiscountItem.Type.BasketPromotion.PromotionName

String

Upcoming

  • Temporary work around to use this field to search promotion_name, this should only be used when there is no way to determine the  unique promotion id
    _ If the basket promotion cannot be found in Aurora the “OrderAdd” call will not create an order but will return an error detailing that the promotion could not be found.

Items.Item.DiscountList.DiscountItem.DiscountAmount

Float

Upcoming

Amount of discount applied and attributed to the order line for the specified promotion, inc VAT

Items.Item.DiscountList.DiscountItem.DiscountNumber

Integer

Upcoming

  • *Optional** integer element used to:

    * *Denote sequence in which the promotion was applied ( lowest first )
    * Grouping of promotion applications
    *Equal number for items in the same order means grouped in the same promotion application and must be part of the same promotion.
    * Different number and same promotion for items within the same order would denote multiple applications/instances of the same promotion.

Items.Item.DiscountList.DiscountItem.PromotionAmount

Float

1.4+

This describes the discount that should be issued by the Promotion being attached to the Ordered Item, e.g. the promotion might issues a 20% discount, in which case this value should be 20 to represent the 20% and not the actual value removed from the item and already listed in the DiscountAmount field.

Items.Item.DiscountList.DiscountItem.PromotionAmountType

String

1.4+

This describes the method used to apply the PromotionAmount provided, e.g. this might be "percent" which would mean the item is reduced by the percentage given in the PromotionAmount field.

Transactions

Container

1.0+

Contains all the details of the order's payment transactions.

Transactions.Transaction

Container

1.0+

Contains all the information pertaining to a single payment transaction.

Transactions.Transaction.TransactionID

Integer

1.1+

The field identifier. If this field is provided, then the transaction details are treated as an 'update' and not an 'addition' When updating transactions, some fields are not permitted to be changed to protect the records for accounting.

Transactions.Transaction.Amount

Float

1.0+

The full and final amount actually charged by this transaction. (Cannot by updated/modified)

Transactions.Transaction.Display

1 or 0

1.1+

If this was a Card Transaction and this is set to 1 then the details provided for this transaction will be presented to the customer on the website as a 'Stored Card' to perform repeat payments with.

Transactions.Transaction.NameOnCard

String

1.1+

If this was a Card Transaction, this is the name as it appears on the payment card.

Transactions.Transaction.CardNumber

String

1.1+

If this was a Card Transaction, the last four (4) digits of the card number should be provided here for use when referencing the card on the website. The full card number should never be stored here.

Transactions.Transaction.CardExpiry

String

1.1+

If this was a Card Transaction, the expiry date should be provided as 'MMYY', e.g. '0112' for January 2012.

Transactions.Transaction.CardType

String

1.1+

If this was a Card Transaction, the card type should be provided as a short uppercase string, e.g. 'VISA'.

Transactions.Transaction.Type

Restricted String

1.0+

To find out what values are permitted here, please refer to the API's XSD file, which can be found on your API URL ashttp://api_url/api_version/aurora.xsd (Cannot by updated/modified)

"PAYMENT" - a payment transaction
 "DEFERRED" - a transaction used to reserve funds and defer payment. Not to be used in order payment calculations.
"RELEASE" - a payment transaction; which has released funds from a previous "DEFERRED" transaction
 "REFUND" - a payment refund transaction; that has refunded money back to the customer
"REPEAT" - a payment transaction; made by using previously saved customer details
 "VOID" - a transaction representing a voided previous transaction e.g. a "DEFERRED" transaction where payment was not taken

Transactions.Transaction.Status

OK or FAILED

1.0+

Was this transaction successful or not?

Transactions.Transaction.StatusDetails

String

1.1+

This is a free-form string provided to describe the transaction status or result.

Transactions.Transaction.Provider

Restricted String

1.0+

This describes the source of the Order or Payment and is often the same or similar to the order's 'PaymentType' field. When placing new orders via the API, you should make use of the 'api' payment type unless otherwise agreed with the API administrator. (Cannot by updated/modified)

Transactions.Transaction.ProviderVendorName

String

1.1+

This is the 'Vendor Name' or 'Username' used to process the request with the Provider.

Transactions.Transaction.ProviderVendorTxCode

String

1.1+

If the provider issues a Tx Code or similar, then this should be stored here.

Transactions.Transaction.ProviderTxID

String

1.1+

If the provider issues a Tx ID or similar, then this should be stored here.

Transactions.Transaction.ProviderSecurityKey

String

1.1+

If the provider issues a Security Code or similar, then this should be stored here.

Transactions.Transaction.ProviderAuthNumber

String

1.1+

The Auth code returned on successful completion of a transaction should be stored here.

Transactions.Transaction.ProviderRelatedVendorTxCode

String

1.1+

Transactions.Transaction.ProviderAVSCV2

String

1.1+

A short sting field to describe the 'Match' achieve on the relevant check, e.g. "ALL MATCH" or "SECURITY CODE MATCH ONLY".

Transactions.Transaction.ProviderAddressResult

NOTMATCHED or MATCHED or NOTCHECKED

1.1+

The result of the provider's Address check(s).

Transactions.Transaction.ProviderPostCodeResult

NOTMATCHED or MATCHED or NOTCHECKED

1.1+

The result of the provider's Postcode check(s).

Transactions.Transaction.ProviderCV2Result

NOTMATCHED or MATCHED or NOTCHECKED

1.1+

The result of the provider's CSV check(s).

Transactions.Transaction.Provider3DSecureStatus

Restricted String

1.1+

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

Transactions.Transaction.DateCreated

DateTime

1.0+

The date and time that this transaction was attempted. (Cannot by updated/modified)

Transactions.Transaction.TransactionAdditionalFields

Container

1.4+

Contains integration level additional transaction information (Paypal Credit, etc).

Transactions.Transaction.TransactionAdditionalFields.TransactionAdditionalField

Container

1.4+

Contains all the information pertaining to a single transaction additional field.

Transactions.Transaction.TransactionAdditionalFields.TransactionAdditionalField.FieldID

Int

1.4+

The field identifier.

Transactions.Transaction.TransactionAdditionalFields.TransactionAdditionalField.FieldName

String

1.4+

The name of the transaction additional 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 a detrimental impact on the performance of several Aurora services.

Transactions.Transaction.TransactionAdditionalFields.TransactionAdditionalField.FieldValue

String

1.4+

The value of the transaction additional field.

AdditionalFields

Container

1.0+

Contains integration level additional order information (Amazon, eBay, Debenhams, Paypal etc).

AdditionalFields.AdditionalField

Container

1.0+

Contains all the information pertaining to a single additional field.

AdditionalFields.AdditionalField.FieldID

Int

1.0+

The field identifier.

AdditionalFields.AdditionalField.FieldName

String

1.0+

The name of the additional field.

AdditionalFields.AdditionalField.FieldValue

String

1.0+

The value of the additional field.

FraudResults

Container

1.1+

Contains all Fraud Checks performed on an order. If there is more then one result for the order, then the most recent result is always returned first.

FraudResults.Result

Container

1.1+

Contains all the information pertaining to a single fraud result.

FraudResults.Result.Action

Restricted String

1.1+

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

FraudResults.Result.Score

Int

1.1+

FraudResults.Result.MID

Int

1.1+

FraudResults.Result.DateCreated

DateTime

1.1+

Email (API Version < 1.4)

🚧

This method is only supported in versions 1.1 to 1.3 of the Aurora API. For later versions of the Aurora API, please see the dedicated Order Email section and its methods.

Deferred: No

This method is intended to allow third parties to trigger genuine Aurora emails over the API. This is most commonly used for sending confirmation emails after adding new orders, but can be used to send any per-configured email template or even custom messages from Aurora to a customer.

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>
             <Order>
                 <Email>
                     <RequestID>1</RequestID>
                     <OrderID>1234</OrderID>
                     <Template>System: Order Confirmation</Template>
                 </Email>
             </Order>
         </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>
                 <OrderID>695657</OrderID>
                 <Email>
                     <Subject>Aurora Demo: A message regarding your order</Subject>
                     <Reference>5fa4dd21ae1e8b2b86e0d3b43dbdf6a4</Reference>
                 </Email>
             </Data>
         </Response>
     </Responses>
</AuroraResponseEnvelope>

The 'Reference' field can be used to view the email in a browser and is often provided to the customer to support the 'Having trouble viewing this email in your email client' feature. To use this code to view the content of the email sent to the customer, simply add it to the end of the URL '/emails/?ref='.

For example:

http://www.example.com/emails/?ref=5fa4dd21ae1e8b2b86e0d3b43dbdf6a4

Request Fields

Field

Values

API Version

Description

Required

Order ID

Integer

1.1+

The Internal ID Aurora used to identify an Order. Emails can only be sent in connection to orders placed and Aurora automatically pulls out the email address associated to the order provided.

Yes

Subject

String

1.1+

If provided, this will override any subject configured for the email being sent.

No

Template

Restricted String

1.1+

This string controls what email template is used for the request. There are two kinds of template 'System' and 'Custom'. 'System' templates are always present and cannot be changed by the client, where 'Custom' emails can be added, edited and removed by clients via the Aurora back-end.

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

If Message is provided then Template cannot be

Message

String

1.1+

This field can be used to provide custom content for an email. The content provided is placed within the default email header and footer templates used for all Aurora emails, ensuring company branding is maintained.

No

AttachInvoice

yes or no

1.1+

If 'yes', an invoice is generated for the order and attached to the email before it is sent.

This field is often not required as Aurora will attach invoices to Dispatch emails automatically if the client has configured Aurora to do so.

NOTE: This invoice relies on the presence of an invoice template, which some clients do not have. Please contact the client for advice if you are unsure if they can provide email invoices.

No

Validate

Deferred: No

🚧

The Order Validate API can be used to perform validations against address, items and order amount details i.e.

  • Do the address details validate against the Aurora checkout validation processes?
  • Are all of the item products live?
  • Do all of the products or variations have sufficient stock?

The process will also attempt to create a basket using the items specified, apply basket promotions and compare the basket total amount against the order total amount specified within your request.

🚧

The Order Validate API also allows you to specify a basket user reference; when provided, this will be used to load an existing basket that may have been created using the Basket Item Add API or the Aurora frontend basket.

When a basket is loaded by user reference, the items within the Order Validate API request are ignored and instead the items within the existing basket are used to validate the total amounts.

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>
            <Order>
                <Validate>
                    <PaymentType>paypal</PaymentType>
                    <Currency>GBP</Currency>
                    <TaxRate>20.00</TaxRate>
                    <ShippingID>47</ShippingID>
                    <ShippingCost>2.10</ShippingCost>
                    <ShippingTax>0.85</ShippingTax>
                    <OrderTotal>117.98</OrderTotal>
                    <OrderSubtotal>18.01</OrderSubtotal>
                    <OrderTax>1.98</OrderTax>
                    <TotalDiscount>0.00</TotalDiscount>
                    <Addresses>
                        <Address>
                            <AddressType>BT</AddressType>
                            <EmailAddress>[email protected]</EmailAddress>
                            <Title>Mr</Title>
                            <FirstName>Bob</FirstName>
                            <LastName>Tide</LastName>
                            <AddressLine1>Somewhere</AddressLine1>
                            <AddressLine2>Over the rainbow</AddressLine2>
                            <Town>Way up high</Town>
                            <County>Cheshire</County>
                            <PostCode>AB1 2PD</PostCode>
                            <Country>GB</Country>
                            <PhoneNumber>01234567890</PhoneNumber>
                            <MobileNumber>07123456789</MobileNumber>
                        </Address>
                        <Address>
                            <AddressType>ST</AddressType>
                            <EmailAddress>[email protected]</EmailAddress>
                            <Title>Mr</Title>
                            <FirstName>Bob</FirstName>
                            <LastName>Tide</LastName>
                            <AddressLine1>Somewhere</AddressLine1>
                            <AddressLine2>Over the rainbow</AddressLine2>
                            <Town>Way up high</Town>
                            <County>Cheshire</County>
                            <PostCode>AB1 2PD</PostCode>
                            <Country>GB</Country>
                            <PhoneNumber>01234567890</PhoneNumber>
                            <MobileNumber>07123456789</MobileNumber>
                        </Address>
                    </Addresses>
                    <Items>
                        <Item>
                            <VariationReference>V518D48BD09AD0</VariationReference>
                            <Price>12.01</Price>
                            <Tax>2.98</Tax>
                            <Discount>2.98</Discount>
                            <TaxRate>20.00</TaxRate>
                            <Quantity>1</Quantity>
                        </Item>
                    </Items>
                </Validate>
            </Order>
        </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>
         </Response>
     </Responses>
</AuroraResponseEnvelope>

Validation Errors

Where order detail result in a validation error, these will be returned using the standard Aurora error format, please see Aurora API: Errors

Request Fields

Field

Values

API Version

Description

Required

PaymentType

String

1.5+

The order payment type.

Yes

Currency

String

1.5+

This should be the 3 character ISO code for the currency the order was taken 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

Yes

TaxRate

Float

1.5+

The Tax percentage (VAT in the UK) that is applicable to the order. This value is used as a 'global' value for the order and is for reference only. For more precise details regarding which items had what levels of Tax allied to them, please see the Order Items data.

Yes

ShippingID

String

1.5+

The ID of the selected shipping method.

No

ShippingCost

Float

1.5+

The portion of the Order Total that is attributed to a standard Shipping Cost (less the VAT).

No

ShippingTax

Float

1.5+

The portion of the Order Total that is attributed to the tax payable on a standard Shipping Cost.

No

OrderTotal

Float

1.5+

The total cost of the entire order, not including Shipping or Discounts.

The amount paid by a customer would be:

OrderTotal + ShippingCost + ShippingTax - TotalDiscounts

Yes

OrderSubtotal

Float

1.0+

The total cost of the Items ordered, not including Shipping, Discounts or Tax.

No

OrderTax

Float

1.0+

The proportion of the "OrderTotal" field that is attributed to Tax.

No

TotalDiscount

Float

1.0+

The total discount applied to the order as a result of all Promotions, Coupons, Loyalty Points and other related systems.

This value does not include the discounts applied to shipping as these are dealt with by simply reducing the shipping value at the basket.

No

Basket

Container

1.5+

No

Basket.UserReference

1.5+

The user reference associated with the basket to validate.

This is the ac_shop cookie stored within the users browser.

Yes

Basket.CouponCodes

Container

1.5+

No

Basket.CouponCodes.CouponCode

String

1.5+

A validate basket promotion coupon code.

No

Addresses

Container

1.5+

This contains all of the addresses pertaining to an order. This will normally include a billing and a shipping address.

Yes

Addresses.Address

Container

1.5+

This contains all of the fields pertaining to an individual address.

Yes

Addresses.Address.AddressType

BT or ST

1.5+

Describes whether an address is for Billing (BT) or Shipping (ST).

Yes

Addresses.Address.EmailAddress

String

1.5+

Yes

Addresses.Address.Title

Restricted String

1.5+

The is the User/Customer title, e.g. Mr, Mrs, etc.

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

Addresses.Address.FirstName

String

1.5+

Yes

Addresses.Address.LastName

String

1.5+

Yes

Addresses.Address.AddressLine1

String

1.5+

Yes

Addresses.Address.AddressLine2

String

1.5+

Addresses.Address.Town

String

1.5+

Yes

Addresses.Address.County

String

1.5+

No

Addresses.Address.PostCode

String

1.5+

Yes

Addresses.Address.Country

Restricted String

1.5+

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

Yes

Addresses.Address.PhoneNumber

String

1.5+

No

Addresses.Address.MobileNumber

String

1.5+

No

Items

Container

1.0+

Contains all the details of the items ordered.

Yes

Items.Item

Container

1.0+

Contains all the information pertaining to a single ordered item.

Items.Item.ProductReference

String

1.0+

The unique reference (or SKU) for the Product, if no overruling variation reference is present, this can be used to identify the item that has been ordered.

Yes

Items.Item.VariationReference

String

1.0+

The unique reference (or SKU) for the Product Variation. When this field is populated, the main 'ProductReference' field becomes secondary. With this in mind, you should use this field for reference whenever it is present.

Not all products have variations, so this field may often be blank.

Yes

Items.Item.Price

Float

1.0+

The item price (excluding any discount, as detailed in "Items.Item.Discount").

The amount the customer was charged for the entire line is:

(Items.Item.Price * Items.Item.Quantity) - Items.Item.Discount

Yes

Items.Item.Tax

Float

1.0+

The proportion of the Item Price that is attributed to Tax.

No

Items.Item.Discount

Float

1.0+

The total discount applied to the line.

This is not the discount per item, but per line.

For example, if the product quantity is 2 and the product discount is 10, then that is 5 per item to a total of 10 and not 10 per item to a total of 20.

You cannot simply calculate the discount per item by dividing the "Discount" field by the "Quantity" field as this can result in 'lost' funds in the event the total discount is not evenly (to the penny) divisible by the number of products.

For example, for a "Buy Two Get One Free" offer where the products costs £2, the discount would be £2 for the line, but theoretically £0.6666666 per item and so the price cannot be presented including discount 'per item' due to the floating point issue encountered here.

Note: Where necessary Aurora's internal systems accounts for this by listing items separately and having the last item have one entire penny more discount and all others on less, but this is not commonly required.

No

Items.Item.TaxRate

Float

1.0+

The Tax percentage (VAT in the UK) that is applicable to the order.

Yes

Items.Item.Quantity

Integer

1.0+

The number of Products purchased in this line. As items are returned, this value should be depleted.

Yes

Updated 13 days ago