Authenticate
See Authenticate.
This document outlines the purpose, technology, use cases, methods, objects and examples for using the Orders API.
This document focuses on the SOAP interface to this API.
The Orders API provides programmatic access to the order database and allows for control and maintenance of order data within the system.
The Orders API exposes two primary native interfaces via .NET and SOAP.
Full documentation for this interface is available in the API Reference.
This section documents the SOAP interface to the API.
The SOAP API endpoint for any site is located at https://[siteurl]/global/api/Orders.asmx
This endpoint is enabled for access via SOAP as well as HTTP GET and POST. The Service Description is also available directly via this endpoint.
Note: For systems with satellite sites, the API will be available only under the primary site URL.
The Orders API via SOAP uses the Permissions System to allow and deny access to users. Use of the API requires a user to be granted the various actions (under iSAMS / API / Orders) to be able to authenticate and perform the various actions available under this API.
Error handling is primarily left to the caller. Any methods that return an ApiResponse object will provide additional details that can be used to assist when debugging problems.
Where a "Call Identifier" is returned in the Message field of the ApiResponse, then a full exception trace will be available from http://[siteurl]/logs/api/{Call Identifier}.txt
Orders API usage examples are available. These examples demonstrate the use of the API via a SOAP interface and are available in C# and Java.
Available methods are listed below.
See Authenticate.
Retrieves a single Order from the provided identifier.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Security token to use. |
| orderID | int | ID of the order to retrieve. |
An OrderApiResponse containing the Order object.
Retrieves Orders for the provided identifiers.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Security token to use. |
| ids | int[] | An integer array of order IDs corresponding to the orders to be retrieved. |
An OrderApiResponse containing the referenced of Order objects.
Retrieves all related Orders within the same split tree for the provided order ID.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Security token to use. |
| orderID | int | The Order ID to find all related orders for. |
An OrderApiResponse containing the Order objects.
Search for orders matching the specified search criteria. All input search terms except customerid perform partial matches on the search fields (e.g. searching for an email of 'estar' will return all orders with 'estar' anywhere in their email address.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Security token to use. |
| String | All or part of the order's email address. | |
| name | String | All or part of the order's delivery name. |
| country | String | All or part of the order's delivery country. |
| address | String | All or part of the order's delivery address. |
| customerID | Nullable<int> | The order's customerID. Note that this an exact match and other search terms are ignored. |
| productTitle | String | All or part of the product title of any order items. |
| productSKU | String | All or part of the product SKU of any order items. |
| externalOrderID | String | All or part of the order's external order ID. |
| externalOrderSource | String | All or part of the order's external order source. |
An IntegerArrayApiResponse containing the order IDs of all matching orders.
Return the list of all order IDs according to their Order status (eg. searching for a StatusID 'Confirmed' will show the list of all the order IDs with confirmed status)
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Security token to use. |
| status | OrderStatus | The Order Status to retrieve all orders for |
An IntegerArrayApiResponse containing the order IDs of all matching orders by Order Status.
This method has been deprecated, please use ListByOrderStatus instead.
Return the list of all available order void reasons.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Security token to use. |
An Collection<IdentifierValuePair<string,string>> containing a list of void reason names and codes.
Return the list of all order IDs according to their Order status (eg. searching for a status of 21 will show the list of all the order IDs with a status of 'To Be Printed').
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Security token to use. |
| status | int | The Order Status ID to retrieve all orders for |
An IntegerArrayApiResponse containing the order IDs of all matching orders by Order Status.
Possible order statuses can be retrieved using ListAvailableOrderStatuses.
Returns the order IDs of orders created in the supplied date range.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Security token to use. |
| start | DateTime | The start of the date range (inclusive), in UTC. |
| end | DateTime | The end of the date range (inclusive), in UTC. |
An IntegerArrayApiResponse containing the order IDs of all orders created within the specified date range.
Returns the order IDs of orders modified in the supplied date range.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Security token to use. |
| start | DateTime | The start of the date range (inclusive), in UTC. |
| end | DateTime | The end of the date range (inclusive), in UTC. |
An IntegerArrayApiResponse containing the order IDs of all orders modified within the specified date range.
Return a list of all available order statuses within the system.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Security token to use. |
An Collection<IdentifierValuePair<int,string>> containing the Status IDs and names of all available order statuses.
New order statuses are added rarely. The response from this method can be cached safely.
Create a new order. Defaults to guest customer and default website.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Security token to use. |
An OrderApiResponse containing a new Order object
Persists the provided order.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Security token to use. |
| order | Order | The hydrated Order to persist. |
An IntegerArrayApiResponse containing the OrderID of the newly imported order.
See the notes for ImportOrders.
Creates new orders from imported Order data. The following information is added to the system:
Ignored import data:
This ignored data may be supported in later versions of the Orders API.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Security token to use. |
| orders | Collection<Order> | Hydrated Orders to persist. |
An IntegerArrayApiResponse containing the OrderIDs of the newly imported orders.
Orders with a populated ID field are IGNORED. This method is only for inserting new orders, it cannot be used to update existing orders.
Attempting to import an Order with a duplicate ExternalOrderSource and ExternalOrderID will abort the import batch and return an error.
If a phone number is supplied in both the Order object and the shipping CustomerAddress object, the order phone number will take precedence.
When setting the OrderStatus and Status properties on an Order, OrderStatus will take precedence if present. If OrderStatus is null, Status will be used.
For click and collect orders, the system will ignore the supplied shipping address and set the collection store address from the database as the order shipping address.
If the specified barcodes for the order items cannot be directly mapped to product items, a historic barcode search will be performed in case the barcodes have changed.
This method operates in one of two modes per-order when determining tax values for the imported order and items. The appropriate tax mode to use when importing orders depends on the use case.
If Order.FreightIncludingTax and OrderItem.UnitPriceIncludingTax are not supplied, the system will calculate tax rates for the order based on FreightPrice/FreightDiscount/FreightTax and UnitPrice/UnitDiscount/UnitTax, and return tax-inclusive/exclusive prices based on these rates. When FreightTax or UnitTax are zero, the system will fall back to an appropriate default tax rate. As this cannot be exact for all values, this can lead to small discrepancies - typically a few cents - between the order and item values in the system and the corresponding values in the originating system.
Orders with a value for FreightIncludingTax and that have OrderItems with a value for UnitPriceIncludingTax use a "store-and-reflect" tax model. The system will persist and output the supplied tax-inclusive and tax-exclusive order and item values, rather than performing any calculations on these values. This eliminates any order or item value discrepancies between the system and the originating external system. This model places the onus on the caller to populate all tax-inclusive and tax-exclusive fields with the correct values. It is strongly recommended to populate the following fields when using this mode:
| Object | Field | Type |
|---|---|---|
| Order | Freight | Tax-exclusive |
| FreightIncludingTax | Tax-inclusive | |
| FreightDiscount | Tax-exclusive | |
| FreightDiscountIncludingTax | Tax-inclusive | |
| FreightTax | Tax | |
| OrderBasedDiscount | Tax-inclusive | |
| OrderBasedDiscountExcludingTax | Tax-exclusive | |
| OrderItem | UnitPrice | Tax-exclusive |
| UnitPriceIncludingTax | Tax-inclusive | |
| UnitDiscount | Tax-exclusive | |
| UnitDiscountIncludingTax | Tax-inclusive | |
| UnitTax | Tax |
Exports specified order data to a series of XML files.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Security token to use. |
| orderIDs | Collection<int> | A collection containing the IDs of the orders to be exported. |
A StringArrayApiResponse containing the filenames of the exported files.
A null exports data for all orders.
Exports specified order data to a series of JSON files.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Security token to use. |
| orderIDs | Collection<int> | A collection containing the order IDs of the orders to be exported. |
A StringArrayApiResponse containing the filenames of the exported files.
A null exports data for all orders.
Exports specified order data to a series of CSV files.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Security token to use. |
| orderIDs | Collection<int> | A collection containing the order IDs of the orders to be exported. |
A StringArrayApiResponse containing the filenames of the exported files.
Adds a note to an Order.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Security token to use. |
| orderID | int | Add a note to the order with this ID. |
| note | String | The note text to be added. Will be truncated to 512 characters. |
| displayLevel | int | The display level for the note. Defaults to 2 (show in admin). |
An ApiResponse containing the result of the operation.
Notes are restricted to 512 characters and will be truncated if necessary.
Updates an order's address details. Orders support address types "Billing" and "Shipping". If the "Shipping" address Country is changed the freight is recalculated.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Security token to use. |
| orderID | int | Order's unique ID |
| address | CustomerAddress | Address data to update. Orders support address types "Billing" and "Shipping". |
An ApiResponse containing the result of the operation.
Updates an order's email address.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Security token to use. |
| orderID | int | Order's unique ID |
| String | Email address (max 100 characters). The email address must be valid otherwise an exception will be thrown. |
An ApiResponse containing the result of the operation.
Updates an order's phone number.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Security token to use. |
| orderID | int | Order's unique ID |
| phone | String | Phone number (max 50 characters). |
An ApiResponse containing the result of the operation.
Updates an order's delivery instructions.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Security token to use. |
| orderID | int | Order's unique ID |
| note | String | New Delivery Instructions (max 500 characters). |
An ApiResponse containing the result of the operation.
Updates an order's gift status.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Security token to use. |
| orderID | int | Order's unique ID |
| status | Boolean | True if the order should be treated as a gift. |
An ApiResponse containing the result of the operation.
Updates an order's gift message.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Security token to use. |
| orderID | int | Order's unique ID |
| message | String | New gift message (max 500 characters). |
An ApiResponse containing the result of the operation.
Updates an order's admin reference.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Security token to use. |
| orderID | int | Order's unique ID |
| note | String | New order reference (max 50 characters). |
An ApiResponse containing the result of the operation.
Updates an order's follow-up date.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Security token to use. |
| orderID | int | Order's unique ID |
| date | DateTime | New follow-up date. |
An ApiResponse containing the result of the operation.
Updates an order's freight provider/shipping method.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Security token to use. |
| orderID | int | Order's unique ID |
| freightProvider | String | The name of the freight provider. |
An ApiResponse containing the result of the operation.
This also updates the orders priority to be the new freight provider's priority if the freight provider has a priority assigned.
Updates the currency of an order.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Security token to use. |
| orderID | int | The identifier of the order which to update. |
| alphaCode | String | The alpha (3) currency code to update the order to. |
An ApiResponse containing the result of the operation.
Updates the collection store of an order.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Security token to use. |
| orderID | int | The identifier of the order which to update. |
| storeID | int | The identifier of the store to be assigned to the order. |
An ApiResponse containing the result of the operation.
Updates the freight charge of an order.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Security token to use. |
| orderID | int | The identifier of the order which to update. |
| freightCharge | Decimal | The standard freight charge for the order excluding tax. |
| freightDiscount | Decimal | Any discount applied to the freight of the order before tax. |
| freightTax | Decimal | The tax charged for the freight on the order. |
An ApiResponse containing the result of the operation.
If a negative freight charge is specified then the value will default to 0.
Adds a product item to an order, returns the newly created OrderItem ID. If no current product item has the barcode assigned, a historic barcode search will be performed in case the barcode for the intended product item has changed.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Security token to use. |
| orderID | int | ID of the Order to add the item to. |
| barcode | String | The barcode of the ProductItem to add to the Order. |
| quantity | int | The number of items to add to the order. |
Returns the newly created OrderItem ID.
Adds or updates the provided order item.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Security token to use. |
| item | OrderItem | The new/updated OrderItem. |
An ApiResponse containing the result of the operation.
Adds or updates the provided order items.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Security token to use. |
| items | Collection<OrderItem> | The new/updated OrderItems. |
An ApiResponse containing the result of the operation.
Updates the status of the specified quantity of the order item(s) to 'deleted'. If this would not delete the full quantity of the product items incorporated in this order item then the order item will be split.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Security token to use. |
| orderItemID | int | The order item ID |
| quantity | int | The quantity of the product to be deleted. |
An ApiResponse containing the result of the operation.
Records the return of the specified quantity of the order item and mark as 'deleted' in the system. If this would not delete the full quantity of the product items incorporated in this order item then the order item will be split. Order must be at status Completed.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Security token to use. |
| item | ReturnItemInfo | The ReturnItemInfo object containing the return data. |
An ApiResponse containing the result of the operation.
Add a payment transaction to an order. The Transaction object contains payment data (e.g. credit card number etc).
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Security token to use. |
| orderID | int | Unique ID of the order to add a payment transaction. |
| transaction | Transaction | The Transaction object containing the payment data. |
An ApiResponse containing the result of the operation.
Remove an existing Transaction from the system.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Security token to use. |
| orderID | int | The Order.ID of the Transactions parent Order. |
| transactionID | int | The Transaction.ID of the Transaction to remove. |
An ApiResponse containing the result of the operation.
Add a voucher to an order.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Security token to use. |
| orderID | int | The ID for the order to add the voucher to. |
| value | Decimal | The vouchers value specified in the currency of its parent Order. |
| recipientFirstName | String | The voucher recipients first name. |
| recipientLastName | String | The voucher recipients last name. |
| recipientEmail | String | The voucher recipients email address. |
| senderName | String | The name of the voucher's sender. |
| message | String | The message that is to be included with the voucher. |
| deliveryDate | DateTime | The date that the voucher is to be sent to the recipient. |
An IntegerArrayApiResponse containing the new voucher ID
The Order referenced by the orderID must be at OrderStatus.Initiated.
Deletes a voucher.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Security token to use. |
| voucherID | int | The voucher's ID |
An ApiResponse containing the result of the operation.
Assigns a customer to an order. The order is updated with the customers address details. Order must be at status Initiated.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Security token to use. |
| orderID | int | Order ID. |
| customerID | int | Customer ID |
An ApiResponse containing the result of the operation.
Approves an order as not being fraudulent. The order will be advanced to Card Validated for stock fulfillment.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Security token to use. |
| orderID | int | Order ID. |
An ApiResponse containing the result of the operation.
Submits an order to the system for processing.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Security token to use. |
| orderID | int | Order ID. |
An ApiResponse containing the result of the operation.
This method does not handle payment processing - credit card authorisations etc must happen before submitting the order. The order must be at OrderStatus.Initiated. Upon completion, the Order referenced by the orderID will be advanced to the RMProfiler queue (OrderStatus.PendingRiskEvaluation).
Voids an order. An order can be voided at any status.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Security token to use. |
| orderID | int | Order's unique ID |
| voidReasonCode | String | Code representing the reason for the void. This field is optional based on whether void reasons are enabled or not. |
An ApiResponse containing the result of the operation.
An Order can be voided at any status.
Updates the order to be: At Risk of Fraud
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Security token to use. |
| orderID | int | Order ID. |
An ApiResponse containing the result of the operation.
Splits an order.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Security token to use. |
| orderID | int | Order ID. |
| itemQuantityPairs | Collection<IdentifierValuePair<int,int>> | Pairings of order item identifiers and quantities to split. |
An OrderApiResponse containing the resultant split order.
When zero is passed through as the quantity to split, then the entire items quantity will be split off.
If splitting a composite item, only the parent should be marked for splitting which will bring the children with it to the new order. Composite child items themselves cannot be split.
Splits an order item.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Security token to use. |
| orderItemID | int | The order item unique identifier. |
| quantity | int | The quantity to split off from this order item. |
An IntegerArrayApiResponse containing the order item id of the newly split item.
If splitting a composite item, only the parent should be marked for splitting which will bring the children with it to the new order. Composite child items themselves cannot be split.
Contains basic information about the result of a method call, along with an array of Order objects.
| Field Name | Type | Description | Notes |
|---|---|---|---|
| Success | Boolean | Indicates the success or failure of an API method call. | A failure (false) response should contain a failure Code and Message in the respective fields. |
| Code | Integer | A response code for the method call. | |
| Message | String | Message or output from the method call. | |
| Data | Order[] | Array of Order objects returned from the method call. |
Represents an Order
| Name | Type | Description | Notes |
|---|---|---|---|
| ID | int | The internal ID of this order. | |
| Customer | int | The internal ID of the customer for this order. | |
| OrderDate | Nullable<DateTime> | The date that the order was placed. | |
| Phone | String | The phone number for this order. | |
| String | The email address of the customer for this order. | ||
| Status | OrderStatus | The current status of the order. | This is deprecated and is present for backwards compatibility, please use the OrderStatus property instead. This property reflects the value of the OrderStatus property where it is present, or Unknown if the status is not contained within OrderStatus. |
| OrderStatus | Nullable<int> | The current status of the order. The name of this order status can be retrieved using ListAvailableOrderStatuses. | While the two will reflect each other's values, combining the use of this property and Status is discouraged and may yield inconsistent results in rare situations. |
| AdminReference | String | A text field that can hold a reference for use by users. | |
| CustomerReference | String | A text field that can hold a reference for use by customers. | |
| FollowUpDate | Nullable<DateTime> | A date that further action will need to be taken in the processing of the order. | |
| GiftWrapStatus | Boolean | Defines if the order is a gift. Can be used to hide pricing data on the invoice and/or specify that the order should be gift wrapped. | |
| GiftMessage | String | A customised message to the person receiving the order. | |
| DeliveryInstructions | String | Further instructions relating to the delivery of the order. | |
| Currency | String | The ISO 4217 currency code representing the currency for this order. E.g. "NZD" | |
| PaymentMethod | int | A code indicating the type(s) of transactions that will apply to this order. | |
| Freight | Decimal | The standard freight charge for the order excluding tax. | |
| FreightDiscount | Decimal | Any discount applied to the freight charge on the order before tax. | |
| FreightTax | Decimal | The tax charged for the freight on the order. | |
| FreightIncludingTax | Nullable<Decimal> | The standard freight charge for the order including tax. | This field is optional. See notes on ImportOrders. |
| FreightDiscount IncludingTax |
Nullable<Decimal> | Any discount applied to the freight charge on the order after tax. | This field is optional. See notes on ImportOrders. Can be calculated using (FreightDiscount * (1 + tax rate)), or using (FreightDiscount + FreightIncludingTax - Freight - FreightTax). |
| OrderBasedDiscount | Decimal | The total value of any discount applied across the whole order after tax. | |
| OrderBasedDiscount ExcludingTax |
Nullable<Decimal> | The total value of any discount applied across the whole order before tax. | This field is optional. See notes on ImportOrders. |
| OrderTotal | Decimal | The total value of the order, calculated by SUM(OrderItems.UnitNet * OrderItems.Quantity) + Freight - FreightDiscount + FreightTax - OrderBasedDiscount. | |
| AuthCode | String | If a full authorisation is done for the payment on this order the code returned is stored here. | |
| AuthDate | Nullable<DateTime> | If a full authorisation is done for the payment on this order the date that it was done is returned here. | |
| AuthAmount | Nullable<Decimal> | If a full authorisation is done for the payment on this order the amount that was authorised is stored here. | |
| DispatchLocation | String | The dispatch location that this order will be dispatched from. | |
| PreviousDispatchPoints | List<PreviousDispatchPoint> | The history of Dispatch point assignments for this order. | This is audit data that is stored for a length of time determined by the data retention policy (defaulting to 180 days), after which it will be unavailable. |
| FreightProvider | String | The freight provider that will be used to send this order. | |
| CollectionStore | Nullable<int> | The StoreID of the Collection Store for a Click and Collect Order. | If this is populated, it is a Click and Collect order. This is deprecated and just acts as a compatibility layer for the new "CollectionStore" property in ClickAndCollectDetails and is due to be removed from future versions of the API. |
| CollectionDetails | OrderCollectionDetails | The details of the person who has been nominated to collect this order. | This can be used for Click and Collect orders. This is deprecated and just acts as a compatibility layer for the new "NominatedPerson" object in ClickAndCollectDetails and is due to be removed from future versions of the API. |
| ClickAndCollectDetails | ClickAndCollectDetails | The Click and Collect details including nominated person, collection person, collection store and Click and Collect related dates. | This is used for Click and Collect orders. |
| DispatchDate | Nullable<DateTime> | The date that the order was dispatched. | |
| CourierTicket | String | The (first) courier reference for track and trace. | This is deprecated and just acts as a compatibility layer for the new "CourierTickets" property and is due to be removed from future versions of the API. |
| CourierTickets | String[] | The courier references for track and trace. | |
| ParentOrder | Nullable<int> | The ID for the parent of this order. | If an order is created as a result of a split then this field will be automatically populated. In all other cases it will remain blank. |
| OriginalOrder | Nullable<int> | The original order that this order was split from. IE The root node of all orders that are parents to this order. | |
| ChildOrders | int[] | Any child orders that have been created from this order. | |
| Fax | String | The fax number for this order. | |
| DateCreated | DateTime | The date that the order was created. | |
| DateModified | DateTime | The date that this order was last modified. | |
| Website | int | The website that this order was placed on. | |
| FraudProfileXML | String | The XML fraud profile for this order. This data is retrieve only, it can only be updated by RMProfiler. | |
| AllowDiscounts | Boolean | Whether to allow discounts and incentives to be applied to the order. Defaults to true. | |
| ExternalOrderSource | String (100) | The external system from which this order originated. | This field is optional. If supplied, then an ExternalOrderID must also be supplied. |
| ExternalOrderID | String (100) | The identifier for this order in the external system from which this order originated. | This field is optional. If supplied, then an ExternalOrderSource must also be supplied. |
| Addresses | List<CustomerAddress> | The addresses relating to this order. | |
| Notes | List<OrderNote> | Any additional notes to go against this order. | |
| OrderItems | List<OrderItem> | Any order items that are to be included as part of this order. | |
| Vouchers | List<Voucher> | Any vouchers that are to be included as part of this order. | |
| Transactions | List<Transaction> | Any transactions relating to this order. | |
| Attributes | List<NameValuePair> | Additional information attached to this order. | These attributes are arbitrary key-value data pairs stored against an Order. Note that certain attributes may be used to support client-specific custom functionality. Caution is advised when using these attributes. |
| PriorityDescription | String | The priority description for this order. | |
| DeliverToRegistrant | Boolean | Marks the order as to be delivered to registrant. | |
| AdditionalDetails | String | String containing arbitrary additional details. | This field is ignored unless custom processing of this field is required. Expected to contain structured data as XML. |
Represents an item in an order.
| Name | Type | Description | Notes |
|---|---|---|---|
| ID | int | The internal ID of this order item. | |
| OrderID | int | A reference to the order that this order item is associated with. | |
| Title | String | The item Product.Title | |
| Style | String | The item ProductItem.Style | |
| Barcode | String | The item ProductItem.Barcode | |
| PackingInstructions | String | Additional instructions for the packing of this order item. | |
| Quantity | int | The number of units at this price. | |
| QuantityScanned | int | The number of units that have been scanned against this order. | |
| StatusCode | OrderItemStatus | The status of this order item. | |
| Supplier | String | The supplier of this order item. | |
| DateScanned | Nullable<DateTime> | The date that stock was applied to this order item. | |
| UnitPrice | Decimal | The base price for a single unit of this item excluding tax. | |
| UnitDiscount | Decimal | Any discount applied to a single unit of this order item before tax. | |
| UnitTax | Decimal | Tax charged for a single unit of this item. | |
| UnitPriceIncludingTax | Nullable<Decimal> | The base price for a single unit of this item including tax. | This field is optional. See notes on ImportOrders. |
| UnitDiscountIncludingTax | Nullable<Decimal> | Any discount applied to a single unit of this order item after tax. | This field is optional. See notes on ImportOrders. Can be calculated using (UnitDiscount * (1 + tax rate)), or using (UnitDiscount + UnitPriceIncludingTax - UnitPrice - UnitTax). |
| UnitNet | Decimal | The total price for a single order item. This is calculated by the UnitPrice minus the UnitDiscount plus UnitTax. | |
| Parent | int | The internal ID of the parent item if this item is a component of a composite product. Defaulting to 0 otherwise. | |
| ItemCompositeType | ProductCompositeType | Defines the make up of the OrderItem. | |
| ItemInfo | OrderItemInfo | Stores additional order item information. | |
| RegistryItemID | Nullable<int> | Identifies the gift registry item that this order item contributes towards. A null value signifies that this item isn't being purchased towards a gift registry. | Multiple order items on different orders can contribute towards the same gift registry item. Gift registries can be managed using the Gift Registry API. |
| SplitOrderID | Nullable<int> | The ID of the child order if this item has been split. A null value signifies the item is not split. | This field is for retrieval only and is ignored by all import/add/create methods for Orders and OrderItems. |
| AdditionalDetails | String | String containing arbitrary additional details. | This field is ignored unless custom processing of this field is required. Expected to contain structured data as XML. |
Represents additional information stored against an order item.
| Name | Type | Description | Notes |
|---|---|---|---|
| Key | String | The identifier for the type of this order item info. | During OrderItem import and update, key-value pairs are added and updated, but do not get deleted. |
| Value | String | The value for this order item info. |
Represents an assignment to, or removal from, a Dispatch Point.
Note that this data is only retained for a length of time determined by the data retention policy (defaulting to 180 days).
| Name | Type | Description | Notes |
|---|---|---|---|
| DispatchPoint | Nullable<string> | Identifier code for the dispatch point | Null when representing a removal from a dispatch point |
| DateAssigned | DateTime | The time that the order was assigned to, or removed from, the dispatch point. |
Represents a note against an order.
| Name | Type | Description | Notes |
|---|---|---|---|
| ID | int | Unique identifier for the note. | |
| OrderID | int | Reference to the order that the note is related to. | |
| DisplayLevel | int | Defines where the note can be displayed. | |
| DateCreated | DateTime | The date that the note was created. | |
| DateModified | DateTime | The date that the note was last modified. | |
| Note | String | The note's text. | Notes are restricted to 512 characters and will be truncated if necessary. |
| Action | String | The action that was performed. |
Represents a transaction.
| Name | Type | Description | Notes |
|---|---|---|---|
| ID | int | The unique transaction identifier. | |
| TransactionType | PaymentMethod | The payment type of this transaction. | |
| TransactionAmount | Decimal | The total amount of the payment. | |
| TransactionDate | Nullable<DateTime> | The date that the transaction was created. | |
| TransactionStatus | int | Indicates the status of the transaction. | |
| CardNumber | String | The number of the credit card used to pay for this order. Information will be received only. A masked version will be transmitted back to a user of this API. | |
| CardExpiryMonth | String | The expiry month of the credit card used for this transaction. | |
| CardExpiryYear | String | The expiry year of the credit card used for this transaction. | |
| CardType | String | The type of the credit card used for the transaction. | |
| CardName | String | The name on the credit card used for the transaction. | |
| VoucherID | String | The voucher used for this transaction. | |
| GiftCardNumber | String | The gift card used for this transaction. | |
| AccountID | String | The account used for this transaction. |
Represents a voucher.
| Name | Type | Description | Notes |
|---|---|---|---|
| ID | int | A unique identifier for the voucher. | |
| SecurityCode | String | The unique security code for the voucher. | |
| Type | String | The type of the voucher. | |
| BuyersName | String | The name of the customer who is purchasing the voucher. | |
| DeliveryDate | Nullable<DateTime> | The date that the voucher is to be delivered to the recipient. | |
| FirstName | String | The first name of the voucher recipient. | |
| LastName | String | The last name of the voucher recipient. | |
| String | The email address of the voucher recipient. | ||
| CustomerID | String | The Customer Id of the voucher recipient. | |
| Message | String | A message for the recipient to be included with the voucher. | |
| PurchaseValue | Decimal | The monetary value that was assigned to the voucher when purchased. | |
| RemainingValue | Decimal | The amount left available against the gift voucher. | |
| RedeemedValue | Decimal | The amount that has been redeemed against this voucher. | |
| Currency | String | The ISO 4217 currency code representing the currency for this voucher. E.g. "NZD" | |
| PurchaseDate | Nullable<DateTime> | The date that the voucher was purchased. | |
| ExpiryDate | Nullable<DateTime> | The date that the voucher will expire. | |
| VoucherStatus | VoucherStatus | The current status of this voucher. | |
| Notes | List<VoucherNote> | Any administration notes specific to this voucher. |
Represents a note against a voucher.
| Name | Type | Description | Notes |
|---|---|---|---|
| ID | int | Unique identifier for the voucher note. | |
| VoucherID | int | The voucher that this note relates to. | |
| DateCreated | DateTime | The date that the voucher note was created. | |
| Note | String | The voucher note text. |
Represents nominated person information for a Click and Collect order.
This is deprecated and just acts as a compatibility layer for the new "NominatedPerson" object in ClickAndCollectDetails and is due to be removed from future versions of the API.
| Name | Type | Description | Notes |
|---|---|---|---|
| FirstName | string | The first name of the nominated person. | |
| LastName | string | The last name of the nominated person. | |
| Phone | string | The contact phone number of the nominated person. |
Represents collection information for a Click and Collect order.
| Name | Type | Description | Notes |
|---|---|---|---|
| CollectionStore | Nullable<int> | The StoreID of the Collection Store for a Click and Collect Order. | If this is populated, it is a Click and Collect order. |
| NominatedPerson.FirstName | string | The first name of the nominated person. | |
| NominatedPerson.LastName | string | The last name of the nominated person. | |
| NominatedPerson.Phone | string | The contact phone number of the nominated person. | |
| CollectedBy.FirstName | string | The first name of the collection person. | |
| CollectedBy.LastName | string | The last name of the collection person. | |
| CollectedBy.Phone | string | The contact phone number of the collection person. | |
| DateShippedToStore | DateTime | The date that the order was shipped to store. | |
| DateArrivedInStore | DateTime | The date that the order arrived in store. | |
| DateCollected | DateTime | The date that the order was collected from store. | If this is populated, the order is collected and complete. |
Represents the status of an Order in the system.
| Name | Value | Description |
|---|---|---|
| Initiated | 0 | Designates than an order is actively in progress within a shopping cart. |
| Confirmed | 2 | Designates that an order has been confirmed by the purchaser. |
| InProgress | 3 | Designates that an order is in progress. |
| InvalidCardNumber | 4 | Designates that an order has been supplied with an invalid means of obtaining funds. |
| Completed | 7 | Designates that an order has been completed. |
| Cancelled | 8 | Designates than an order has been cancelled. |
| PaymentProcessing | 12 | Designates that an order is currently undergoing payment processing. |
| PaymentProcessingError | 13 | Designates that an order has been unsuccessful in attempting to process payment. |
| ToBePrinted | 21 | Designates that an order is ready to be assigned to a courier. |
| ReadyToDispatch | 22 | Designates that an order is ready to be sent to a customer. |
| PersonaliseItems | 23 | Designates that an order has items which require personalisation. |
| PendingPaymentProcessing | 24 | Designates that an order is waiting for payment processing.. |
| ExportedToExternal | 25 | Designates that an order has been submitted to third party shipping system. |
| ShippedToStore | 26 | Designates that a click and collect order has been shipped to the collection store. |
| ReceivedInStore | 27 | Designates that a click and collect order is ready for collection at the collection store. |
| PendingRiskEvaluation | 30 | Designates than an order is waiting to be risk assessed. |
| PotentiallyFraudulent | 31 | Designates that an order is considered to be at risk of fraud. |
| FraudulentOrder | 32 | Designates that an order is fraudulent. |
| PendingManualPayment | 33 | Designates that this order is awaiting a manual payment from a customer. |
| SendInProgress3PL | 58 | Designates that this order is at send in progress with a third party logistics provider. |
| DispatchInProgress3PL | 59 | Designates that this order at dispatch in progress with a third party logistics provider. |
| SendError3PL | 60 | Designates that this order is at an error state with a third party logistics provider. |
| UpdateError3PL | 61 | Designates that this order failed to receive a dispatch update from a third party logistics provider. |
| OrderSubmitting | 250 | Designates that an order has been submitted. |
| ProcessingMOTO | 251 | Designates that a MOTO sourced order has been submitted. |
Defines an orderitems status in a dispatch system.
| Name | Value | Description |
|---|---|---|
| WaitingToBeOrdered | -2 | The item has not yet been ordered from the supplier. |
| Unordered | -1 | The item has not yet been ordered from the supplier. |
| Ordered | 0 | The item has been ordered from the supplier. |
| Undefined | 1 | The item status is undefined. |
| Backorder | 2 | The item has been ordered from the supplier but will be delayed. |
| Indent | 3 | The item sold is not being held in stock. |
| Deleted | 4 | The item has been removed from the order. |
| SplitToNewOrder | 5 | The item has been removed from this order and assigned to another. |
| Personalise | 6 | Item requires modification for the customer. |
| PartialSplit | 7 | This items quantity has been split into multiple orderitems in this order. |
| PartialSplitToNewOrder | 8 | Part of this items quantity has been removed from this order and assigned to another. |
The payment method of a transaction.
| Name | Value | Description |
|---|---|---|
| None | 0 | This transaction is not associated with any known transaction type. |
| CreditCard | 1 | A credit card transaction. |
| Voucher | 2 | A voucher transaction. |
| Account | 4 | An account transaction. |
| Cheque | 8 | A cheque transaction. |
| CashSale | 20 | A cash sale transaction. |
| BarterCard | 30 | A barter card transaction. |
| External | 35 | An externally sourced transaction which occurred outside of the system. |
| ExternalPayPal | 36 | A externally sourced PayPal transaction which occurred outside of the system. |
| PayPalSaleRefund | 37 | A PayPal sale or refund transaction. |
| PayPal | 38 | A PayPal transaction. |
| EFTPOS | 40 | An EFTPOS transaction. |
| InternetBanking | 50 | An internet banking transaction. |
| NoCharge | 60 | Indicates the buyer will not be charged. |
| DirectCredit | 70 | A direct credit transaction. |
| ExternalPOS | 80 | An external transaction made in a Point of Sale (POS) system. |
| Phone | 90 | A phone transaction. |
| PaymentOnPickUp | 110 | A transaction indicating the buyer will pay at pick up. |
| GiftCard | 120 | A gift card transaction. |
| zipMoney | 200 | A zipMoney transaction. |
| Openpay | 201 | An Openpay transaction. |
| Afterpay | 202 | An Afterpay transaction. |
| eShopWorld | 203 | An eShopWorld transaction. |
| Laybuy | 204 | A Laybuy transaction. |
| Oxipay | 205 | An Oxipay transaction. |
| PaymentExpress | 206 | A Payment Express transaction. |
| Apple Pay | 207 | An Apple Pay transaction. |
| Alipay | 208 | An Alipay transaction. |
| Online EFTPOS | 209 | An Online EFTPOS transaction. |
| ApplePayDirect | 212 | An ApplePay Direct transaction. |
Represents the status of a voucher.
| Name | Value | Description |
|---|---|---|
| Uncomplete | 0 | The initial voucher state. |
| AddedToCart | 1 | The voucher has been added to a cart. |
| PendingValidation | 2 | The voucher is ready to be authorised. |
| Validated | 3 | The voucher has been validated. |
| Allocated | 4 | The voucher has been allocated to a customer. |
| Deleted | 8 | The voucher has been deleted. |
| Processing | 12 | Payment processing is currently in progress for the order associated with this voucher. |
| PendingPayment | 30 | The order associated with this voucher requires payment capture. |
Represents a returned order item.
| Name | Type | Description |
|---|---|---|
| OrderItemID | int | The internal ID of this order item. |
| QuantityReturned | int | The number of units that are being returned. |
| ReasonCode | String | The return reason code. |
| ReasonDescription | String | The return reason description. |
The Orders API returns standard API response codes.