This document outlines the purpose, technology, use cases, methods, objects and examples for using the Delivery API.
This document focuses on the SOAP interface to this API.
The Delivery API provides programmatic access to retrieve delivery and click and collect freight options from the system.
The Delivery 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/delivery.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 Delivery 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 permissions (under iSAMS/API/Delivery) 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 more information can be obtained by contacting eStar.
Available methods are listed below.
Available objects are listed below.
Delivery API usage examples are available. These examples demonstrate the use of the API via a SOAP interface and are available in C#.
See Authenticate.
Retrieves available delivery options for the supplied DeliveryEnquiries.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String | Authentication token to use for this call. |
| enquiries | DeliveryEnquiry[] | An array of delivery enquiries to retrieve delivery options for. |
Returns a DeliveryOptionApiResponse containing the available delivery options for each enquiry.
Supplying multiple DeliveryEnquiry objects will return the available delivery options for each enquiry. The Reference field is used to uniquely identify the available DeliveryOptions for a DeliveryEnquiry. An example of calling GetDeliveryOptions with multiple DeliveryEnquiries is available.
This method does NOT consider product display status or item availability.
All dates and times are in UTC.
Contains information about the result of a method call, along with an array of DeliveryOption 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 | DeliveryOption[] | Array of DeliveryOption objects returned from the method call. | May not be populated if Success is true (for example, if a search returned no results). Will not be populated if Success if false. |
Contains information needed to identify the available delivery options for a set of items to a location.
| Field Name | Type | Description | Notes |
|---|---|---|---|
| Reference | String | A unique identifier for this enquiry in an API call. | Reference is used to identify the DeliveryOptions available for this enquiry in the DeliveryOptionApiResponse. It must be unique within this call, but does not need to be unique between different API calls. Duplicate References within a call will raise an error. |
| State | String | The state to deliver the items to. | |
| Postcode | String | The postcode to deliver the items to. | |
| Country | String | The country to deliver the items to. | Three-letter ISO country code. |
| WebsiteID | Integer | The website to use for freight options and pricing. | Different websites support different freight options and pricing. See WebsiteID for more information. |
| DisplayState | Nullable<Integer> | The display state to use for freight options and pricing. | Optional. If DisplayState is zero or not supplied, the default display state for WebsiteID will be used. |
| DeliveryType | Integer | Restricts the types of the returned delivery options. | Valid values are: 1 - Delivery freight options. 2 - Click and collect freight options. 3 - Both delivery and click and collect freight options. |
| Items | DeliveryEnquiryItem[] | The list of items to deliver to the location. |
The Reference field allows multiple different DeliveryEnquiry objects to be supplied to GetDeliveryOptions in one call. The DeliveryOptions for a DeliveryEnquiry can be easily identified, as the DeliveryOptions will have the same Reference as the DeliveryEnquiry.
An item to retrieve delivery options for.
| Field Name | Type | Description | Notes |
|---|---|---|---|
| Barcode | String | The barcode of the item. | Barcode must exist in the system. |
| Quantity | Integer | The quantity of the item to deliver. | |
| UnitWeight | Nullable<Decimal> | The unit weight of the item. | Optional. If not supplied, the item weight stored in the system will be used. A value of zero will be used if this field is not supplied and the item weight in the system is not set. |
| UnitNet | Nullable<Decimal> | The unit net price of the item. | Optional. If not supplied, the item unit price stored in the system will be used. |
| UnitDiscount | Decimal | The unit discount of the item. | Optional. |
| Properties | NameValuePair[] | Additional information associated with this item. | Optional. Properties may be supplied in the form of arbitrary key-value pairs. This field is ignored when using the standard freight system. Client-specific customisations may use this field to supply additional data for freight calculations. |
Represents a delivery option for a set of items delivered to a specified location in a DeliveryEnquiry.
| Field Name | Type | Description | Notes |
|---|---|---|---|
| Reference | String | The Reference of the originating DeliveryEnquiry. | Maps to a DeliveryEnquiry from the request. Multiple DeliveryOptions may be returned for one DeliveryEnquiry. |
| DeliveryMethod | String | The name of the delivery option. | The freight provider name as configured in the freight administration console. |
| Code | String | The identifying code for the delivery option. | The freight provider code. |
| DeliveryType | Integer | Identifies the type of the delivery option. | Values: 1 - Delivery. 2 - Click and collect. |
| GrossPrice | Decimal | The gross price to charge to the customer. | |
| NetPrice | Decimal | The net price to charge to the customer. Tax-inclusive. | This is the price that the system would charge for this order. |
| Discount | Decimal | The discount on the gross price. | |
| Cost | Decimal | The actual cost to ship the items to the specified location. | |
| Tax | Decimal | The tax charged on the NetPrice. | |
| Status | Integer | The status of the delivery option. | Values: 0 - Ok. 2 - Freight charges have not been configured for this freight provider. 3 - Item weight exceeds freight provider's maximum weight. |
| Priority | Nullable<Integer> | The priority of this delivery option. | Lower Priority values should be displayed ahead of larger values. |
| Properties | NameValuePair[] | Additional information associated with this delivery option. | Additional properties may be returned in the form of arbitrary key-value pairs. This field is currently unused in the standard freight system. Client-specific customisations may return additional data in this field. |
A click and collect delivery option only indicates that the enquiry is eligible for click and collect. It is up to the caller to determine which stores are available for click and collect. The Stores API may be of use.
The Reference field allows multiple different DeliveryEnquiry objects to be supplied to GetDeliveryOptions in one call. The DeliveryOptions for a DeliveryEnquiry can be easily identified, as the DeliveryOptions will have the same Reference as the DeliveryEnquiry.
See NameValuePair.
The Delivery API returns standard API response codes.