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. or ) 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 | [created/modified/both] | 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 | [created/modified/both] | 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 | [created/modified/both] | 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 5 months ago