This document outlines the purpose, technology, use cases, methods, objects and examples for using the Sales and Returns API.
This particular document focuses on the SOAP interface to this API.
This API provides programmatic access to historical sales and returns data.
The Sales and Returns API exposes 2 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/salesreturns.asmx
This endpoint is enabled for access via SOAP as well as HTTP GET & 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 Sales and Returns API via SOAP uses the Permissions System to allow and deny access to certain users. Use of the API requires a user to be granted the various actions (under iSAMS / API / Orders / Retrieve) to be able to authenticate, and perform the various actions available under this API.
Error handling is primarily left to the caller, however 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 [website url]/logs/api/{Call Identifier}.txt
The available methods are listed below, and link to the relevant details for which arguments are required, and the responses each method provides;
The available objects are listed below, and link to the relevant details for each;
See Authenticate.
Retrieves the Sale referenced by the specified sale ID.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| orderid | Integer | ID of the Sale to retrieve. |
Returns a SaleReturnApiResponse containing an array (of length 1) containing the Sale object for the given sale ID.
Retrieves the set of Sale objects referenced by the specified sale IDs.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| orderIDs | int[] | IDs of the Sale to retrieve. |
Returns a SaleReturnApiResponse containing an array containing the Sale objects for the given sale IDs.
Retrieves the Return referenced by the specified return ID.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| returnID | Integer | ID of the Return to retrieve. Note - This is NOT the order ID. |
Returns a SaleReturnApiResponse containing an array (of length 1) containing the Sale object for the given return ID.
Retrieves the set of Sale objects referenced by the specified return IDs.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| returnIDs | int[] | IDs of the Return to retrieve. Note - These are NOT the order IDs. |
Returns a SaleReturnApiResponse containing an array containing the Sale objects for the given return IDs.
Lists all Sales/Returns in the database.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
Returns a IntegerArrayApiResponse containing an array containing the full list of sale/return order IDs in the database.
Lists the Sales/Returns in the database based on the filters specified.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| exportID | Integer | The sequential id assigned to the sale or return when it is exported. |
| dateFrom | DateTime | Start date, returns orders that have a dispatch date greater than this date. |
| dateTo | DateTime | To date, returns orders that have a dispatch date less than this date. |
| type | String | The type to be returned, can be either "sale" or "return" |
| site | Integer | The specific satellite site id the order was placed on. |
Returns a IntegerArrayApiResponse containing an array containing the sale/return order IDs matching the filters specified.
Trigger the full bulk export of all sale and return data to a set of XML files that can be retrieved via HTTP.
Note: Files generated will be retrievable via https://[siteurl]/data/sales/[filename]
(Where [filename] is provided in the API call response.)
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
Returns an StringArrayApiResponse indicating both the outcome of the call, as well as the list of the files generated.
A sample of an XML-formatted sale and return export is available here.
Trigger the specified bulk export of sale and return data to a set of XML files that can be retrieved via HTTP.
Note: Files generated will be retrievable via https://[siteurl]/data/sales/[filename]
(Where [filename] is provided in the API call response.)
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| orderIDs | int[] | The order IDs of the Sales/Returns to export. |
Returns an StringArrayApiResponse indicating both the outcome of the call, as well as the list of the files generated.
A sample of an XML-formatted sale and return export is available here.
Trigger the full bulk export of all sale and return data to a set of JSON files that can be retrieved via HTTP.
Note: Files generated will be retrievable via https://[siteurl]/data/sales/[filename]
(Where [filename] is provided in the API call response.)
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
Returns an StringArrayApiResponse indicating both the outcome of the call, as well as the list of the files generated.
A sample of an JSON-formatted sale and return export is available here.
Trigger the specified bulk export of sale and return data to a set of JSON files that can be retrieved via HTTP.
Note: Files generated will be retrievable via https://[siteurl]/data/sales/[filename]
(Where [filename] is provided in the API call response.)
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| orderIDs | int[] | The order IDs of the Sales/Returns to export. |
Returns an StringArrayApiResponse indicating both the outcome of the call, as well as the list of the files generated.
A sample of an JSON-formatted sale and return export is available here.
Trigger the full bulk export of all sale and return data to a set of CSV files that can be retrieved via HTTP.
Note: Files generated will be retrievable via https://[siteurl]/data/sales/[filename]
(Where [filename] is provided in the API call response.)
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
Returns an StringArrayApiResponse indicating both the outcome of the call, as well as the list of the files generated.
A sample of an CSV-formatted sale and return export is available here.
Trigger the specified bulk export of sale and return data to a set of CSV files that can be retrieved via HTTP.
Note: Files generated will be retrievable via https://[siteurl]/data/sales/[filename]
(Where [filename] is provided in the API call response.)
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this session. |
| orderIDs | int[] | The order IDs of the Sales/Returns to export. |
Returns an StringArrayApiResponse indicating both the outcome of the call, as well as the list of the files generated.
A sample of an CSV-formatted sale and return export is available here.
Contains basic information about the result of a method call, along with an array of Sale 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 | Sale[] | Array of Sale objects returned for this method call. |
Represents a Sale/Return.
| Field Name | Type | Description | Notes |
|---|---|---|---|
| ExportID | Integer | The internal Export ID for this order. | |
| OrderID | Integer | The internal ID of this order. | |
| ReturnID | Integer | The internal Return ID of this order. | |
| WebsiteID | Integer | The website that this order was placed on. | |
| DisplayStateName | String | The display state this order was placed from. | |
| Type | String | The type of this order. eg. "Sale" or "Return" | |
| DispatchDate | DateTime | The date that the order was dispatched. | |
| Currency | String | The Currency Code representing the currency for any transactions for this order. E.g. "NZD" | |
| CustomerID | Integer | The internal ID of the customer for this order. | |
| CustomerForeignID | String | The external foreign identity for the customer of this order | |
| Addresses | CustomerAddress[] | The addresses relating to this order. | |
| OrderDiscount | Decimal | The total value of any discount applied across the whole order. The discount is applied after tax. | |
| SaleItems | SaleItem[] | Items relating to this order including freight as a line item. | |
| Payments | Payment[] | Any transactions relating to this order. |
Represents a Sale/Return Item.
| Field Name | Type | Description | Notes |
|---|---|---|---|
| Barcode | String | The item barcode (ProductItem.Barcode). | |
| APN | String | The item APN (ProductItem.Style). | |
| Title | String | The item title. | |
| Colour | String | The item colour. | |
| Size | String | The item size. | |
| Quantity | Integer | The number of units at this price. | |
| UnitPrice | Decimal | The base price for a single unit of this item. | |
| UnitDiscount | Decimal | Any discount applied to this item before tax. | |
| UnitTax | Decimal | The tax charged for this item. | |
| UnitNet | Decimal | The total price for a single order item. This is calculated by the UnitPrice minus the UnitDiscount plus UnitTax. | |
| ExtendedNet | Decimal | The total summed price for the order item. This is calculated by the UnitNet * Quantity. | |
| ReturnReasons | ReturnReasons[] | Return Reasons for this Sale/Return item. | |
| StatusCode | OrderItemStatus | The OrderItemStatus of the item. Default value for the freight line is OrderItemStatus.Undefined. | |
| ID | Integer | The internal ID of the item. Default value for the freight line is 0. |
Represents a ReturnReason.
| Field Name | Type | Description | Notes |
|---|---|---|---|
| ID | Integer | The internal ID of this Return Reason. | |
| Description | String | Description for this Return Reason. | |
| ExtraDetail | String | Extra Detail for this Return Reason. |
Represents a Payment.
| Field Name | Type | Description | Notes |
|---|---|---|---|
| ID | Integer | The unique payment identifier. | |
| PaymentType | String | The type of payment. | |
| PaymentAmount | Decimal | The total amount of the payment. | |
| PaymentDate | DateTime | The date that the payment was created. |
Represents an Address. See here for more details.
The Sales and Returns API returns standard API response codes.